Handover and release - Shortext

Use these endpoints to build your own agent console, or to stop the AI when your system detects a sensitive case. All of them require Send messages, and the conversation must have an active session.

Take over and hand back

# Take the conversation over: the AI agent stops answering
curl -X PUT https://shortext.ny-corp.io/api/v2.0/conversations/$CONVERSATION_ID/handover \
  -H "Authorization: Bearer $SHORTEXT_API_KEY" -H "Accept: application/json"

# Hand it back: the AI agent answers again
curl -X DELETE https://shortext.ny-corp.io/api/v2.0/conversations/$CONVERSATION_ID/handover \
  -H "Authorization: Bearer $SHORTEXT_API_KEY" -H "Accept: application/json"

<?php
$client  = new GuzzleHttp\Client(['base_uri' => 'https://shortext.ny-corp.io/api/v2.0/']);
$headers = ['Authorization' => 'Bearer ' . getenv('SHORTEXT_API_KEY'), 'Accept' => 'application/json'];

$client->put("conversations/{$conversationId}/handover", ['headers' => $headers]);    // take over
$client->delete("conversations/{$conversationId}/handover", ['headers' => $headers]); // hand back

const url = `https://shortext.ny-corp.io/api/v2.0/conversations/${conversationId}/handover`;
const headers = { Authorization: `Bearer ${process.env.SHORTEXT_API_KEY}`, Accept: "application/json" };

await fetch(url, { method: "PUT", headers });    // take over
await fetch(url, { method: "DELETE", headers }); // hand back

url = f"https://shortext.ny-corp.io/api/v2.0/conversations/{conversation_id}/handover"
headers = {"Authorization": f"Bearer {os.environ['SHORTEXT_API_KEY']}", "Accept": "application/json"}

requests.put(url, headers=headers)     # take over
requests.delete(url, headers=headers)  # hand back

Endpoint	Effect	Webhook
`PUT /conversations/{id}/handover`	A human follows the conversation: the AI agent stops answering.	`conversation.handover`
`DELETE /conversations/{id}/handover`	The AI agent answers the next messages again.	`conversation.released`

Both return the conversation; session.handover and session.handover_at tell you its state. Replying with POST /conversations/{id}/messages also takes the conversation over, unless you send "handover": false. Starting a conversation with "handover": true opens it directly in handover.

Assign

GET /conversations/assignees lists the members of your company (USR-XXXXX).
PUT /conversations/{id}/assignee with { "user_id": "USR-XXXXX" } assigns the current session; { "user_id": null } unassigns it.

curl -X PUT https://shortext.ny-corp.io/api/v2.0/conversations/$CONVERSATION_ID/assignee \
  -H "Authorization: Bearer $SHORTEXT_API_KEY" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{ "user_id": "USR-XXXXX" }'

Filter conversations by assignee with GET /conversations?assignee=USR-XXXXX (or none).

Keep your system in sync

Subscribe a webhook to conversation.* to know when someone takes over or hands back from the Inbox, and to message.* to follow the messages.