Inbox · API reference

#List conversations in the inbox

GET/api/v1/conversations

Operation list_conversations · needs scope conversations:read

The live chat queue, most recently active first. Not pageable: narrow with view, q, responder, priority or tag.

Parameter	In	Type	Notes
`view`	query	all \| everything \| resolved \| mine \| unassigned \| team \| my_teams \| needs_person \| waiting_customer \| waiting_teammate \| ai \| human \| unread \| closed \| sla_risk
`q`	query	string	Search the visitor, site and messages.
`responder`	query	ai \| human
`priority`	query	none \| low \| medium \| high \| urgent
`tag`	query	string	A tag name.
`limit`	query	integer	Page size, at most 80.

bash

curl https://synconone.com/api/v1/conversations \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

json

{
  "data": [
    {
      "id": "pr_1a2b3c4d5e6f7a8b",
      "object": "string",
      "visitor_name": "string",
      "visitor_email": "[email protected]",
      "site": "string",
      "channel": "string",
      "status": "string",
      "responder": "ai",
      "handoff_state": "string",
      "assignee": "string"
    }
  ],
  "pagination": {
    "nextCursor": null,
    "hasMore": false
  }
}

Errors: 401: Missing, invalid, revoked or expired API key. · 403: The key lacks the scope, or its role cannot do this. · 422: Validation failed. · 429: Rate limited. Honour Retry-After.. See errors.

#Get a conversation

GET/api/v1/conversations/{id}

Operation get_conversation · needs scope conversations:read

Who is answering, who holds it, and whether the acting teammate may reply.

Parameter	In	Type	Notes
`id` required	path	string	Public id of the conversation, conv_…

bash

curl https://synconone.com/api/v1/conversations/pr_1a2b3c4d5e6f7a8b \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

json

{
  "data": {
    "id": "pr_1a2b3c4d5e6f7a8b",
    "object": "string",
    "visitor_name": "string",
    "visitor_email": "[email protected]",
    "site": "string",
    "channel": "string",
    "status": "string",
    "responder": "ai",
    "handoff_state": "string",
    "assignee": "string"
  }
}

Errors: 401: Missing, invalid, revoked or expired API key. · 403: The key lacks the scope, or its role cannot do this. · 404: Not found, or not visible to this key. · 422: Validation failed. · 429: Rate limited. Honour Retry-After.. See errors.

#Change a conversation's owner, priority or tags

PATCH/api/v1/conversations/{id}

Operation update_conversation · needs scope conversations:write

Parameter	In	Type	Notes
`id` required	path	string	Public id of the conversation, conv_…

Body field	Type	Notes
`priority`	none \| low \| medium \| high \| urgent
`assignee`	string	Member user id; null unassigns.
`add_tags`	list of string
`remove_tags`	list of string

bash

curl -X PATCH https://synconone.com/api/v1/conversations/pr_1a2b3c4d5e6f7a8b \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"priority":"none","assignee":"string","add_tags":["string"],"remove_tags":["string"]}'

json

{
  "data": {
    "id": "pr_1a2b3c4d5e6f7a8b",
    "object": "string",
    "visitor_name": "string",
    "visitor_email": "[email protected]",
    "site": "string",
    "channel": "string",
    "status": "string",
    "responder": "ai",
    "handoff_state": "string",
    "assignee": "string"
  }
}

Errors: 401: Missing, invalid, revoked or expired API key. · 403: The key lacks the scope, or its role cannot do this. · 404: Not found, or not visible to this key. · 409: Conflict, approval required, or idempotent request in progress. · 422: Validation failed. · 429: Rate limited. Honour Retry-After.. See errors.

#Read a conversation's messages

GET/api/v1/conversations/{id}/messages

Operation list_conversation_messages · needs scope conversations:read

The thread as the team sees it, oldest first, with system lines such as joins. Poll with after set to the last cursor to follow it live. Reading does not mark it read.

Parameter	In	Type	Notes
`id` required	path	string	Public id of the conversation, conv_…
`after`	query	integer	Only messages after this cursor. 0 starts at the beginning.
`limit`	query	integer	At most 100.

bash

curl https://synconone.com/api/v1/conversations/pr_1a2b3c4d5e6f7a8b/messages \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

json

{
  "data": [
    {
      "cursor": 1,
      "object": "string",
      "role": "visitor",
      "kind": "string",
      "body": "Asked about annual terms on the website.",
      "sender": "string",
      "event": "string",
      "reply_to": 1,
      "attachments": [
        {
          "kind": null,
          "name": null,
          "url": null
        }
      ],
      "created_at": "2026-11-05T10:00:00Z"
    }
  ],
  "pagination": {
    "nextCursor": null,
    "hasMore": false
  }
}

Errors: 401: Missing, invalid, revoked or expired API key. · 403: The key lacks the scope, or its role cannot do this. · 404: Not found, or not visible to this key. · 422: Validation failed. · 429: Rate limited. Honour Retry-After.. See errors.

#Take a conversation over from the AI agent

POST/api/v1/conversations/{id}/join

