---
title: Group Chats | API Docs
description: Create and manage group conversations with multiple participants.
---

Group chats allow you to create conversations with three or more participants. They support display names, icons, and participant management. See the [Chats API Reference](/api/resources/chats/index.md) for the full endpoint specification.

> **Note:** [Typing indicators](/guides/chats/typing-indicators/index.md), delivery receipts, and read receipts are **not supported** in group chats. These features only work in one-to-one conversations.

## Creating a group chat

Create a group by sending a message to multiple recipients:

Terminal window

```
curl -X POST https://api.linqapp.com/api/partner/v3/chats \
  -H "Authorization: Bearer $LINQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+12223334444",
    "to": ["+15556667777", "+18889990000"],
    "message": {
      "parts": [
        { "type": "text", "value": "Welcome to the group!" }
      ]
    }
  }'
```

```
const chat = await client.chats.create({
  from: '+12223334444',
  to: ['+15556667777', '+18889990000'],
  message: {
    parts: [{ type: 'text', value: 'Welcome to the group!' }],
  },
});
```

```
chat = client.chats.create(
    from_="+12223334444",
    to=["+15556667777", "+18889990000"],
    message={
        "parts": [{"type": "text", "value": "Welcome to the group!"}]
    },
)
```

A few constraints on this request:

- The first outbound message must not contain links. `link` parts and text parts containing URLs are rejected on `POST /v3/chats` — send the initial message without links, then follow up with a [link preview](/guides/messaging/rich-link-previews/index.md) using the returned chat ID.
- A chat’s `to` array supports a maximum of **31 recipients**. SMS/MMS group chats are additionally limited by carrier settings — most carriers cap group texts at around **20 participants**, and some restrict this to as few as **10**. Plan for the stricter of the two when delivery falls back to SMS/MMS.

## Updating group details

Set a display name and icon for the group. Only available for group conversations:

Terminal window

```
curl -X PUT https://api.linqapp.com/api/partner/v3/chats/{chat_id} \
  -H "Authorization: Bearer $LINQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Project Team",
    "group_chat_icon": "https://cdn.example.com/team-icon.png"
  }'
```

```
await client.chats.update(chatId, {
  display_name: 'Project Team',
  group_chat_icon: 'https://cdn.example.com/team-icon.png',
});
```

```
client.chats.update(
    chat_id,
    display_name="Project Team",
    group_chat_icon="https://cdn.example.com/team-icon.png",
)
```

> **Note:** `group_chat_icon` is a publicly accessible HTTPS URL to the icon image. Updating display names and icons only works for group chats ([error code `1006`](/error/codes/1xxx/1006/index.md) is returned for direct messages). See the [Update Chat](/api/resources/chats/methods/update/index.md) endpoint for the full request schema.

## Managing participants

> **Note:** Managing participants is currently supported for iMessage group chats only.

### Adding a participant

Add a phone number or email to an existing group chat. See the [Add Participant API reference](/api/resources/chats/subresources/participants/methods/add/index.md).

### Removing a participant

Remove a participant by handle. See the [Remove Participant API reference](/api/resources/chats/subresources/participants/methods/remove/index.md).

> **Important:** Groups must always have at least 3 members. You cannot remove a participant if it would drop below this minimum.

## Leaving a group chat

Remove your own phone number from a group conversation. See the [Leave Chat API reference](/api/resources/chats/methods/leave_chat/index.md).

> **Important:** Groups must always have at least 3 members. You cannot leave a group if it would drop below this minimum.

Once you leave, you can no longer access the chat unless an active participant adds you back. Recreating a chat with the same set of participants will create a new, separate chat. A [`participant.removed`](/api/resources/webhooks/index.md) webhook fires once the leave has been processed.

For the webhook events that fire on chat creation, group updates, and participant changes, see [Webhook Events → Chat events](/guides/webhooks/events#chat-events/index.md).