Chat handoff integrations

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.

Available integrations

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):

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.

Choosing an integration

Five9 chat handoff is on the roadmap. Talkdesk and other CCaaS providers can be scoped as custom integrations — contact your PolyAI account manager.

Related pages