Skip to main content
Hand off a live webchat or SMS conversation from your PolyAI agent to a Salesforce Service Cloud Messaging agent. PolyAI continues to proxy messages between the end user and the Salesforce agent for the rest of the session, so the user stays in the same widget.
This integration is available from Configure > Integrations > Salesforce Messaging in Agent Studio.

​
Prerequisites

  • A Salesforce org with Service Cloud and Messaging for In-App and Web enabled.
  • Salesforce administrator access to create a Messaging channel and a Connected App.
  • A PolyAI project with at least one Knowledge topic that should escalate to a human.

​
1. Set up Salesforce

PolyAI connects to Salesforce through the Bring Your Own Channel integration. You will need:
  1. A Messaging channel in Salesforce Setup (Messaging Settings) for PolyAI to hand conversations into.
  2. A Connected App with OAuth enabled so PolyAI can authenticate against Salesforce’s Messaging API.
  3. Omni-Channel routing configured so that messages on this channel land in a queue or skill that human agents are subscribed to.
Your PolyAI contact will walk you through the exact fields and OAuth scopes required for your Salesforce edition. For broader Salesforce CRM access (case lookup, account data), see the Salesforce CRM integration – the two integrations can coexist on the same project.

​
2. Connect from Studio

In Agent Studio, open Configure > Integrations and click Connect on the Salesforce Messaging tile. Paste the credentials and IDs from your Connected App and Messaging channel setup.

​
3. Write the handoff function

Add a Python tool that returns the chat handoff payload. The empty object lets you pass routing hints later (queue or skill) if needed. 
def transfer_to_salesforce(conv: Conversation):
    return {
        "utterance": "No problem, I'll transfer you to one of our agents now.",
        "handoff": {
            "text_chat": {
                "salesforce_integration": {}
            }
        }
    }

​
4. Assign the function to a topic

Open the Knowledge topic that should escalate to a live agent, add an Action, and select the transfer_to_salesforce function. When that topic fires, PolyAI delivers the utterance to the user, opens a Salesforce Messaging conversation, and proxies subsequent turns between the two sides. You can call the same function from a flow step or directly via conv.call_handoff() if you need more dynamic routing.

​
5. Verify

  1. Start a session in your webchat widget (or send an SMS, if SMS is wired up) and steer the conversation into the topic you wired the handoff to.
  2. Confirm that the utterance is sent and that a new conversation appears in the Salesforce Omni-Channel inbox for the routing queue you configured.
  3. Reply from Salesforce and confirm the message is delivered back to the user inside the original widget.
  4. End the session from the Salesforce side and confirm the widget shows the conversation as closed.
If nothing arrives in Salesforce, check Configure > Integrations > Salesforce Messaging for connection errors, and confirm the Connected App is approved for the user PolyAI is authenticating as.

Salesforce CRM

Customer record lookup and case management.

Chat handoff overview

All chat handoff integrations and the shared payload shape.
Last modified on June 16, 2026