Prise en main et retour à l'agent - Shortext

Utilisez ces endpoints pour construire votre propre console d’agents, ou pour arrêter l’IA quand votre système détecte un cas sensible. Ils demandent tous Envoyer des messages, et la conversation doit avoir une session active.

Prendre en main et rendre la main

# 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	Effet	Webhook
`PUT /conversations/{id}/handover`	Une personne suit la conversation : l’agent IA cesse de répondre.	`conversation.handover`
`DELETE /conversations/{id}/handover`	L’agent IA répond de nouveau aux prochains messages.	`conversation.released`

Les deux renvoient la conversation ; session.handover et session.handover_at indiquent son état. Répondre avec POST /conversations/{id}/messages prend aussi la conversation en main, sauf si vous envoyez "handover": false. Démarrer une conversation avec "handover": true l’ouvre directement en prise en main.

Assigner

GET /conversations/assignees liste les membres de votre entreprise (USR-XXXXX).
PUT /conversations/{id}/assignee avec { "user_id": "USR-XXXXX" } assigne la session en cours ; { "user_id": null } la désassigne.

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" }'

Filtrez les conversations par personne assignée avec GET /conversations?assignee=USR-XXXXX (ou none).

Rester synchronisé

Abonnez un webhook à conversation.* pour savoir quand quelqu’un prend en main ou rend la main depuis la boîte de réception, et à message.* pour suivre les messages.