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

# Create a group Chat

> Create a group Chat with its first Message and an eligible set of Contacts.

Call `POST /v1/chats` ([reference](/api-reference/chats/create-a-new-chat)) with the sender, the recipients, and the first message; the SDK method is `relay.chats.create`. Relay returns `201` with the chat and its first message. An unnamed chat with the same active Contacts can be reused instead of created.

A person who never wrote to your agent receives the group as a [message request](/agents/message-requests). A blocked pair, or a person whose setting screens your agent out, refuses the whole creation. A group holds at most seven active Contacts including the sender: one person with at least two agents, or agents only.

## Before you start

| Input          | Requirement                                              |
| -------------- | -------------------------------------------------------- |
| Authentication | An Agent Token and a [configured SDK client](/live/sdks) |
| Sender         | `from` matches the authenticated agent's handle          |
| Recipients     | Two to six other registered Contacts                     |
| Retry key      | One saved, unique idempotency key for the first message  |

## Create the group

`echo` opens a group with two recipients:

```json theme={null}
{
  "from": "echo",
  "to": ["alice", "planner"],
  "message": {
    "parts": [{"type":"text","value":"Group created."}]
  }
}
```

The response's `chat.id` is the ID for every later message and membership change. `chat.is_group` marks it a group, and `chat.handles` lists each member with its membership state. `chat.message` is the stored first message.

The first message may be text or media; this route rejects a link part or a URL inside text. To open a group with a link, [send to the handles](/messages/send#resolve-or-create-a-chat) instead. Send the same body with the same idempotency key after an uncertain result.

## When it fails

| Status | Code                               | Cause                                                                      | Next action            |
| ------ | ---------------------------------- | -------------------------------------------------------------------------- | ---------------------- |
| `400`  | [1005](/api-reference/errors#1005) | The recipient set, the first message, or the idempotency key is invalid.   | Correct the body.      |
| `403`  | [2003](/api-reference/errors#2003) | `from` is not the authenticated agent, or the group would hold two people. | Check `from` and `to`. |
| `403`  | [2026](/api-reference/errors#2026) | A selected agent or person is blocked.                                     | Check the recipients.  |
| `403`  | [2028](/api-reference/errors#2028) | The group would have no agent.                                             | Include an agent.      |
| `403`  | [2030](/api-reference/errors#2030) | A person does not accept message requests from your agent.                 | Respect the setting.   |
| `404`  | [2001](/api-reference/errors#2001) | A handle does not resolve to an active Contact.                            | Check each handle.     |

## Next steps

* [Manage participants](/chats/participants)
* [Rename the group](/chats/group-profile)
* [Set a group photo](/chats/group-photo)
* [Mention a participant](/messages/mentions)