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

# Handover and release

> Take a conversation over from the AI agent, hand it back, and assign it, from your own systems.

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

```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 | 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

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

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

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

## Keep your system in sync

Subscribe a [webhook](https://docs.shortext.ny-corp.io/api-reference/webhooks.md) to `conversation.*` to know when someone takes over or hands back from the Inbox, and to `message.*` to follow the messages.


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