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

# Chats

> Send messages to a bot and read its replies.

A chat is called a **thread** in the API. Every thread procedure takes exactly one of these to say which chat:

| Field | The chat |
| - | - |
| `botId` | The bot's own chat. |
| `groupId` | A group chat. |
| `externalConversationId` | One of a bot's other chats: a routine's chat or a channel conversation. |

## threads/send

`POST /rpc/threads/send` posts a message. In a bot's chat, it starts a run (or steers the one in progress).

**botId | groupId | externalConversationId** `string` *required*

The chat.

**text** `string`

The message. Required unless you attach files.

**artifactIds** `string[]`

Up to 4 uploaded files to attach. Upload with `artifacts/create` first.

**mentions** `array`

Mentions, as `{ "kind": "bot" | "group" | "routine" | "connector", "id": "..." }`.

**replyToMessageId** `string`

The message you are replying to.

**replyQuote** `string`

The part of that message you are quoting. Needs `replyToMessageId`.

**clientNonce** `string`

A unique value per message. Retrying with the same nonce does not post twice.

```bash theme={null}
curl -s "$CADENCE_URL/rpc/threads/send" \
  -H "Authorization: Bearer $CADENCE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json": {"botId": "YOUR_BOT_ID", "text": "What did we sell yesterday?", "clientNonce": "c0b7a1f2"}}'
```

```json theme={null}
{ "json": { "taskId": "...", "runId": "...", "seq": 118 } }
```

**runId** `string | null`

The run that will answer. Null only in a group when nobody is asked to answer.

**seq** `number`

The position of your message in the chat.

**runIds** `string[]`

In a group, every run that started.

## threads/messages

`POST /rpc/threads/messages` returns a page of messages, newest last.

**botId | groupId | externalConversationId** `string` *required*

The chat.

**before** `number`

Return messages before this `seq`, to page back.

## threads/subscribe

Streams the chat's events live. See [Streaming](https://docs.usecadence.gg/api/streaming.md).

## threads/answer

`POST /rpc/threads/answer` answers a question or [approval](https://docs.usecadence.gg/work/approvals.md) card the bot posted.

**botId | groupId | externalConversationId** `string` *required*

The chat.

**runId** `string` *required*

The run that asked.

**messageId** `string` *required*

The card's message id.

**answer** `string` *required*

Your answer, or the option you chose.

## Other thread procedures

| Procedure | Effect |
| - | - |
| `threads/get` | The chat with its recent messages. |
| `threads/head` | The chat's id and its latest `seq`, to start a subscription. |
| `threads/stop` | Stops the run in progress. |
| `threads/editMessage` | Edits your message; the chat rewinds and the bot answers again. Returns a `rewindId`. |
| `threads/undoRewind` | Undoes an edit, given its `rewindId`. |
| `threads/react` | Adds a reaction to a message. |
| `threads/clear` | Clears a bot's or group's chat. |
| `threads/markRead`, `threads/markUnread` | Read state. |

## Attach a file

Upload first with `artifacts/create`, then pass the returned `id` in `artifactIds`.

**botId | groupId** `string` *required*

The chat the file belongs to.

**name** `string` *required*

The file name.

**mimeType** `string` *required*

For example `application/pdf`.

**contentBase64** `string` *required*

The file, base64-encoded. 10 MB maximum by default.

**clientNonce** `string`

Retrying with the same nonce returns the same upload.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.