The live chat inbox

Everything a teammate does in the live chat inbox can be done through the API: read the queue and a conversation, take it over from the AI agent, reply to the visitor, hand it back, and organise it. It uses the same rules as the inbox in the app.

#Read the queue and a thread

# the queue (conversations:read)
curl "https://synconone.com/api/v1/conversations?view=needs_person&limit=25" -H "Authorization: Bearer $KEY"

# one conversation: who is answering, and whether you may reply
curl https://synconone.com/api/v1/conversations/conv_… -H "Authorization: Bearer $KEY"

# its thread, oldest first; pass the last cursor as "after" to follow it live
curl "https://synconone.com/api/v1/conversations/conv_…/messages?after=0" -H "Authorization: Bearer $KEY"

responder is ai while the agent is answering and human once a teammate has taken over. Reading never marks a conversation read. Messages carry a role of visitor, agent, human or system (a join, a hand-back, a booking).

#Take over and reply

1. POST /conversations/{id}/join. The visitor sees a teammate arrive. If another teammate already has it, you get 409.
2. POST /conversations/{id}/reply with { "text": "…" }. Replying before joining is a 409.

curl -X POST https://synconone.com/api/v1/conversations/conv_…/reply -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Yes, we ship to Perth.", "client_message_id": "case-88-reply-1"}'

Send your own client_message_id so a retry after a dropped connection posts the message once, not twice.

#Hand back to the AI agent

POST /conversations/{id}/return-to-ai returns the conversation to the agent. Only the teammate who holds it can.

#Owner, priority, tags and notes

• PATCH /conversations/{id} sets assignee (a teammate from GET /team/members, or null), priority, and add_tags / remove_tags.
• POST /conversations/{id}/notes adds a note only your team sees; the visitor never does. GET lists them.
• There is no separate close. A conversation is resolved by resolving its ticket, with PATCH /tickets/{number}.

See the inbox reference for every field.