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

# Group Chats

> Create a Relay group Chat and update its name or photo.

A group Chat has at least three and at most 32 active Contacts.

## Create a group

`POST /v1/chats` accepts 2 to 31 recipient Handles plus the sender.

<CodeGroup>
  ```typescript TypeScript SDK theme={null}
  const group = await relay.chats.create({
    from: "echo.acme",
    to: ["alice", "bob"],
    message: {
      parts: [{ type: "text", value: "Group created." }],
      idempotency_key: crypto.randomUUID(),
    },
  });
  ```

  ```bash cURL theme={null}
  curl -sS -X POST https://api.relayapp.im/v1/chats \
    -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
    -d '{
      "from":"echo.acme",
      "to":["alice","bob"],
      "message":{
        "parts":[{"type":"text","value":"Group created."}]
      }
    }'
  ```
</CodeGroup>

## Limits

* A group starts with the sender plus 2 to 31 recipient Contacts.
* A group has at most 32 active Contacts.
* Removing or leaving must keep at least three active Contacts.

## Rename the group

<CodeGroup>
  ```typescript TypeScript SDK theme={null}
  await relay.chats.update(chatId, {
    display_name: "Weekend plans",
  });
  ```

  ```bash cURL theme={null}
  curl -sS -X PUT "https://api.relayapp.im/v1/chats/$CHAT_ID" \
    -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"display_name":"Weekend plans"}'
  ```
</CodeGroup>

## Set a group photo

Upload an image Attachment, then pass its ID:

<CodeGroup>
  ```typescript TypeScript SDK theme={null}
  await relay.chats.update(chatId, {
    group_chat_icon: attachmentId,
  });
  ```

  ```bash cURL theme={null}
  curl -sS -X PUT "https://api.relayapp.im/v1/chats/$CHAT_ID" \
    -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"group_chat_icon":"01993d50-d263-7d6b-87ce-90aba89b7815"}'
  ```
</CodeGroup>

Relay accepts only a completed image Attachment owned by the acting Contact.
The Chat response returns a signed URL, not the Attachment ID.

## Group metadata events

| Event                     | Meaning             |
| ------------------------- | ------------------- |
| `chat.group_name_updated` | Group name changed  |
| `chat.group_icon_updated` | Group photo changed |

Membership changes have their own routes, visibility rules, and events.

## Related

* [Participants and Membership](/guides/chats/participants)
* [Typing Indicators](/guides/chats/typing-indicators)
* [Mentions](/guides/messaging/mentions)
* [Delivery Receipts](/guides/messaging/delivery-receipts)