> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuco.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Group Chat

> Start a new iMessage group chat from one of your Tuco lines: pick the people, optionally name it, and send the first message. Bearer-token auth, JSON.

## What this endpoint does

It starts a **new iMessage group** from one of your lines and sends the first message into it.
In iMessage a group is created by sending its first message, so `message` is required.

After that the group works like any other group your line is in:

* send into it with [Send to a Group Chat](https://docs.tuco.ai/api-reference/endpoint/send-group-message.md)
* it shows in the Unibox and in [List Conversations](https://docs.tuco.ai/api-reference/endpoint/conversations.md#group-chats)
* members' replies come back as [`group.message.*` webhooks](https://docs.tuco.ai/api-reference/message-webhooks#group-chat-events)

> [!NOTE]
>
> **Everyone must be on iMessage.** Tuco checks each person before anything is sent. If anyone
> isn't on iMessage, nothing is sent and you get `MEMBER_NOT_IMESSAGE` with their number.
> Groups never fall back to SMS.

## Authentication

Pass your workspace API key as a Bearer token.

```bash theme={null}
Authorization: Bearer tuco_xxxxxxxxxxxxx
```

## Request body

| Field | Type | Required | What it is |
| - | - | - | - |
| `members` | string\[] | Yes | 2 to 31 people: phone numbers in E.164 (`+13025550100`) or email addresses (Apple IDs). Duplicates and your own line are removed. |
| `message` | string | Yes | The first message, up to 5,000 characters, text only. Send files after with [Send to a Group Chat](https://docs.tuco.ai/api-reference/endpoint/send-group-message.md). |
| `name` | string | No | The group's name, up to 100 characters. Shown on everyone's phone. |
| `lineId` | string | Only if you have more than one line | Which line starts the group. Get ids from [List Lines](https://docs.tuco.ai/api-reference/endpoint/get-lines.md). The line needs group-chat support (every Tuco-hosted line has it). |
| `idempotencyKey` | string | No | Recommended. A retry with the same key gets the first result back instead of starting a second group. Also accepted as the `Idempotency-Key` header. |

## Example

```bash cURL theme={null}
curl -X POST "https://app.tuco.ai/api/unibox/create-group" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: q4-deal-room-1" \
  -d '{
    "lineId": "6a42688ad3aeb6d18286686c",
    "members": ["+13025550100", "sam@example.com"],
    "name": "Q4 Deal Room",
    "message": "Hi both, starting a thread for the Q4 deal."
  }'
```

```javascript Node.js theme={null}
const res = await fetch('https://app.tuco.ai/api/unibox/create-group', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer tuco_xxxxxxxxxxxxx',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'q4-deal-room-1',
  },
  body: JSON.stringify({
    lineId: '6a42688ad3aeb6d18286686c',
    members: ['+13025550100', 'sam@example.com'],
    name: 'Q4 Deal Room',
    message: 'Hi both, starting a thread for the Q4 deal.',
  }),
});
const data = await res.json();
// data.conversationId → use it with /api/unibox/send-group
```

```python Python theme={null}
import requests

res = requests.post(
    "https://app.tuco.ai/api/unibox/create-group",
    headers={
        "Authorization": "Bearer tuco_xxxxxxxxxxxxx",
        "Idempotency-Key": "q4-deal-room-1",
    },
    json={
        "lineId": "6a42688ad3aeb6d18286686c",
        "members": ["+13025550100", "sam@example.com"],
        "name": "Q4 Deal Room",
        "message": "Hi both, starting a thread for the Q4 deal.",
    },
)
print(res.json()["conversationId"])
```

## Response

```json 200 theme={null}
{
  "success": true,
  "conversationId": "group:iMessage;+;chat52247337719921698",
  "chatGuid": "iMessage;+;chat52247337719921698",
  "messageId": "6b00b219fb16ed81dc80d3e7",
  "members": ["+13025550100", "sam@example.com"],
  "newConversationsCounted": 2,
  "existingGroup": false,
  "name": "Q4 Deal Room",
  "nameApplied": true
}
```

| Field | What it means |
| - | - |
| `conversationId` | The group's id. Use it with [Send to a Group Chat](https://docs.tuco.ai/api-reference/endpoint/send-group-message.md) and in the Unibox. When you put it in a URL (`?conversation=`), URL-encode it: the `+` must be `%2B`. |
| `newConversationsCounted` | How many of the line's daily new-conversation slots this used (see below). |
| `existingGroup` | `true` when these exact people already had a group with this line. iMessage reuses that group instead of making a second one (same as on an iPhone), and your message went into it. Add or remove someone to start a new group. |
| `nameApplied` | Only when you sent `name`. `false` means the group was created but the name didn't apply; `nameError` says why. Nothing else is affected. |

## Daily limits

A group counts against your line's **new conversations per day** limit:

* each person this line has **never messaged** (1:1 or in a group) uses 1 slot
* people the line has messaged before use none
* the first message counts as 1 message toward the daily message limit

All slots are taken together or not at all. If the line doesn't have room for everyone new,
nothing is sent and you get `LINE_NEW_CONVERSATION_LIMIT`.

Example, a group of you + 2 people: both never messaged → 2 slots; one messaged before → 1 slot.

## Errors

Nothing is sent on any of these unless the table says otherwise.

| HTTP | `code` | What happened | What to do |
| - | - | - | - |
| 400 | `MESSAGE_REQUIRED` | No first message. | Add `message`: the group is created by sending it. |
| 400 | `MESSAGE_TOO_LONG` | Over 5,000 characters. | Shorten it. |
| 400 | `TOO_FEW_MEMBERS` | Fewer than 2 other people (after removing duplicates and your own line). | For one person, send a normal message instead. |
| 400 | `TOO_MANY_MEMBERS` | More than 31 people. | Use fewer people. |
| 400 | `INVALID_MEMBER` | A member isn't a phone number or an email. | Fix the entries listed in `invalid`. |
| 400 | `MEMBER_NOT_IMESSAGE` | These people aren't on iMessage (listed in `members`). | Remove them, or text them 1:1. |
| 503 | `MEMBER_CHECK_FAILED` | The iMessage check didn't answer for these people. | Try again in a minute. |
| 400 | `NAME_TOO_LONG` / `INVALID_NAME` | `name` is over 100 characters or isn't text. | Fix `name`. |
| 400 | `LINE_ID_REQUIRED` | You have more than one line and didn't pass `lineId`. | Pass `lineId` (some of your lines are listed in `lines`). |
| 404 | `LINE_NOT_FOUND` | That line isn't in your workspace. | Check `lineId`. |
| 409 | `LINE_NOT_READY` / `NO_USABLE_LINE` | The line is paused, its device is down, or it can't create groups. | Use another line, or check the line on the Lines page. |
| 429 | `LINE_NEW_CONVERSATION_LIMIT` | Not enough new-conversation room left today (`slotsLeft`, `newMembers`). | Use fewer new people, another line, or try tomorrow. |
| 502 | `CREATE_FAILED` | The device refused to create the group. Nothing was sent and no slots were used. | Check the line is up, then try again. |
| 504 | `CREATE_UNCONFIRMED` | The device didn't answer in time. The group **may still have been created**. | Don't retry with a new key. Check the Unibox in a few minutes; a retry with the **same** idempotency key gets the group once it's confirmed. |

## Webhooks and CRM

* The first message fires [`group.message.sent`](https://docs.tuco.ai/api-reference/message-webhooks#group-chat-events), exactly once.
* If your workspace has a CRM connected, the message is logged on each member's contact, and a contact is created for anyone the CRM doesn't have. See [Group chats in your CRM](https://docs.tuco.ai/api-reference/endpoint/conversations.md#group-chats-in-your-crm).

## What you can't do

| | |
| - | - |
| Add or remove members, or rename later | Not from Tuco yet. Anyone in the group can do it from their phone. |
| Start a group from a line without group-chat support | Pick another line. |
| Two groups with exactly the same people on one line | iMessage reuses the existing group (`existingGroup: true`). |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.