> ## Documentation Index
> Fetch the complete documentation index at: https://polyai-mintlify-7055a538.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat handoff integrations

> Hand off webchat and SMS conversations from your PolyAI agent to a live agent in your CCaaS or CRM.

Use a chat handoff integration to escalate a webchat or SMS conversation from your PolyAI agent to a live agent in your existing CCaaS or CRM. PolyAI continues to proxy messages between the end user and the live agent, so the conversation stays in the same widget the user started in.

<Note>
  All chat handoff integrations are configured from **Integrations** in Agent Studio. The handoff is triggered from a Python tool returning a `handoff` payload, then assigned to the Knowledge topic (or flow step) that should escalate.
</Note>

## Available integrations

<CardGroup cols={3}>
  <Card title="Salesforce" icon="cloud" href="/integrations/chat/salesforce">
    Hand off to Salesforce Service Cloud Messaging using an Embedded Service deployment.
  </Card>

  <Card title="Zendesk" icon="ticket" href="/integrations/chat/zendesk">
    Hand off to Zendesk Messaging through a Conversations Integration and switchboard.
  </Card>

  <Card title="NICE CXone" icon="headset" href="/integrations/chat/nice-cxone">
    Hand off to NICE CXone Digital using Brand ID and Channel ID routing.
  </Card>

  <Card title="Amazon Connect" icon="aws" href="/integrations/chat/amazon-connect">
    Hand off to an Amazon Connect chat contact flow via the `StartChatContact` API.
  </Card>

  <Card title="Genesys Cloud" icon="headset" href="/integrations/messaging/genesys">
    Hand off through Genesys Cloud Open Messaging to a queue with live agents.
  </Card>

  <Card title="Webex by Cisco" icon="webex" href="/integrations/chat/webex">
    Hand off to Webex Contact Center through Bring Your Own Channel.
  </Card>

  <Card title="Five9" icon="headset" href="/integrations/chat/five9">
    Hand off to Five9 through Open Messaging to an inbound campaign and skill.
  </Card>
</CardGroup>

## How it works

1. **Set up the integration on the CCaaS or CRM side.** Each platform expects a webhook, channel, or messaging app to be created so PolyAI has a place to deliver the conversation.
2. **Connect from Studio.** Go to **Integrations**, click **Connect** on the relevant tile, and paste the IDs and secrets generated in step 1.
3. **Write a handoff function.** Return a structured `handoff` payload from a Python tool – the payload tells PolyAI which integration to hand off to.
4. **Assign the function to a topic.** Add the tool to the Knowledge topic (or flow step) that should trigger the handoff. When that topic fires, PolyAI announces the transfer, sends the conversation to the live agent, and continues to proxy turns.

## The handoff payload

All chat handoff integrations share the same payload shape. Replace `<integration>` with the integration key (e.g. `salesforce_integration`, `nice_integration`, `amazon_connect_integration`, `genesys_integration`, `zendesk_integration`, `webex_integration`, `five9_integration`):

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def transfer_to_agent(conv: Conversation):
    return {
        "utterance": "No problem, I'll transfer you to a live agent now.",
        "handoff": {
            "text_chat": {
                "<integration>_integration": {}
            }
        }
    }
```

The `utterance` is the message the agent sends to the user immediately before the handoff. The empty object `{}` is where integration-specific parameters go – most integrations accept routing hints such as a queue ID, skill, or department.

<Tip>
  The same conversation continues in the same widget after handoff – PolyAI relays each side's messages through the same WebSocket connection. The end user never has to switch tools or re-authenticate.
</Tip>

## Choosing an integration

| If your live agents work in…       | Use                                                                                                  |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Salesforce Service Cloud Messaging | [Salesforce](/integrations/chat/salesforce)                                                          |
| Zendesk Messaging                  | [Zendesk](/integrations/chat/zendesk)                                                                |
| NICE CXone Digital                 | [NICE CXone](/integrations/chat/nice-cxone)                                                          |
| Amazon Connect chat                | [Amazon Connect](/integrations/chat/amazon-connect)                                                  |
| Genesys Cloud (Open Messaging)     | [Genesys Cloud](/integrations/messaging/genesys)                                                     |
| Webex Contact Center               | [Webex by Cisco](/integrations/chat/webex)                                                           |
| Five9 (Open Messaging)             | [Five9](/integrations/chat/five9)                                                                    |
| Anything else                      | [Contact your PolyAI account manager](/integrations/managed-services) to scope a custom integration. |

Talkdesk and other CCaaS providers can be scoped as custom integrations, contact your PolyAI account manager.

## Related pages

<CardGroup cols={3}>
  <Card title="Call handoff" icon="phone-arrow-right" href="/call-handoff/introduction">
    Voice (SIP-based) handoff configuration and the handoff context model.
  </Card>

  <Card title="Handoff API" icon="code" href="/api-reference/handoff/introduction">
    Retrieve handoff context programmatically for screen-pop or CRM enrichment.
  </Card>

  <Card title="Chat API" icon="message" href="/api-reference/chat/introduction">
    Integrate PolyAI into a custom chat surface and observe the `handoff` object.
  </Card>
</CardGroup>