---
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!" }
      ]
    }
  }'
```

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:

- [cURL](#tab-panel-20)
- [TypeScript](#tab-panel-21)
- [Python](#tab-panel-22)
- [Go](#tab-panel-23)

Terminal window

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

```
await client.chats.update({chatId}, {
  display_name: "Team Discussion",
  group_chat_icon: "https://example.com/group-icon.png",
});
```

```
client.chats.update(
    {chat_id},
    display_name="Team Discussion",
    group_chat_icon="https://example.com/group-icon.png",
)
```

```
client.Chats.Update(context.TODO(), {chatId}, linq.ChatUpdateParams{
  DisplayName: linq.F("Team Discussion"),
  GroupChatIcon: linq.F("https://example.com/group-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).