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

# Add a participant

> POST /api/v1/chats/:id/participants — add a phone number or email to a group chat.

<Note>
  **Auth.** HMAC v1 or bearer token — see [Authentication](/api/authentication).
  **Status.** Live · **Idempotent:** Effectively yes — adding the same address twice is a no-op.
</Note>

Adds a phone number or email handle to an existing iMessage group chat. The line pinned to this chat handles the operation. Direct messages return `1006`.

## Request

`POST /api/v1/chats/{id}/participants`

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://console.trychert.com/api/v1/chats/ch_01H.../participants \
    -H "x-chert-tenant: $TENANT" \
    -H "x-chert-signature: v1,$TS,$SIG" \
    -H "content-type: application/json" \
    -d '{"address": "+14155551234"}'
  ```

  ```js Node.js theme={null}
  const ts = Math.floor(Date.now() / 1000)
  const body = JSON.stringify({ address: "+14155551234" })
  const sig = crypto.createHmac("sha256", SIGNING_SECRET).update(`${ts}.${body}`).digest("hex")
  const res = await fetch(
    `https://console.trychert.com/api/v1/chats/${chatId}/participants`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-chert-tenant": TENANT_SLUG,
        "x-chert-signature": `v1,${ts},${sig}`,
      },
      body,
    },
  )
  ```

  ```python Python theme={null}
  import hmac, hashlib, json, time, requests
  ts = int(time.time())
  body = json.dumps({"address": "+14155551234"})
  sig = hmac.new(SIGNING_SECRET.encode(), f"{ts}.{body}".encode(), hashlib.sha256).hexdigest()
  r = requests.post(
      f"https://console.trychert.com/api/v1/chats/{chat_id}/participants",
      headers={
          "Content-Type": "application/json",
          "x-chert-tenant": TENANT_SLUG,
          "x-chert-signature": f"v1,{ts},{sig}",
      },
      data=body,
  )
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "chat_id": "ch_01H...",
    "added": "+14155551234",
    "participants": ["+14155550100", "+14155550200", "+14155551234"]
  }
  ```
</ResponseExample>

### Path parameters

<ParamField path="id" type="string" required>
  Chat identifier (`ch_…`).
</ParamField>

### Body

<ParamField body="address" type="string" required>
  E.164 phone number or email address to add to the group. `handle` is accepted as an alias.
</ParamField>

### Response fields

<ResponseField name="chat_id" type="string">
  The chat the participant was added to.
</ResponseField>

<ResponseField name="added" type="string">
  The address that was added (echoed back, normalized).
</ResponseField>

<ResponseField name="participants" type="string[]">
  Full participant roster after the add.
</ResponseField>

## Errors

| Code   | HTTP | When                                                                     |
| ------ | ---- | ------------------------------------------------------------------------ |
| `1001` | 400  | `address` missing.                                                       |
| `1006` | 400  | Chat is a direct message — participants endpoint only applies to groups. |
| `2002` | 404  | Chat not found.                                                          |
| `4001` | 502  | Delivery failed (add participant was rejected).                          |
| `4099` | 422  | Group is missing its chat key or has no pinned line.                     |

See the full [error code reference](/api/errors).

## See also

* [Remove a participant](/api/group-chats/remove-participant)
* [Rename a group](/api/group-chats/rename)
* [Leave a group](/api/group-chats/leave)
* [Create a group](/api/group-chats/create)