# Send a typing indicator

`POST /chat.typing`

## Description

Notify other chat participants that you are working on a response.
If they have the chat open, they will see "(Bot name) is typing...".

The indicator lasts **6 seconds**. Re-send every **5 seconds** to keep
it visible while you work. Longer gaps will let it expire between pings.

**Destination options (mutually exclusive):**
- `chatId` - Send to an existing chat by its ID
- `groupId` - Send to a group channel
- `userIds` - Send to a DM or Multi-DM with the specified users

**Custom sender (optional):** pass `sender.id` to show the indicator as a
[configured bot persona](/docs/guides/sender-profiles) — the persona's
configured name and avatar are used. Only `id` is accepted; `name` and
`imageUrl` are rejected on this endpoint. Selection is lookup-only: an id
that doesn't match a configured persona is accepted and ignored, and the
indicator shows the app's own identity (same for an omitted, empty, or `_`
id). Personal access tokens reject `sender` entirely.

**Required scope:** `chat:send_message` or `chat:write`

---

**OpenAPI Spec:** [chat-v1.json](https://developer.ro.am/chat-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Request Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `chatId` | string | No | Send to an existing chat by ID (mutually exclusive with groupId/userIds) |
| `groupId` | string | No | Send to a group channel (mutually exclusive with chatId/userIds) |
| `userIds` | string[] | No | Send to a DM or Multi-DM with these users (mutually exclusive with chatId/groupId) |
| `threadTimestamp` | integer | No | Timestamp of the message being replied to. |
| `sender` | object | No | Optional configured bot persona to show the indicator as. Only `id` is accepted — `name` and `imageUrl` are rejected on this endpoint. Personal access tokens reject this field entirely. See the [Sende |

**sender**:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | No | Code of a configured bot persona (lookup-only; never creates one). Ids that don't match a configured persona are accepted and ignored.  |

## Responses

### 200 - Typing indicator successfully sent

### 400 - Bad request. Common causes:
- No destination specified (chatId, groupId, or userIds required)
- Multiple destinations specified (only one allowed)
- `sender.name` or `sender.imageUrl` provided (not supported on typing)
- Personal access token provided a `sender` field


### 401 - Presented invalid authentication credentials.

### 405 - An unsupported method was requested.

### 500 - An internal error occurred.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/api/chat-typing*