> ## Documentation Index
> Fetch the complete documentation index at: https://docs.irisagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Note>
  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.
</Note>

## 1. Prepare Salesforce routing

If your organization already routes Enhanced Chat sessions to support agents, continue to [Create a custom client deployment](#2-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](https://help.salesforce.com/s/articleView?id=sf.miaw_prepare_org_1.htm\&type=5) 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.

<Warning>
  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.
</Warning>

<Warning>
  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](https://developer.salesforce.com/docs/service/messaging-api/guide/setup-recaptcha.html).
</Warning>

For Salesforce's full setup flow, see [Configure a Custom Client Deployment for Enhanced Chat](https://help.salesforce.com/s/articleView?id=sf.miaw_deployment_custom.htm\&type=5).

## 3. Connect the deployment in IrisAgent

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

```json theme={null}
{
  "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](https://web.irisagent.com/).
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.

<Note>
  **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.
</Note>

<Warning>
  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.
</Warning>

Salesforce also documents these values under [Create an Enhanced Chat Deployment](https://help.salesforce.com/s/articleView?id=mktg.persnl_agentforce_embedded_service.htm\&type=5).

## 4. Enable live chat in IrisAgent

After the **Salesforce Messaging** card displays **Connected**:

1. Sign in to the [IrisAgent dashboard](https://web.irisagent.com/).
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](/deploying-irisagent/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.