> ## 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. # Handoff States > Retrieve the handoff state and context written by your agent when a conversation transitions to a live agent. Use the Handoff States API to retrieve the handoff state recorded by your agent at the moment of transition to a live agent, along with the context and metadata needed to synchronize downstream systems. The endpoint is read-only — handoffs themselves are triggered from the agent (via [Call Handoffs](/voice-channel/handoffs), [FAQs actions](/knowledge/faqs/actions/handoff), or `conv.call_handoff` in code), not from this API. For detailed API specifications, refer to the [Handoff API documentation](/api-reference/handoff/introduction). ## Related handoff documentation * **[Call Handoffs overview](/voice-channel/handoffs)** - Configure handoff destinations in the UI * **[Handoff actions in FAQs](/knowledge/faqs/actions/handoff)** - Trigger handoffs from Knowledge topics * **[Handoff API reference](/api-reference/handoff/introduction)** - Retrieve handoff context programmatically * **[Twilio handoff integration](/voice-channel/numbers/twilio/how-to-handoff)** - Twilio-specific handoff setup ## When to use handoff states The **handoff states** API reads back the state your agent recorded for a conversation at handoff. Use it to: * 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. The API does not trigger handoffs or change conversation state — it only returns what the agent stored. To trigger or configure handoffs, see [Call Handoffs](/voice-channel/handoffs) (UI) or `conv.call_handoff` (code). ## 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](/voice-channel/handoffs) to configure handoff destinations in the UI, or the [handoff action in FAQs](/knowledge/faqs/actions/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](/voice-channel/handoffs#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.