Request Human Handoff

Ask a human agent to take over a conversation, for example when your automated assistant cannot answer. Supply its conversation_id in the path; no request body is needed. Obtain conversation_id from List Conversations or data.conversation.id in a message webhook.

Every active agent in your workspace is notified, and the conversation is shown as waiting for a human agent in the dashboard. Handoff does not assign the conversation. To route it to a specific agent or team, also call Assign Conversation.

Repeating the request within 5 minutes of the last handoff does not notify anyone again and returns changed: false, so it is safe to retry. After that, a new request notifies your team again.

Returns 200 OK with the conversation ID and handoff_requested status.

POST https://developers.chatway.app/api/v1/conversations/{conversation_id}/handoff

Example request

curl -X POST "https://developers.chatway.app/api/v1/conversations/0f46c0a1-8938-40e3-b2b5-bb56f569fcab/handoff" \
  -H "X-API-KEY: your_api_key"

Parameters

Responses

200

Handoff notifies your team but does not assign the conversation. Your automated assistant can still send messages with Create Message after the handoff, for example to tell the visitor that a human agent will reply.

application/json

• message (string, required)
• data (object, required)
  • conversation_id (string, required)
  • status (string, required)
  • changed (boolean, required)

404

Conversation not found

application/json

• message (string, required)

Examples

Response 200 example

{
    "message": "Human handoff requested.",
    "data": {
        "conversation_id": "0f46c0a1-8938-40e3-b2b5-bb56f569fcab",
        "status": "handoff_requested",
        "changed": true
    }
}