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.

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": { "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.

​

threads/answer

POST /rpc/threads/answer answers a question or approval 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.