API reference: Handover

Handover. Your team takes over, from your own tools.

The same actions as the SimplyBoost inbox: take a conversation over, reply as a person, hand it back to the agent, resolve and reopen. Works on every channel.

AI answering
mode: "ai"
POST …/take-over
Your team answering
mode: "human" · POST …/replies
PATCH {"resolved": true}
Resolved
resolved: true
POST …/switch-to-ai hands it back

By , AI EngineerUpdated

The flow

  • Take over: the agent stops answering. mode becomes human.
  • Reply: your message reaches the visitor on the conversation's own channel (website chat, WhatsApp, Instagram or API), shown with the first name of the token's creator.
  • Hand back: the agent answers again. mode becomes ai.
  • Resolve or reopen: mark the conversation done, or open it again.

Replies are sent as the person who created the token. If a colleague already claimed the handover in the inbox, your reply is refused with 403 claimed_by_other, so two people never answer at once. A conversation handed over by the agent fires the conversation.escalated webhook; resolving fires conversation.resolved.

Take over a conversation

POST/chatbots/{chatbotId}/conversations/{threadId}/take-over

A person takes the conversation; the chatbot stops answering it. When your account uses tickets, this opens one: the response has its ticketCode.

Permission: conversations:write

Path parameters

chatbotId
string (uuid)required

The chatbot. Listed by GET /chatbots.

threadId
string (uuid)required

The conversation, from conversation.threadId.

Request
curl -X POST https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/conversations/THREAD_ID/take-over \
  -H "Authorization: Bearer $SIMPLYBOOST_TOKEN"

Response 200 OK

{
  "ok": true,
  "data": { "conversation": { "threadId": "3f0c…", "mode": "human", "escalated": false, "resolved": false, … } },
  "meta": { "requestId": "req_7c1e4b2a9f0d4e6c8b3a5d7f9e1c2b4a" }
}

Response fields

data.conversation.threadId
string

The conversation's ID.

data.conversation.chatbotId
string

The chatbot it belongs to.

data.conversation.channel
string

Where it happens: web, api, whatsapp or instagram.

data.conversation.mode
string

Who answers: ai (the chatbot) or human (your team).

data.conversation.escalated
boolean

True while a handover to your team is open.

data.conversation.resolved
boolean

True once it was marked resolved.

data.conversation.startedAt
string (date-time)

When it started.

data.conversation.lastMessageAt
string (date-time)

When the last message was sent.

data.conversation.ticketCode
string | null

The ticket's code, such as SB-7K4Q9M: what to show your team and the visitor, and what they quote. Random and unique across all accounts. null until the conversation is a ticket.

data.conversation.ticketNumber
integer | null

The ticket's number in your account, in the order tickets opened. Use it to sort; show ticketCode instead. null until the conversation is a ticket.

data.conversation.priority
string | null

low, normal, high or urgent, as set by your team. null when not set.

data.conversation.tags
string[]

The conversation's tags.

data.conversation.assignee
object | null

The teammate it is assigned to: id and name. null when unassigned.

Errors

StatusCodeWhen
404not_foundNo such chatbot or conversation, or this token may not see it.
409already_handoverA person is already handling it.

Reply as a person

POST/chatbots/{chatbotId}/conversations/{threadId}/replies

Sends a reply from the token's creator in a conversation your team is handling. Take it over first.

Permission: conversations:write

Path parameters

chatbotId
string (uuid)required

The chatbot. Listed by GET /chatbots.

threadId
string (uuid)required

The conversation, from conversation.threadId.

Body (JSON)

message
stringrequired

The reply, 1 to 4,000 characters.

Request
curl -X POST https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/conversations/THREAD_ID/replies \
  -H "Authorization: Bearer $SIMPLYBOOST_TOKEN" \
  -H "Idempotency-Key: reply-3f0c-1" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hi Sanne, I have refunded the second payment."}'

Response 201 Created

{
  "ok": true,
  "data": {
    "message": { "id": "…", "role": "agent", "text": "Hi Sanne, I have refunded the second payment.", "createdAt": "2026-10-07T09:41:00+00:00" },
    "delivered": true
  },
  "meta": { "requestId": "req_7c1e4b2a9f0d4e6c8b3a5d7f9e1c2b4a" }
}

Response fields

data.message.id
string

The message's ID.

data.message.role
string

user (the visitor), assistant (the chatbot) or agent (a person on your team).

data.message.text
string

The message text.

data.message.createdAt
string (date-time)

When it was sent.

data.delivered
boolean

Whether the reply was handed to the visitor's channel.

data.deliveryError
string

Only when delivery failed: the reason. The reply is still saved in the conversation.

Errors

StatusCodeWhen
400validation_errormessage is missing, empty or over 4,000 characters.
404not_foundNo such chatbot or conversation, or this token may not see it.
409not_handoverYour team is not handling the conversation. Take it over first.
403claimed_by_otherA colleague is already handling this handover.
503lock_failedA short conflict while claiming the handover. Retry.

