Salesforce Live Chat Handoff

Hand off IrisGPT website chats to agents in Salesforce Messaging while customers stay in the same widget

IrisGPT answers first and hands the chat to a human when needed. The customer stays in the IrisGPT widget, and the agent replies from Salesforce Service Cloud.

​

Before you begin

• Salesforce Service Cloud with Enhanced Chat (formerly Messaging for In-App and Web) and the required Digital Engagement entitlements
• Salesforce admin access
• Omni-Channel set up for the agents who take messaging sessions
• An IrisGPT chatbot on your website, and access to the IrisAgent dashboard

This uses a Salesforce Enhanced Chat Custom Client deployment. Salesforce’s standard chat widget is not shown.

​

1. Prepare Salesforce routing

Skip to step 2 if Enhanced Chat sessions already route to your agents. Otherwise, in Salesforce Setup:

1. Enable Omni-Channel.
2. Create a service channel for the Messaging Session object.
3. Create a queue and add the agents who should get IrisGPT handoffs.
4. Create presence statuses for messaging.
5. Create and activate an Omni-Channel flow that routes the recordId input to your queue, agent, or skills.
6. Add Enhanced Chat to the Service Console.

Full guide: Prepare a Salesforce Org for Enhanced Chat.

​

2. Create a custom client deployment

1. In Setup, open Messaging Settings and create or open an Enhanced Chat channel.
2. Select the Omni-Channel flow and fallback queue for IrisGPT handoffs.
3. Turn off Use reCAPTCHA (or reCAPTCHA Verification) and save the channel.
4. In Setup, open Embedded Service Deployments and click New Deployment.
5. Select Enhanced Chat → Next → Custom Client → Next.
6. Name the deployment. Its API Name is the deployment name IrisAgent uses.
7. Select the channel from step 1 and save.
8. Publish the deployment. Stay on the page until it finishes.
9. Enable the Enhanced Chat REST API for the org if it is not already on.

Allow up to 10 minutes after publishing for Salesforce to make the deployment available.

• Choose Custom Client, not Web. A Web deployment cannot be converted and does not work with IrisAgent. Create a new Custom Client deployment instead.
• Keep reCAPTCHA off. IrisAgent does not send a Salesforce captchaToken. If you turn reCAPTCHA off after publishing, save the channel and republish. See reCAPTCHA requirements for API clients.

Salesforce reference: Configure a Custom Client Deployment for Enhanced Chat.

​

3. Connect the deployment in IrisAgent

Copy these values from the published deployment’s configuration (all from the same org and deployment):

{
  "OrganizationId": "00D000000000000EAA",
  "DeveloperName": "IrisGPT_Live_Chat_API",
  "Url": "https://your-instance.salesforce-scrt.com"
}

Salesforce value	IrisAgent field
Enhanced Chat REST API base URL (Url)	Service URL
Salesforce Organization ID (OrganizationId)	Organization ID
Deployment API/Developer Name (DeveloperName)	Deployment Name

The Service URL must start with exactly one https://, have no Markdown brackets, and have no path after the hostname.

1. In the IrisAgent dashboard, go to Deploy → Chat channels.
2. On the Salesforce Messaging card, click Configure.
3. Turn on Enable Salesforce Messaging.
4. Enter Service URL, Organization ID, and Deployment Name.
5. Optional: enter a No-agent reply to show when no agent is available.
6. Click Save. The card shows Connected.

These settings apply to all your IrisGPT website chatbot configurations, including future ones.

Connected only means the values are saved. It does not confirm the deployment is published or is a Custom Client. Run the test in step 5.

Do not enter Salesforce passwords, tokens, session IDs, or client secrets. The three values above are all you need.

​

4. Turn on live chat handoff

1. Go to AI Products → Chatbot and click Configure and deploy.
2. Open the chatbot configuration your website uses.
3. Under Agent Handoff, select Start a live chat and save.

The data-token in your website’s embed snippet must belong to this configuration. See Chatbot on Website.

​

5. Test the handoff

1. Have an agent open the Service Console and set the Omni-Channel presence used by the queue.
2. On your website, ask IrisGPT for a human.
3. Check that IrisGPT shows a waiting or queue status.
4. Accept the Messaging Session in Salesforce and send a reply. It should appear in the widget.
5. Reply from the widget. It should appear in the same Salesforce session.
6. Reload the website. The conversation and agent connection should be restored.

Handoff supports text only. File and image attachments are not available.

​

Troubleshooting

“No agents are available”

• At least one agent in the queue must be online with the right presence status and have capacity.
• The channel’s flow and fallback queue must be active.

Stuck in waiting

• The Omni-Channel flow must route the Messaging Session service channel.
• The flow’s input variable must be named exactly recordId, be text, and be available for input.
• The deployment must be published and the Enhanced Chat REST API enabled.

“There was an error processing your request”

• Wait up to 10 minutes after publishing, then retry.
• Confirm the deployment type is Custom Client, not Web.
• Use the exact DeveloperName (API name), not the display label or a Web deployment’s name.
• Confirm all three values come from the same org and deployment.
• If Salesforce says the deployment type is unsupported or must be api, create and publish a new Custom Client deployment.
• If you see Verification requires a valid reCAPTCHA token, turn off Use reCAPTCHA, save the channel, republish, and wait up to 10 minutes.

Messages do not appear in IrisGPT

• The Salesforce deployment must include the exact top-level domain where the widget runs.
• The values on the Salesforce Messaging card must match the published deployment. Update them if the deployment was replaced or renamed.