Actions API

Do anything a teammate can do in the inbox, over HTTP.

Every action in the SI Desk inbox is also an HTTP endpoint. Your scripts and backends can list conversations, reply, add notes, change status and read reports.

Get a token

Sign in to SI Desk and open https://sidesk.co/mcp/connect.
Choose Generate a static token, then Create connection token.
Send it with every request as Authorization: Bearer <token>.

A token acts as you, in the business that was active when you made it. Make one token per business. Revoke it on the same page. Keep it secret, like a password.

Call an action

Read actions take GET https://sidesk.co/_agent-native/actions/<name> with query parameters.
All other actions take POST to the same address with a JSON body.

TOKEN=...   # from /mcp/connect
BASE=https://sidesk.co/_agent-native/actions

# Open conversations
curl -sS -H "Authorization: Bearer $TOKEN" "$BASE/list-conversations?status=open"

# Reply as a teammate
curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"conversationId":"<id>","body":"Thanks, fixed now.","author":"human"}' \
  "$BASE/reply-to-conversation"

Times are ISO 8601 in UTC. Durations are in seconds.

Errors

Status	Meaning
`400`	The input is invalid. The response says why.
`401`	The token is missing, expired or revoked.
`404`	The record does not exist.
`405`	Wrong method, such as `POST` for a read action.

Common actions

Action	Method	What it does
`list-conversations`	GET	Lists conversations. Filter by `status`, `channel`, `assigneeEmail`, `labelId`, `query` and dates.
`get-conversation`	GET	A conversation with all its messages and notes.
`reply-to-conversation`	POST	Replies to the customer. Set `author` to `human` for a teammate reply, or leave it as `agent` for an AI reply.
`save-reply-draft`	POST	Leaves a draft for a teammate to review and send.
`add-note`	POST	Adds a note only your team sees.
`update-conversation`	POST	Changes status, assignee or subject.
`bulk-update-conversations`	POST	Changes status or assignee for up to 200 conversations.
`start-email-conversation`	POST	Emails a customer first.
`list-contacts`	GET	Searches customers by name or email.
`get-contact-profile`	GET	A customer's details, other conversations and website activity.
`performance-report`	GET	Response and resolution times.

The MCP server offers the same actions as tools.

Was this page helpful?