Salesforce Live Chat Handoff

​

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

​

1. Prepare Salesforce routing

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.

​

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.

​

3. Connect the deployment in IrisAgent

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

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.

​

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.

​

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.

​

6. Optional: Send pre-chat answers to your Omni-Channel flow

​

Plan your fields

• The IrisAgent field key: the snake_case key of the procedure field that collects it (for example, i_am_a).
• The Salesforce Channel Variable Name it maps to.
• The exact values the flow compares against, if it branches on the field.

​

Set up Salesforce

1. Standard fields (first name, last name, email, subject) use the built-in names _firstName, _lastName, _email, and _subject. Keep them enabled in the deployment’s pre-chat settings. They need no parameter mapping.
2. Custom fields: in Setup, open Messaging Settings, open your Enhanced Chat channel, and add a Parameter Mapping for each field. Each mapping has a Parameter API Name and a Channel Variable Name, and they can differ. IrisAgent sends the Channel Variable Name, so that is the name to send us.
3. In the channel’s Omni-Channel flow, create an input variable for each field. Make it Text and select Available for input, then map the channel variable to it.
4. In Embedded Service Deployments, add each custom field to the deployment’s pre-chat fields. Hidden fields work, since IrisGPT asks the questions. Then republish the deployment.

​

Create the intake procedure in IrisAgent

1. Go to Automate → Procedures and create or edit the procedure that runs when a customer asks for a human. See Workflows.
2. Choose Instructions for AI Agent.
3. Under Information to collect, add one field per row of your table, in the order the AI should ask. Check that each field’s key matches your IrisAgent field key exactly.
4. In the steps, give the exact allowed values for every field the flow branches on, and finish with the handoff. For example:
   1. Ask: "Which best describes you: Participant, Retiree, Beneficiary, or Other?"
      Record i_am_a as exactly one of: Participant, Retiree, Beneficiary, Other.
      If the answer is unclear, ask once more with the options, then record Other.
   2. Ask for their first name.
   3. Ask for their last name.
   4. Ask for their email address.
   5. Ask what their question or issue is about.
   After collecting everything, say "Thank you. I'm connecting you with a representative now."
   Escalate the conversation.
   
5. Under Availability, select Chat so email and voice conversations do not get these questions, then save.

​

Ask IrisAgent to turn it on

​

How the answers are sent

• Only the fields in your mapping are sent as routing attributes. Other answers the procedure collects are not.
• Values are sent once, when the Salesforce session starts. Answers given after the handoff are not sent.
• If a customer answered the same field more than once, the latest answer is sent.
• Empty answers, and answers longer than 255 characters, are skipped.
• The answers are not stored with the chat or shown in the widget.
• The chat transcript passed to your agent still contains every message the customer typed, including answers to questions you did not map. Do not rely on the mapping to keep information out of Salesforce.

​

Test it

1. Start a chat on your website (or sandbox), ask for a human, and answer every question.
2. Accept the Messaging Session in Salesforce.
3. Check that the session’s fields are filled in, or use a Flow debug run, and that the flow took the expected branch.

​

Troubleshooting

• 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.

• 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.

• 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.

• Use the Channel Variable Name in the mapping, not the Parameter API Name.
• The flow variable must be Text and Available for input, and the channel variable must be mapped to it.
• Each custom field must be on the deployment’s pre-chat field list, and the deployment must be republished.
• The procedure must collect every field before it hands off. Values are only sent when the session starts.

• The value IrisGPT sends must match the flow’s comparison value exactly, including capitalization. List the allowed values in the procedure steps.

• 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.