> ## Documentation Index > Fetch the complete documentation index at: https://docs.cognigy.com/llms.txt > Use this file to discover all available pages before exploring further. # Salesforce MIAW Updated in 2026.4 Salesforce MIAW handover provider logo
Salesforce MIAW
## Description The Salesforce MIAW handover provider bridges Cognigy.AI and [Salesforce Messaging for In-App and Web](https://help.salesforce.com/s/articleView?id=service.miaw_intro_landing.htm\&type=5), enabling end users to connect with human agents working in a contact center that uses Salesforce. ## Prerequisites * Access to [Salesforce](https://login.salesforce.com/). * Created Endpoint [compatible with Salesforce](/ai/agents/deploy/endpoints/handover-settings#endpoints-compatible-with-handover-providers). * Give [Salesforce users access](https://help.salesforce.com/s/articleView?id=service.miaw_non_agent_permissions_1.htm\&type=5). ## Restrictions * The Salesforce MIAW handover provider supports attachments only when used with [Webchat](/webchat/overview). ## Limitations * Salesforce MIAW has file size limitations for attachments. For more information, refer to the Salesforce documentation on [File Size and Sharing Limits](https://help.salesforce.com/s/articleView?id=experience.collab_files_size_limits.htm\&type=5). ## Configuration on the Handover Provider Side 1. Log in to [Salesforce](https://login.salesforce.com/). 2. On the **Salesforce home** page, select **Setup** in the upper-right corner, then select **Setup** from the menu. 3. In the **Quick Find** box, enter `Omni-Channel Settings` and click **Omni-Channel Settings**. Alternatively, navigate to **Feature Settings > Service > Omni-Channel > Omni-Channel Settings** in the left-side menu. 4. On the **Omni-Channel Settings** page, ensure that the **Enable Omni-Channel** setting is activated. 5. In the **Quick Find** box, enter `Service Channels` and click **Service Channels**. Alternatively, navigate to **Feature Settings > Service > Omni-Channel > Service Channels** in the left-side menu. 6. Create a channel by clicking **New**. Fill in the following fields: * **Service Channel Name** – enter the name of your channel, for example, `Messaging`. * **Developer Name** – the developer name will be generated automatically as soon as you enter the service channel name. Change the developer name if needed. * **Salesforce Object** – select **Messaging Session**. In case the **Messaging Session** is not available for you, select **Case**. 7. Save changes. 1. In the **Quick Find** box, enter `Queues` and click **Queues**. Alternatively, navigate to **Users > Queues** in the left-side menu. 2. Create a new queue by clicking **New**. Fill in the following fields: * **Label** – enter the name of your channel, for example, `Messaging`. * **Queue Name** – the queue name will be generated automatically as soon as you enter the channel name. Change the queue name if needed. 3. In the **Supported Objects** section, add the following options: * **Messaging User** * **Messaging Session** * **Chat Session** * **Case** (if you selected **Case** as a Salesforce object in the **Service Channels** settings) 4. In the **Queue Members** section, add the human agents you want to include in the queue. Save changes. 1. In the **Quick Find** box, enter `Flows`, then click **Flows**. 2. To create a new flow, click **New Flow** in the upper-right corner and select **Omni-Channel Flow**. 3. Open the **Toolbox** tab by clicking the **Toggle Toolbox** button in the upper-left corner. Then, click **New Resource** on the **Manager** tab and configure the following fields: * From the **Resource Type** list, select **Variable**. * In the **API Name** field, enter `recordId`. * From the **Data Type** list, select **Text**. * Activate **Available for input**, then click **Done**. 4. In the Flow editor, click **+** to add an element. Select **Route Work** from the list. 5. In the **Label** field, enter a name for the element. The value in the **API Name** field will be generated automatically. 6. In the **Set Input Values** section, configure the following fields: * **Record ID Variable** — select `recordId`. * **Service Channel** — select the service channel that you created previously. * **Route To** — select **Queue**. 7. In the **Queue** section, select the ID related to your queue from the **Queue ID** list. 8. Click **Save** and fill in the following fields: * **Flow Label** — enter the name of your flow. * **Flow API Name** — the flow API name will be generated automatically. Change flow API name if needed. 9. Click **Activate**, then **Publish**. At this stage, you will route your flow via the queue. You can also configure routing for a specific agent, bot, or skill. For more details, refer to the Salesforce [documentation](https://help.salesforce.com/s/articleView?id=service.omnichannel_routing_targets.htm\&type=5). 1. Go back to the **Setup** page, enter `Messaging Settings` in the **Quick Find** box, and click **Messaging Settings**. Alternatively, navigate to **Feature Settings > Service > Messaging > Messaging Settings** in the left-side menu. 2. On the **Messaging Settings** page, click **New Channel**, then **Next**. Select **Messaging for In-App and Web** and fill in the following fields: * **Channel Name** — enter the name of your messaging channel. * **Developer Name** — the developer name will be created automatically. * **Deployment Type** — select the interface where users will interact with Salesforce MIAW: * **Web** — you need to enter the URL of the website on which users can interact with Salesforce MIAW in the **Domain** field. * **Mobile** 3. In the **Channel Routing** section, configure the following: * **Routing Type** — select **Omni-Flow**. * **Flow Definition** — enter the Flow name that you created. * **Fallback Queue** — enter the queue name that you created. Save changes. 4. Ensure that your channel is active. On the **Messaging Settings** page, check if the channel is marked as **Active** in the **Active** column. If not, select your channel and click **Activate** in the upper-right corner. 1. In the **Quick Find** box, enter `Embedded Service Deployments` and click **Embedded Service Deployments**. Alternatively, navigate to **Feature Settings > Service > Messaging > Embedded Service Deployments** in the left-side menu. 2. On the **Embedded Service Deployments** page, click **New Deployment**. 3. Select the **Messaging for In-App and Web** type, then **Custom Client**. Fill in the following fields: * **Embedded Service Deployment Name** — enter the name of your deployment. * **API Name** — the API name will be created automatically. Change API name if needed. 4. From the **Messaging Channel** list, select the channel you created previously. Save changes. 5. Go to **Code Snippet**. Copy the `OrganizationId`, `DeveloperName`, and `Url` values for later use in Cognigy.AI. 6. Click **Done**. Check whether your deployment is active and click **Publish**. The deployment will take about 10 minutes. Afterward, you can go to Cognigy.AI to configure the handover settings. ## Configuration on the Cognigy.AI Side 1. Go to **Build > Handover Providers** and click **+ New Handover Provider**. 2. In the **New Handover Provider** window, select **Salesforce MIAW** from the list and name the connector. 3. *(Optional)* Activate the **Forward Events to the Flow** setting. This setting forwards any event to the Flow, which can be handled in the Lookup Node. Select the **Handover Status** type in the Lookup Node. In the Case Node, select **Events** from the **Handover Status** list. Agent Replies and Conversation Closed events are not forwarded. 4. Fill in the following fields: | **Field** | **Description** | | ------------------------------- | --------------------------------------------------------------------------------------- | | Base URL | The URL of your configured service in Salesforce, copied from `Url`. | | Organization ID | The unique identifier of your organization in Salesforce, copied from `OrganizationId`. | | Embedded Service Developer Name | The ID of your deployment in Salesforce, copied from `DeveloperName`. | | Capabilities Version | The API version is `1`. | In the **Salesforce Settings** section of the [Handover to Human Agent](/ai/agents/develop/node-reference/service/handover-to-agent) Node, configure the following settings: * **Send Transcript as first message** — the setting allows Salesforce to receive the conversation transcript as the first message. If the transcript exceeds 3000 characters, it is split into multiple messages. This setting is turned off by default. * **Conversation Routing Attributes** — the setting supports key-value pairs, where the keys are variables you manually specify in the Omni-Channel flow in Salesforce. To specify variables, follow the [Map Pre-Chat Values in Omni-Channel Flow](https://help.salesforce.com/s/articleView?id=service.miaw_map_messaging_2.htm) guide in the Salesforce documentation. Then, enter the key-value pairs in JSON format. For example: ```json theme={null} { "customerName": "John Doe", "issueType": "Billing" } ``` where `customerName` and `issueType` are variables you specified on the Salesforce side, and `John Doe` and `Billing` are the values you want to pass to the flow in Salesforce. * **Identity Token for Authenticated Users** — the setting allows you to specify an access token generated via the [Salesforce API](https://developer.salesforce.com/docs/service/messaging-api/references/miaw-api-reference?meta=generateAccessTokenForAuthenticatedUser). This token enables users who have already authenticated within your system to interact securely with Salesforce MIAW. Before using this token, [set up user verification](https://help.salesforce.com/s/articleView?id=sf.user_verification_setup.htm) on the Salesforce side. By default, the setting is turned off, meaning that unauthenticated users can interact with Salesforce MIAW. * **Enable User Connects Message** - the setting allows you to notify human agents when an end user reconnects to the chat. The parameter is enabled by default. When the parameter is enabled, the message `User joined the conversation` appears in the chat as soon as the end user opens a new URL on the same tab as the chat and then returns to the chat tab by clicking the **←** (back arrow) at the top bar in the browser. * **Enable User Disconnects Message** - the setting allows you to notify human agents when an end user disconnects from the chat. The parameter is enabled by default. When the parameter is enabled, the message `User left the conversation` is sent as soon as the user closes the tab with the chat or switches to a new URL address within the current tab. * **End Chat When Agent Leaves** — the setting allows the handover to end automatically when a human agent is removed from a Salesforce MIAW conversation. This setting is turned off by default. Instead of waiting for the conversation close event, which [Salesforce may not always send](https://help.salesforce.com/s/articleView?id=000397177\&type=1), this setting relies on the participant change event to trigger the end of the handover. Test your Flow to ensure it works as expected. You can use Demo Webchat to send messages to the Salesforce contact center. On the Salesforce side, go to the Service Console. In the Service Console, open [Messaging Sessions](https://help.salesforce.com/s/articleView?id=service.livemessage_create_console_app.htm\&type=5), and make sure that your human agent is online. ## Additional Configuration ### Agent Copilot Workspace Within the Salesforce MIAW integration, you can use the [Agent Copilot workspace](/agent-copilot/overview) as an assistant to your human agents. By default, two versions of the application are provided: Agent Copilot will be available as a standalone application via the following link: `https://${AgentCopilotBaseUrl}/?userId=${userId}&sessionId=${sessionId}&URLToken=${URLToken}` Where: * `AICopilotBaseUrl` — the base URL used to access the Agent Copilot workspace. * `sessionId` — the Cognigy session ID. A session represents the interaction between the human agent and the Agent Copilot workspace. * `userId` — the Cognigy user ID. It helps Agent Copilot associate the interaction with a specific user. * `URLToken` — the Endpoint token from Cognigy.AI. The Endpoint must be linked to the Handover Flow. To find this token, go to the Endpoint that you created previously. In the **Endpoint URL** field, copy the token after `https://endpoint-trial.cognigy.ai/`. For example, in the URL `https://endpoint-trial.cognigy.ai/f38791ae20d4961acf0e97d9f377c4fe3df92894e1eff1c7a774a8ed089a4590`, the token is `f38791ae20d4961acf0e97d9f377c4fe3df92894e1eff1c7a774a8ed089a4590`. Only authorized users can access the Agent Copilot system through this URL. Example URL: ```txt wrap theme={null} https://ai-copilot-trial.cognigy.ai/?sessionId=session123&userId=user123&URLToken=a4d5c86c98f27730311591f28d194510e05ffed30ca148e3344970defd418e7d ``` To use the embedded version of the Agent Copilot workspace, you need to update the settings on the Salesforce side and configure the Agent Copilot UI components. 1. In the [Salesforce](https://login.salesforce.com/) interface, go to **Setup > Messaging Settings** and select the messaging channel that you created previously. 2. In the messaging channel, go to **Custom Parameters** and click **New**. 3. In the **New Custom Parameter** window, configure the following parameters: * **Parameter Name** — enter **Copilot URL**. * **Parameter API Name** — the parameter API name will be generated automatically as soon as you enter the parameter name. Change the parameter API name if needed. * **Channel Variable Name** — the channel variable name will be generated automatically as soon as you enter the parameter name. Change the channel variable name if needed. * **Data Type** — select **String**. * **Maximum Length** — enter `255`. Save changes. 4. In the **Parameter Mappings** section, click **New**. 5. In the **New Parameter Mapping** window, configure the following parameters: * **Parameter** — select **Copilot URL** that was added under **Custom Parameters**. * **Flow Variable Name** — enter `copilotUrl`.
Save changes. 1. In the **Quick Find** box, enter `Embedded Service Deployments` and click **Embedded Service Deployments**. Alternatively, navigate to **Feature Settings > Service > Messaging > Embedded Service Deployments** in the left-side menu. 2. Select the deployment that you created previously, then select **Pre-Chat**. 3. Enable the **Activate the pre-chat feature** setting. 4. Go to the **Visible Pre-Chat Fields** section, click **Add > Custom**. 5. In the **New Custom** window, fill in the following fields: * **Field Type** — select **text**. * **Channel Variable Name** — select `Copilot_URL` that you added in **Messaging Settings** previously.
Save changes. 6. Click **Save**. On the **Embedded Service Deployment Settings** page, click **Publish**. 1. In the **Quick Find** box, enter `Flows`, then click **Flows**. Alternatively, navigate to **Feature Settings > Service > Messaging > Flows** in the left-side menu. 2. Go to the Flow that you created previously. 3. Open the **Toolbox** tab by clicking the **Toggle Toolbox** button in the upper-left corner. Then, click **New Resource** on the **Manager** tab and configure the following fields: 1. From the **Resource Type** list, select **Variable**. 2. In the **API Name** field, enter `copilotUrl`. 3. From the **Data Type** list, select **Text**. 4. Activate **Available for Input**, then click **Done**. 4. In the Flow editor, above the **Route Work** action, click **+** to add an element. Select **Update Records** from the list. 5. In the **Label** field, enter a name for the element. The value in the **API Name** field will be generated automatically. 6. In the **How to Find Records to Update and Set Their Values** section, select **Specify conditions to identify records**. 7. In the **Update Records of This Object Type** section, select **Messaging Session** from the **Object** list. 8. In the **Filter Messaging Session Records** section, configure the following fields: * **Condition Requirement to Update Records** — select **All Conditions Are Met (AND)**. * **Field** — enter `Id`. * **Operator** — select **Equals**. * **Value** — enter `recordId`. 9. In the **Set Field Values for the Messaging Session Records** section, configure the following fields: * **Field** — enter `Copilot__c`. * **Value** — enter `copilotUrl`. 10. Click **Save a New Version**, then **Activate**. To configure the Agent Copilot UI components, refer to the [Salesforce Integrations](https://github.com/Cognigy/salesforce-integrations) documentation on GitHub. Once the components are configured, you can test the embedded Agent Copilot workspace using [Demo Webchat](/webchat/demo). If you used an embedded Agent Copilot workspace with the [deprecated Salesforce integration](/ai/escalate/handover-reference/salesforce) and migrated to Salesforce MIAW, you need to update the Agent Copilot UI components. Refer to the [Set up the Component](https://github.com/Cognigy/salesforce-integrations?tab=readme-ov-file#set-up-the-componentrefer) documentation on GitHub. #### Automated Messaging Components The Salesforce MIAW integration supports automated messaging components for sending auto-responses during messaging sessions, such as welcome messages, inactivity reminders, and survey links. To learn how to use these components, refer to the [Salesforce documentation on Automated Messaging Components](https://help.salesforce.com/s/articleView?id=service.messaging_components_auto_response.htm\&type=5). ### Prevent Conversations from Automatically Closing Cognigy.AI prevents Salesforce MIAW chats from closing automatically when human agents leave the conversation and continues polling for new events. #### Cognigy.AI 2025.16 and earlier Salesforce MIAW chat closes automatically when a human agent leaves the conversation. You can control this behavior by setting the `DISABLE_ABORT_HANDOVER_ON_SALESFORCE_MIAW_PARTICIPANT_CHANGE` variable in the `values.yaml` file. By default, this variable is set to `false`. Setting it to `true` keeps the conversation open after human agents leave and continues polling for new events. ### Access Token Expiration When a handover starts, Salesforce MIAW provides an access token with a configurable expiration time to Cognigy.AI in the backend. To make sure that the session is synchronized, Cognigy.AI polls Salesforce MIAW approximately every 2 minutes to check for new messages or actions, and verifies if the access token is still valid. Additionally, Cognigy.AI has a configurable grace period, counted from the end of the access token expiration time to control the session termination. The default grace period is 30 minutes. When the grace period is reached, Cognigy.AI terminates the session on both Cognigy.AI and Salesforce MIAW sides. This approach prevents unnecessary API calls to Salesforce MIAW sessions with expired access tokens. 1. On the **Salesforce home** page, click **Setup** in the upper-right corner, then select **Setup** from the menu. 2. In the **Quick Find** box, enter `Messaging Settings` and follow the **Feature Settings > Service > Messaging** path. 3. On the **Messaging Settings** page, click the **Show one more action** arrow next to the channel you want to configure, and select **Edit**. 4. On the **Messaging for In-App and Web** page, configure as follows: * Without user verification — enter the expiration time in **Authorization Token Expiration Time for Unverified Users**. The default value is 360 minutes. Save changes. * With user verification — select **Add User Verification** and enter the expiration time in **Authorization Token Expiration Time for Verified Users**. The default value is 60 minutes. Save changes. * For on-premises installations, set the grace period in seconds using the `SALESFORCE_MIAW_ACCESS_TOKEN_GRACE_PERIOD` variable in the `values.yaml` file. * For SaaS installations, contact [Cognigy Support](/help/get-help). If you have an access token expiration time of 6 hours (360 minutes) and a grace period of 30 minutes, Cognigy.AI terminates the session on both platforms 5 hours and 30 minutes after the handover started. ### Mark Conversations as Inactive Human agents managing multiple active conversations can quickly reach capacity. Without a way to pause unresolved sessions, new incoming conversations may be delayed, affecting response times. Your human agents can temporarily pause unresolved conversations by marking them as inactive. This approach frees up capacity for new sessions while still allowing customers to reconnect later. To mark a conversation as inactive, open it in Salesforce MIAW, click the dropdown next to **End Chat**, and select **Customer Inactive**. For more details, refer to [Ending or Inactivating Messaging Sessions Automatically](https://help.salesforce.com/s/articleView?id=service.messaging_auto_end.htm\&type=5) and [Inactivate a Messaging Session](https://help.salesforce.com/s/articleView?id=service.livemessage_agent_inactivate_session.htm\&type=5) in the Salesforce documentation. ## Troubleshooting | Possible Error | How to Resolve | | ----------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Could not find field `Copilot__c`. Make sure to add this field to your Salesforce installation. | An embedded Agent Copilot doesn't work. Make sure that you've updated the settings in Salesforce. Check your flow and make sure that `Copilot__c` is included in the **Update Records** action. | | You are trying to pull data from a Live Chat transcript while you are on a Messaging session. | This error occurs when you migrate from the [deprecated Salesforce integration](/ai/escalate/handover-reference/salesforce) to Salesforce MIAW without updating the Agent Copilot UI components. To update the components, refer to the [Set up the Component](https://github.com/Cognigy/salesforce-integrations?tab=readme-ov-file#set-up-the-componentrefer) documentation on GitHub. | | Login to Omni-Channel failed. | This error occurs when a resource limit is exceeded. In the Salesforce Console, delete old messaging sessions, chat transcripts, and chat sessions. This action frees up space. | ## More Information * [All Handover Providers](/ai/escalate/handover-reference/overview) * [Handovers](/ai/escalate/handovers)