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

On this page

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, Messenger 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.

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, instagram or facebook.

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.

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, instagram or facebook.

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.

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, instagram or facebook.

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.

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.
PreviousConversationsNextLeads

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.

Start free trial
See pricing
  • No credit card required
  • 7 days, 100 AI replies
  • From €39 a month
  • Hosted in Europe