Salesforce Live Chat Handoff

Let customers continue chatting in the IrisGPT website widget while support agents reply from Salesforce Messaging

Salesforce live chat handoff lets IrisGPT answer questions first and transfer the conversation to a human when needed. The customer stays in the same IrisGPT website widget, while the support agent accepts and replies to the conversation from Salesforce Service Cloud.

Before you begin

You need:

• A Salesforce Service Cloud org with Enhanced Chat (formerly Messaging for In-App and Web) and the required Digital Engagement entitlements
• Salesforce administrator access
• Omni-Channel configured for the agents who receive messaging sessions
• An IrisGPT chatbot installed on your website
• Access to the IrisAgent dashboard

This integration uses a Salesforce Enhanced Chat custom client deployment. It does not display Salesforce’s standard embedded chat widget and does not require customers to leave the IrisGPT widget.

1. Prepare Salesforce routing

If your organization already routes Enhanced Chat sessions to support agents, continue to Create a custom client deployment.

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 support agents who should receive IrisGPT handoffs.
4. Create the presence statuses agents use to become available for messaging.
5. Create and activate an Omni-Channel flow that routes the recordId input to the queue, agent, or skills used by your support team.
6. Add Enhanced Chat to the Salesforce Service Console so agents can accept and reply to sessions.

See Salesforce’s Prepare a Salesforce Org for Enhanced Chat guide for the complete routing setup.

2. Create a custom client deployment

1. In Salesforce Setup, search for Messaging Settings.
2. Create or open an Enhanced Chat messaging channel.
3. Select the Omni-Channel flow and fallback queue that should receive IrisGPT handoffs.
4. In the messaging channel settings, make sure Use reCAPTCHA or reCAPTCHA Verification is turned off, then save the channel.
5. In Salesforce Setup, search for Embedded Service Deployments, then click New Deployment.
6. Select Enhanced Chat, click Next, select Custom Client, and click Next again.
7. Name the deployment and review its generated API Name. IrisAgent uses this API name as the deployment developer name.
8. Select the Enhanced Chat messaging channel from step 2 and save the deployment.
9. Create and publish the deployment. Do not navigate away while Salesforce is publishing it.
10. Enable the Enhanced Chat REST API for the Salesforce org if it is not already enabled.

Salesforce normally publishes a custom client deployment within a few minutes. Allow up to 10 minutes for the published configuration to become available because Salesforce caches deployment changes.

Select Custom Client, not Web. A Web deployment produces an embeddedservice_bootstrap.init(...) JavaScript snippet and cannot be used by IrisAgent’s Enhanced Chat REST API integration. Salesforce does not let you convert that Web deployment into the required API deployment; create a new Custom Client deployment instead.

The current IrisAgent integration does not send a browser-generated Salesforce captchaToken. Leave reCAPTCHA disabled for the messaging channel used by this deployment. If you turn reCAPTCHA off after publishing, save the channel and republish the Custom Client deployment. See Salesforce’s reCAPTCHA requirements for API clients.

For Salesforce’s full setup flow, see Configure a Custom Client Deployment for Enhanced Chat.

3. Connect the deployment in IrisAgent

From the published custom client deployment’s configuration, copy these values:

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

Salesforce value	Example	IrisAgent field
Enhanced Chat REST API base URL	https://your-instance.salesforce-scrt.com	Service URL
Salesforce Organization ID	00D000000000000EAA	Organization ID
Deployment API/Developer Name	IrisGPT_Live_Chat_API	Deployment Name

Copy all three values from the same Salesforce org and custom client deployment. Copy the raw URL only: it must start with exactly one https://, contain no Markdown brackets, and have no path after the Salesforce hostname.

Then configure the connection:

1. Sign in to the IrisAgent dashboard.
2. Go to Deploy → Chat channels.
3. On the Salesforce Messaging card, click Configure.
4. Turn on Enable Salesforce Messaging.
5. Enter the Service URL, Organization ID, and Deployment Name from the table above.
6. Optional: enter the message IrisGPT should display when no Salesforce agent is available.
7. Click Save. The card displays Connected when Salesforce Messaging is enabled.

These settings apply to all IrisGPT website chatbot configurations for your account, including configurations created later.

Connected confirms that the values were saved and Salesforce Messaging is enabled. It does not verify that Salesforce has finished publishing the deployment or that the selected deployment is a Custom Client/API deployment. Complete the handoff test below before treating the connection as ready.

Do not enter Salesforce passwords, access tokens, session IDs, or client secrets. The three deployment values above identify the public Enhanced Chat deployment and are sufficient for this connection.

Salesforce also documents these values under Create an Enhanced Chat Deployment.

4. Enable live chat in IrisAgent

After the Salesforce Messaging card displays Connected:

1. Sign in to the IrisAgent dashboard.
2. Go to AI Products → Chatbot and click Configure and deploy.
3. Select the chatbot configuration used by your website.
4. Under Agent Handoff, select Start a live chat.
5. Save the configuration.

Make sure the data-token in your website’s IrisGPT embed snippet belongs to the same chatbot configuration. See Chatbot on Website for installation instructions.

5. Test the handoff

1. Have a Salesforce agent open the Service Console and set their Omni-Channel presence to the messaging status configured for the queue.
2. Open IrisGPT on your website and ask to speak with a human agent.
3. Confirm that IrisGPT displays a waiting or queue status.
4. Accept the Messaging Session in Salesforce.
5. Send a reply from Salesforce and confirm that it appears in the IrisGPT widget.
6. Reply from IrisGPT and confirm that the message appears in the same Salesforce session.
7. Reload the website and confirm that the conversation and live-agent connection are restored.

During a live-agent conversation, IrisGPT supports text messages. File and image attachments are not currently available in Salesforce handoff mode.

Troubleshooting

The widget says that no agents are available

• Confirm at least one assigned agent is online with the correct Omni-Channel presence status.
• Confirm the messaging channel’s flow and fallback queue are active.
• Confirm the agent is a member of the selected queue and has capacity for another Messaging Session.

The handoff remains in a waiting state

• In Salesforce, verify that the Omni-Channel flow routes the Messaging Session service channel.
• Confirm that the flow’s input variable is named exactly recordId, is text, and is available for input.
• Check that the deployment is published and the Enhanced Chat REST API is enabled.

The widget displays “There was an error processing your request”

• Wait up to 10 minutes after Salesforce reports that the deployment is published, then test again.
• Confirm the deployment type is Custom Client, not Web.
• Copy the exact DeveloperName from the Custom Client deployment. Do not use the deployment’s display label or the developer name from a standard Web deployment.
• Confirm the Organization ID, Service URL, and DeveloperName all came from the same Salesforce org and deployment.
• If Salesforce reports that the developer name is invalid, verify that the API name was copied exactly and that publication completed.
• If Salesforce reports that the deployment type is not supported or must be set to api, create and publish a new Custom Client deployment and use its developer name.
• If Salesforce reports Verification requires a valid reCAPTCHA token, disable Use reCAPTCHA in the messaging channel settings, save the channel, republish the Custom Client deployment, and allow up to 10 minutes before testing again.

Messages do not appear in IrisGPT

• Confirm the Salesforce deployment includes the exact top-level domain where the IrisGPT widget is running.
• Confirm the Organization ID, Service URL, and Deployment Name saved under Deploy → Chat channels → Salesforce Messaging match the published deployment.
• If the Salesforce deployment was replaced or renamed, update the values on the Salesforce Messaging card and save again.