> ## 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.

# Rename a group

> PUT /api/v1/chats/:id — change a group chat's display name or icon.

<Note>
  **Auth.** HMAC v1 or bearer token — see [Authentication](/api/authentication).
  **Status.** Live · **Idempotent:** Yes (last write wins).
</Note>

Renames a group chat or sets its group icon. Supplying both fields in one call applies both. The line pinned to this chat handles the operation. Direct messages do not support these fields and return `1006`.

## Request

`PUT /api/v1/chats/{id}`

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT https://console.trychert.com/api/v1/chats/ch_01H... \
    -H "x-chert-tenant: $TENANT" \
    -H "x-chert-signature: v1,$TS,$SIG" \
    -H "content-type: application/json" \
    -d '{
      "display_name": "Acme launch crew",
      "group_chat_icon": "https://cdn.example.com/acme-icon.png"
    }'
  ```

  ```js Node.js theme={null}
  const ts = Math.floor(Date.now() / 1000)
  const body = JSON.stringify({
    display_name: "Acme launch crew",
    group_chat_icon: "https://cdn.example.com/acme-icon.png",
  })
  const sig = crypto.createHmac("sha256", SIGNING_SECRET).update(`${ts}.${body}`).digest("hex")
  const res = await fetch(`https://console.trychert.com/api/v1/chats/${chatId}`, {
    method: "PUT",
    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({
      "display_name": "Acme launch crew",
      "group_chat_icon": "https://cdn.example.com/acme-icon.png",
  })
  sig = hmac.new(SIGNING_SECRET.encode(), f"{ts}.{body}".encode(), hashlib.sha256).hexdigest()
  r = requests.put(
      f"https://console.trychert.com/api/v1/chats/{chat_id}",
      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...",
      "display_name": "Acme launch crew",
      "group_chat_icon": "https://cdn.example.com/acme-icon.png",
      "is_group": true
    }
  }
  ```
</ResponseExample>

### Path parameters

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

### Body

<ParamField body="display_name" type="string">
  New display name for the group. Trimmed; must be non-empty if present.
</ParamField>

<ParamField body="group_chat_icon" type="string">
  HTTPS URL of the new group icon image.
</ParamField>

### Response fields

<ResponseField name="chat" type="object">
  Refreshed chat object with the updated `display_name` and `group_chat_icon` fields.
</ResponseField>

## Errors

| Code   | HTTP | When                                                                     |
| ------ | ---- | ------------------------------------------------------------------------ |
| `1004` | 400  | Invalid JSON body.                                                       |
| `1006` | 400  | Chat is a direct message — only group chats support display name + icon. |
| `2002` | 404  | Chat not found.                                                          |
| `4001` | 502  | Delivery failed (rename or icon update was rejected).                    |
| `4099` | 501  | Group is missing its chat key or has no pinned line.                     |

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

## See also

* [Add a participant](/api/group-chats/add-participant)
* [Create a group](/api/group-chats/create)