Skip to main content

​
Description

The Salesforce MIAW handover provider bridges Cognigy.AI and Salesforce Messaging for In-App and Web, enabling end users to connect with human agents working in a contact center that uses Salesforce.

​
Prerequisites

​
Restrictions

  • The Salesforce MIAW handover provider supports attachments only when used with Webchat.

​
Limitations

  • Salesforce MIAW has file size limitations for attachments. For more information, refer to the Salesforce documentation on File Size and Sharing Limits.

​
Configuration on the Handover Provider Side

  1. Log in to Salesforce.
  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.
  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:
FieldDescription
Base URLThe URL of your configured service in Salesforce, copied from Url.
Organization IDThe unique identifier of your organization in Salesforce, copied from OrganizationId.
Embedded Service Developer NameThe ID of your deployment in Salesforce, copied from DeveloperName.
Capabilities VersionThe API version is 1.
In the Salesforce Settings section of the 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 guide in the Salesforce documentation. Then, enter the key-value pairs in JSON format. For example: 
    {
  "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. 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 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 Handover on Participant Change — 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, 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, 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 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://${AICopilotBaseUrl}/?userId=${userId}&sessionId=${sessionId}&URLToken=${URLToken}Where:
  • AICopilotBaseUrl — the base URL of Agent Copilot. It represents the main web address where the Agent Copilot service is hosted.
  • sessionId — the Cognigy session ID. A session is a period of interaction or communication 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, allowing for tracking user-specific information.
  • URLToken — the Endpoint token on the Cognigy side. To find this token, navigate to the Endpoint linked with Agent Copilot. In the Config URL field, copy the token found after https://endpoint-trial.cognigy.ai. For example, in the URL https://endpoint-trial.cognigy.ai/f38791ae20d4961acf0e97d9f377c4fe3df92894e1eff1c7a774a8ed089a4590, the token would be f38791ae20d4961acf0e97d9f377c4fe3df92894e1eff1c7a774a8ed089a4590. Note that only authorized users can access or interact with the Agent Copilot system through this URL.
For example:https://agent-copilot-trial.cognigy.ai/?sessionId=session-17738489-e767-4d47-b669-cb0dd2e899e0&userId=52476cc5-710c-40db-8108-e99109f45d91&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 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 documentation on GitHub. Once the components are configured, you can test the embedded Agent Copilot workspace using Demo Webchat.If you used an embedded Agent Copilot workspace with the deprecated Salesforce integration and migrated to Salesforce MIAW, you need to update the Agent Copilot UI components. Refer to the Set up the Component 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 Salesforce documentation on Automated Messaging Components.

​
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 and select Edit arrow next to the channel you want to configure. Show one more action and select Edit arrow next to the channel you want to configure.
  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 dedicated SaaS and shared SaaS installations, contact Cognigy Support.
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 and Inactivate a Messaging Session in the Salesforce documentation.

​
Troubleshooting

Possible ErrorHow 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 to Salesforce MIAW without updating the Agent Copilot UI components. To update the components, refer to the Set up the Component 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

⌘I