# Update community bot profile

Change the name and avatar that your community's bot shows next to its messages.

- Endpoint: `PUT https://api.returning.ai/v1/community-bot`
- Section: Community / Appearance
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `appearance` (Shown in the dashboard as "Appearance")
- Retries: Safe to repeat; the same values give the same result
- Guide: hand-written
- Verified: code, 2026-09-27
- Last updated: 26 Sep 2026
- Web page: https://docs.returning.ai/api-reference/community-appearance/update-community-bot-profile

## When to use this

- You rebrand the bot so its messages carry your brand's name and logo.
- You set the bot's look from your own admin tools instead of the dashboard.
- You want to remove a custom avatar and go back to none.

**Instead:** Use [Update community theme colors](https://docs.returning.ai/api-reference/community-appearance/update-community-theme-colors.md) instead to change the community's colours, logos and loading animation.

## Authentication

- Header: `Authorization: Bearer <API_KEY>`
- Permission: `appearance`

Use a Community API key with `appearance`, and keep it on your server. The key decides the community, so never send a community ID. The published path lacks `/v1`: call `PUT /v1/community-bot`, because `PUT /community-bot` returns `404`.

## Behaviour

Send only the fields you want to change; a field you leave out keeps its value. The bot's messages show the new name and avatar straight away, including for members who are online. Traders aren't notified.

`avatar` must point at an image file. Host it yourself, or use a URL from Upload message images. Send `null` to remove the avatar.

## Request

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Community API key with `appearance`. (`Bearer <API_KEY>`) |
| `Content-Type` | `string` | Yes | Request body format. (`application/json`) |

### Body

Send a JSON object with `name`, `avatar` or both. An empty object, or any other field, is rejected with `400`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | No | The bot's display name. Leading and trailing spaces are removed. (1-32 characters) |
| `avatar` | `string` | No | The bot's avatar image, or `null` to remove it. An `https` or `http` URL, or a path starting with `/assets/files/`, ending in `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp` or `.svg`. (Image URL or path, max 2048 chars; nullable) |

### Example request

```bash
curl --request PUT \
  --url https://api.returning.ai/v1/community-bot \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Sample Broker Bot",
    "avatar": "https://cdn.example.com/brand/bot-avatar.png"
  }'
```

## Response

A `200` returns the whole bot profile after the change in `data`.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `meta` | `object` | always | - |
| `meta.status` | `string` | always | Result of the request. (`success`) |
| `meta.statusCode` | `integer` | always | The HTTP status, repeated. (`200`) |
| `message` | `string` | always | Human-readable summary. Do not branch on it. |
| `data` | `object` | always | The bot profile after the change. |
| `data._id` | `string` | - | The bot profile's ID. |
| `data.communityID` | `string` | - | Your community's ID. |
| `data.name` | `string` | - | The bot's display name. `Bot` until you set one. |
| `data.avatar` | `string` | - | The avatar image URL or path, or `null`. |
| `data.createdAt` | `string` | - | When the bot profile was created. |
| `data.updatedAt` | `string` | - | When the bot profile last changed. |

### Example response (200)

```json
{
  "meta": {
    "status": "success",
    "statusCode": 200
  },
  "message": "Update community bot success.",
  "data": {
    "_id": "66f000000000000000000a02",
    "communityID": "66f000000000000000000010",
    "name": "Sample Broker Bot",
    "avatar": "https://cdn.example.com/brand/bot-avatar.png",
    "createdAt": "2026-09-20T08:30:00.000Z",
    "updatedAt": "2026-09-26T08:30:00.000Z"
  }
}
```

## Errors

Every error carries `meta.status` and `meta.statusCode`, with the reason in `detail`. Key errors and field validation errors also carry `meta.code`; the empty-body `400` and the `500` and `502` errors don't.

### Fix the request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | - | The body is empty or isn't a JSON object (`detail.body` is `Request body must be a non-empty object`). Send `name`, `avatar` or both. This error has no `meta.code`. |
| 400 | `VALIDATION_FAILED` | A field breaks its rule, such as a `name` over 32 characters or an `avatar` that isn't an image URL, or the body has a field other than `name` and `avatar`. `detail` names it. Nothing changed. |
| 401 | `AUTH_API_KEY_REQUIRED` | No key was sent. Send `Authorization: Bearer <API_KEY>`. |
| 401 | `AUTH_API_KEY_INVALID` | The key is unknown, expired or malformed. Use a current Community API key. |
| 403 | `AUTH_PERMISSION_REQUIRED` | The key lacks `appearance`. Add the permission in Settings > Integration > API Keys. |

### Fix the data

| Status | Code | What to do |
| --- | --- | --- |
| 404 | - | The community that owns this key no longer exists. Contact Returning.AI support. |

### Retry with backoff

| Status | Code | What to do |
| --- | --- | --- |
| 500 | - | The change failed unexpectedly. Retry with backoff; sending the same values again is safe. |
| 502 | - | The change couldn't be completed just now (`Upstream service is temporarily unavailable.`). Retry with backoff. |
| 401 | `AUTH_API_KEY_VALIDATION_FAILED` | The key could not be checked just now. Retry with backoff; the key itself may be fine. |

**Retries:** Sending the same values twice gives the same result, so a retry after a timeout, a `500` or a `502` is safe. Use bounded exponential backoff. Over the [rate limit](https://docs.returning.ai/how-it-works.md#rate-limits), requests return `429`; wait for the window to reset, then retry.

## Next step

- [Update community theme colors](https://docs.returning.ai/api-reference/community-appearance/update-community-theme-colors.md): `PUT /v1/appearance`. Match the community's colours and logos to the bot's new look.