Hand a conversation back to the chatbot

POST/chatbots/{chatbotId}/conversations/{threadId}/switch-to-ai

The chatbot answers the visitor's next messages again.

Permission: conversations:write

Path parameters

chatbotId
string (uuid)required

The chatbot. Listed by GET /chatbots.

threadId
string (uuid)required

The conversation, from conversation.threadId.

Request
curl -X POST https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/conversations/THREAD_ID/switch-to-ai \
  -H "Authorization: Bearer $SIMPLYBOOST_TOKEN"

Response 200 OK

{
  "ok": true,
  "data": { "conversation": { "threadId": "3f0c…", "mode": "ai", … } },
  "meta": { "requestId": "req_7c1e4b2a9f0d4e6c8b3a5d7f9e1c2b4a" }
}

Response fields

data.conversation.threadId
string

The conversation's ID.

data.conversation.chatbotId
string

The chatbot it belongs to.

data.conversation.channel
string

Where it happens: web, api, whatsapp or instagram.

data.conversation.mode
string

Who answers: ai (the chatbot) or human (your team).

data.conversation.escalated
boolean

True while a handover to your team is open.

data.conversation.resolved
boolean

True once it was marked resolved.

data.conversation.startedAt
string (date-time)

When it started.

data.conversation.lastMessageAt
string (date-time)

When the last message was sent.

data.conversation.ticketCode
string | null

The ticket's code, such as SB-7K4Q9M: what to show your team and the visitor, and what they quote. Random and unique across all accounts. null until the conversation is a ticket.

data.conversation.ticketNumber
integer | null

The ticket's number in your account, in the order tickets opened. Use it to sort; show ticketCode instead. null until the conversation is a ticket.

data.conversation.priority
string | null

low, normal, high or urgent, as set by your team. null when not set.

data.conversation.tags
string[]

The conversation's tags.

data.conversation.assignee
object | null

The teammate it is assigned to: id and name. null when unassigned.

Errors

StatusCodeWhen
404not_foundNo such chatbot or conversation, or this token may not see it.
409not_handoverThe chatbot is already answering.

Resolve or reopen a conversation

PATCH/chatbots/{chatbotId}/conversations/{threadId}

{"resolved": true} marks the conversation done; {"resolved": false} reopens it.

Permission: conversations:write

Path parameters

chatbotId
string (uuid)required

The chatbot. Listed by GET /chatbots.

threadId
string (uuid)required

The conversation, from conversation.threadId.

Body (JSON)

resolved
booleanrequired

true to resolve, false to reopen.

Request
curl -X PATCH https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/conversations/THREAD_ID \
  -H "Authorization: Bearer $SIMPLYBOOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resolved": true}'

Response 200 OK

{
  "ok": true,
  "data": { "conversation": { "threadId": "3f0c…", "mode": "ai", "resolved": true, … } },
  "meta": { "requestId": "req_7c1e4b2a9f0d4e6c8b3a5d7f9e1c2b4a" }
}

Response fields

data.conversation.threadId
string

The conversation's ID.

data.conversation.chatbotId
string

The chatbot it belongs to.

data.conversation.channel
string

Where it happens: web, api, whatsapp or instagram.

data.conversation.mode
string

Who answers: ai (the chatbot) or human (your team).

data.conversation.escalated
boolean

True while a handover to your team is open.

data.conversation.resolved
boolean

True once it was marked resolved.

data.conversation.startedAt
string (date-time)

When it started.

data.conversation.lastMessageAt
string (date-time)

When the last message was sent.

data.conversation.ticketCode
string | null

The ticket's code, such as SB-7K4Q9M: what to show your team and the visitor, and what they quote. Random and unique across all accounts. null until the conversation is a ticket.

data.conversation.ticketNumber
integer | null

The ticket's number in your account, in the order tickets opened. Use it to sort; show ticketCode instead. null until the conversation is a ticket.

data.conversation.priority
string | null

low, normal, high or urgent, as set by your team. null when not set.

data.conversation.tags
string[]

The conversation's tags.

data.conversation.assignee
object | null

The teammate it is assigned to: id and name. null when unassigned.

Errors

StatusCodeWhen
400validation_errorresolved is missing or not a boolean.
404not_foundNo such chatbot or conversation, or this token may not see it.
409already_resolvedResolving a conversation that is already resolved.
409not_resolvedReopening a conversation that is not resolved.

Try SimplyBoost with your own content

Start a 7-day free trial with 100 AI replies. Add your website, install the widget and see how the agent answers your customers. Larger team? Custom plans above 4,000 AI replies come with a dedicated account manager and white-label.

See pricing
  • 7 days, 100 AI replies
  • From €39 a month
  • Hosted in Europe