Skip to main content

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.

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.

​
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

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:
StateDescription
customer_refundThe call was escalated to a live agent to process a refund request.
complaint_escalationThe call was handed off due to a complaint requiring live agent resolution.
successfully_identifiedThe system successfully verified the customer’s identity before transitioning the call to a live agent.
Example API response: 
{
  "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 to configure handoff destinations in the UI, or the handoff action in Managed Topics 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.

​
Webchat and SMS handoff via the Chat API

For webchat and SMS integrations using the Chat API, 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. 
{
  "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 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.

​
SIP header handoff

Some deployments include handoff metadata in SIP 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.

List conversations

Retrieve metadata for conversations programmatically.

Studio transcripts

Access detailed transcripts for compliance and analytics.

S3-to-S3 integration

Automate large-scale transcript and metadata transfers.
Last modified on April 28, 2026