Operation join_conversation · needs scope conversations:write

The visitor sees a teammate arrive. Refused with 409 when another teammate already has it. Do this before replying.

Parameter	In	Type	Notes
`id` required	path	string	Public id of the conversation, conv_…

bash

curl -X POST https://synconone.com/api/v1/conversations/pr_1a2b3c4d5e6f7a8b/join \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

json

{
  "data": {
    "id": "pr_1a2b3c4d5e6f7a8b",
    "object": "string",
    "responder": "ai",
    "cursor": 1
  }
}

Errors: 401: Missing, invalid, revoked or expired API key. · 403: The key lacks the scope, or its role cannot do this. · 404: Not found, or not visible to this key. · 422: Validation failed. · 429: Rate limited. Honour Retry-After.. See errors.

#Reply to the visitor

POST/api/v1/conversations/{id}/reply

Operation reply_to_conversation · needs scope conversations:write

Sends a message the visitor reads at once, as the teammate the key stands for. The conversation must be joined first (409 otherwise). Sending the same client_message_id twice posts once.

Parameter	In	Type	Notes
`id` required	path	string	Public id of the conversation, conv_…

Body field	Type	Notes
`text` required	string	What the visitor will read.
`reply_to`	integer	Cursor of the message being answered.
`client_message_id`	string	Your own id for this message. Sending it again returns the first instead of posting twice.

bash

curl -X POST https://synconone.com/api/v1/conversations/pr_1a2b3c4d5e6f7a8b/reply \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Asked about annual terms on the website.","reply_to":1,"client_message_id":"pr_1a2b3c4d5e6f7a8b"}'

json

{
  "data": {
    "id": "pr_1a2b3c4d5e6f7a8b",
    "object": "string",
    "responder": "ai",
    "cursor": 1
  }
}

Errors: 401: Missing, invalid, revoked or expired API key. · 403: The key lacks the scope, or its role cannot do this. · 404: Not found, or not visible to this key. · 409: Conflict, approval required, or idempotent request in progress. · 422: Validation failed. · 429: Rate limited. Honour Retry-After.. See errors.

#Hand a conversation back to the AI agent

POST/api/v1/conversations/{id}/return-to-ai

Operation return_conversation_to_ai · needs scope conversations:write

Only the teammate who holds it can. The agent carries on from where the human left off.

Parameter	In	Type	Notes
`id` required	path	string	Public id of the conversation, conv_…

bash

curl -X POST https://synconone.com/api/v1/conversations/pr_1a2b3c4d5e6f7a8b/return-to-ai \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

json

{
  "data": {
    "id": "pr_1a2b3c4d5e6f7a8b",
    "object": "string",
    "responder": "ai",
    "cursor": 1
  }
}

Errors: 401: Missing, invalid, revoked or expired API key. · 403: The key lacks the scope, or its role cannot do this. · 404: Not found, or not visible to this key. · 422: Validation failed. · 429: Rate limited. Honour Retry-After.. See errors.

#List a conversation's internal notes

GET/api/v1/conversations/{id}/notes

Operation list_conversation_notes · needs scope conversations:read

Notes only the team sees, newest first.

Parameter	In	Type	Notes
`id` required	path	string	Public id of the conversation, conv_…

bash

curl https://synconone.com/api/v1/conversations/pr_1a2b3c4d5e6f7a8b/notes \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

json

{
  "data": [
    {
      "id": "pr_1a2b3c4d5e6f7a8b",
      "object": "string",
      "body": "Asked about annual terms on the website.",
      "author": "string",
      "author_name": "string",
      "created_at": "2026-11-05T10:00:00Z"
    }
  ],
  "pagination": {
    "nextCursor": null,
    "hasMore": false
  }
}

Errors: 401: Missing, invalid, revoked or expired API key. · 403: The key lacks the scope, or its role cannot do this. · 404: Not found, or not visible to this key. · 422: Validation failed. · 429: Rate limited. Honour Retry-After.. See errors.

#Add an internal note to a conversation

POST/api/v1/conversations/{id}/notes

Operation add_conversation_note · needs scope conversations:write

The visitor never sees it.

Parameter	In	Type	Notes
`id` required	path	string	Public id of the conversation, conv_…

Body field	Type	Notes
`body` required	string	Only the team sees this. @mentions notify.

bash

curl -X POST https://synconone.com/api/v1/conversations/pr_1a2b3c4d5e6f7a8b/notes \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"Asked about annual terms on the website."}'

json

{
  "data": {
    "id": "pr_1a2b3c4d5e6f7a8b",
    "object": "string",
    "body": "Asked about annual terms on the website.",
    "author": "string",
    "author_name": "string",
    "created_at": "2026-11-05T10:00:00Z"
  }
}

Errors: 401: Missing, invalid, revoked or expired API key. · 403: The key lacks the scope, or its role cannot do this. · 404: Not found, or not visible to this key. · 409: Conflict, approval required, or idempotent request in progress. · 422: Validation failed. · 429: Rate limited. Honour Retry-After.. See errors.