> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.poly.ai/feedback
```json
{
"path": "/call-data/conversations-api/handoff-states",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Handoff States
> Monitor and manage transitions between automated and live agents using the Handoff States API.
Use the Handoff States API to monitor transitions between automated agents and live agents, retrieve handoff context, and synchronize metadata with downstream systems. This page explains when to use handoff APIs, highlights topic-specific state examples, and provides integration best practices.
For detailed API specifications, refer to the [Handoff API documentation](/api-reference/handoff/introduction).
## Related handoff documentation
* **[Call Handoffs overview](/call-handoff/introduction)** - Configure handoff destinations in the UI
* **[Handoff actions in Managed Topics](/managed-topics/how-to-setup-action/handoff)** - Trigger handoffs from Knowledge topics
* **[Handoff API reference](/api-reference/handoff/introduction)** - Retrieve handoff context programmatically
* **[Twilio handoff integration](/telephony/twilio/how-to-handoff)** - Twilio-specific handoff setup
## When to use handoff states
The **handoff states** API manages live agent transitions during conversations. Use it to:
* Trigger transitions between automated and live agents.
* Retrieve the state of a handoff, such as `handoff_initiated`, `handoff_completed`, or `handoff_failed`, or custom topic-specific states (e.g., `customer_refund` or `complaint_escalation`).
* Synchronize metadata with systems operated by human agents so they have full conversational context.
## Handoff states overview
```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
stateDiagram-v2
[*] --> handoff_initiated: Agent triggers handoff
handoff_initiated --> handoff_completed: Live agent accepts
handoff_initiated --> handoff_failed: Transfer fails
handoff_failed --> handoff_initiated: Retry
handoff_completed --> [*]: Call ends
handoff_failed --> [*]: Fallback / call ends
```
The **handoff states** API provides key triggers for managing transitions between automated and live agents. These states act as signals indicating the outcome of a handoff process rather than continuously updating during the call.
Some example states you could use include:
| State | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------- |
| `customer_refund` | The call was escalated to a live agent to process a refund request. |
| `complaint_escalation` | The call was handed off due to a complaint requiring live agent resolution. |
| `successfully_identified` | The system successfully verified the customer's identity before transitioning the call to a live agent. |
Example API response:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "0bba04d7-38b3-4fd3-a1a8-329c34517fc1",
"shared_id": "acme_inc_sdklfasdklfjasbdfklabs",
"data": {
"customer_id": "12345",
"handoff_reason": "successfully_identified"
}
}
```
## Accessing handoff state data
Use the [Call Handoffs page](/call-handoff/introduction) to configure handoff destinations in the UI, or the [handoff action in Managed Topics](/managed-topics/how-to-setup-action/handoff) to trigger handoffs from Knowledge topics.
### API endpoint
The **Handoff API** retrieves the current handoff state of a conversation using either:
* **Shared IDs (`shared_id`)**: Used in both the PolyAI and client systems to keep them in sync.
* **PolyAI conversation IDs (`id`)**: Generated automatically by PolyAI for each conversation.
When both IDs are provided, the API prioritizes the `shared_id`.
For full details on parameters, headers, and error codes, refer to the [Handoff API documentation](/api-reference/handoff/introduction).
## Webchat and SMS handoff via the Chat API
For webchat and SMS integrations using the [Chat API](/api-reference/chat/introduction), the agent signals a handoff on the `chat/respond` response: `end_conversation` is set to `true` and a `handoff` object is included alongside the agent's final message.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"conversation_id": "CONV-1234567890",
"response": "Transferring you to a live agent.",
"end_conversation": true,
"handoff": {
"destination": "live_agent_queue",
"reason": "billing_question"
}
}
```
When your widget or SMS connector sees `handoff` in the response:
1. Stop calling `chat/respond` for this conversation.
2. Use `destination` to route the session to the right queue or skill in your live-chat platform.
3. Call the [Handoff API](/api-reference/handoff/introduction) with the `conversation_id` (or your `shared_id`) to retrieve the full `data` payload — customer identifiers, verification status, collected entities — for a screen-pop on the live agent's desktop.
4. Optionally call `chat/close` once the human has accepted the session.
For voice handoffs, the equivalent signal is a SIP REFER, INVITE, or BYE — see [Call handoff](/call-handoff/introduction#adding-a-handoff-destination).
## SIP header handoff
Some deployments include handoff metadata in [SIP](https://en.wikipedia.org/wiki/Session_Initiation_Protocol) headers when calls are passed back to the contact center. SIP headers can provide critical context quickly, because they package agent IDs and handoff states into lightweight metadata.
### Considerations
* **Customization**: SIP header metadata varies by deployment. Review your deployment-specific SIP header documentation or contact your PolyAI representative for details on the fields and formats available in your setup.
* **Completeness**: Ensure the SIP headers in your deployment include all context your contact center agents need for handoff handling (e.g., handoff reason, customer ID).
## Best practices
1. **Prioritize shared IDs**: Use `shared_id` for consistency with your internal systems. If both `id` and `shared_id` are provided, the API defaults to the `shared_id`.
2. **Monitor handoff failures**: Track the `handoff_failed` state (or its equivalent in your deployment) to implement automated retries or fallback workflows.
3. **Use topic-specific states**: Implement custom states (e.g., `customer_refund` or `complaint_escalation`) for better tracking and reporting on specific interaction types.
***
## Related pages
Retrieve metadata for conversations programmatically.
Access detailed transcripts for compliance and analytics.
Automate large-scale transcript and metadata transfers.