> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shortext.ny-corp.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Prise en main et retour à l'agent

> Prenez une conversation en main à la place de l'agent IA, rendez-la-lui et assignez-la, depuis vos propres systèmes.

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

```bash cURL theme={null}
# 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 PHP theme={null}
<?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
```

```javascript Node.js theme={null}
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
```

```python Python theme={null}
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

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

```bash theme={null}
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](https://docs.shortext.ny-corp.io/fr/api-reference/webhooks.md) à `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.