Salesforce voice integration with Twilio Flex

This voice integration makes use of the Twilio Open CTI integration to bring a Twilio Flex call center into your Salesforce instance.

Agent Assist uses the media stream from the Twilio Flex call to provide suggestions to your agents in the Salesforce Lightning Service Console.

Before you begin

To integrate Agent Assist UI modules with Salesforce, you need access to the following resources:

  • Node.js

    Follow the recommended installation instructions for your operating system.

  • Salesforce CLI

    Follow the recommended installation instructions for your operating system.

  • Google Cloud CLI

    Install the gcloud command as instructed and authenticate using gcloud auth login.

  • Salesforce

    1. Sign in at your instance URL or the Salesforce sign-in page and note the following:
    2. Your Salesforce My Domain URL. Follow these steps to find the My Domain URL:
      1. Navigate to the menu bar > Setup menu.
      2. Click Setup.
      3. In the Quick Find box, enter My Domain. The domain name is in the following format: MY-DOMAIN-NAME.develop.my.salesforce.com.
    3. Your Salesforce organization ID. Follow these steps to find the organization ID:
      1. Navigate to the menu bar > Setup menu.
      2. Click Setup.
      3. In the Quick Find box, enter Company Information. Note: These integration steps have been tested with Salesforce Developer Edition only. Differences in feature licenses and the Salesforce interface might arise if you use another edition.

  • Agent Assist integration backend

    1. Follow the instructions to set up the integration.
    2. Before running the deploy script, configure the following environment variables with deploy.sh, or in an .env file at the project root:
    3. AUTH_OPTION: Set this to SalesforceLWC.
    4. SALESFORCE_DOMAIN: A domain name similar to YOUR_SUBDOMAIN.develop.lightning.force.com. You noted this value in the Salesforce prerequisite. Note that you shouldn't include https://.
    5. SALESFORCE_ORGANIZATION_ID: You noted this value in the Salesforce prerequisite.
    6. APP_AUTH_OPTION: Set this to Twilio.
    7. TWILIO_ACCOUNT_SID: Set this to your Twilio Account SID.

Step 1: Set up Twilio Flex

Twilio Flex serves as the softphone in this integration. You can sign in to the Twilio console to set up a Flex account. Visit the Twilio setup page to get detailed instructions on how to create a Flex account.

Install SIPREC connector add-on

The SIPREC connector add-on allows your Twilio Flex account to make SIPREC forks of voice call media streams to Agent Assist. Follow these steps to install the SIPREC connector add-on.

  1. Navigate to Twilio Home > Marketplace > Catalog > Twilio > Siprec Connector.
  2. Click Install > the terms and conditions acknowledgment checkbox > Install.
  3. On the Configure tab, configure the plugin as follows:
    1. Unique Name: SipRec1
    2. Session Recording Server: 
      sip:+<GTP-provisioned-phone-number>@216.239.36.145:5672;transport=tls;secure=true;edge=umatilla
    3. See the telephony integration documentation for more details on provisioning a GTP number. You can ignore the SBC configuration and validation steps, because they're complete for the Twilio Siprec connector.
  4. Navigate to Twilio Home > Functions and Assets.
    • If Functions and Assets is not visible in the sidebar, pin it from Explore Products.
  5. Click Create Service.
  6. Name the new service ui-connector-auth.
  7. In the editor that appears, click Add + > Add Function.
  8. Name the function conversation-name.
  9. Click , and change the function visibility to Public.
  10. Copy and paste the entire contents of ui-connector-auth.js from the GitHub repository into the editor.
  11. Click Save.
  12. Click Deploy All.

Configure IVR with Flex Studio

The IVR consists of configuring a programmatic call flow with Twilio Studio to make the SIPREC fork of the media stream to Agent Assist. It also makes an HTTP post to share the phone number and conversation Id with Agent Assist. Follow these steps to configure IVR with Flex Studio.

  1. Navigate to the Twilio Console
  2. Click Develop > Phone Numbers > Manage > Active Numbers. There should be one row in the table with the default Twilio number provisioned for your Flex Account.
  3. In the Voice - Studio Workflow section, click Voice IVR.
  4. Drag a Make HTTP Request widget into the flow.
  5. Disconnect Incoming Call from the SendCallToAgent widget's input.
  6. Connect Incoming Call to the Make HTTP Request widget's input.
  7. Configure the Make HTTP Request widget with the following details:
    • Widget Name: register_twilio
    • Request Method: POST
    • Request URL: <your-ui-connector-cloud-run-url>.run.app/register-app
    • Content type: Application/JSON
    • Request body: 
      {
"accountSid": "<yourTwilioAccountSid>",
"authToken": "<yourTwilioAccountAuthToken>"
}
  8. Drag a Run Function widget into the flow.
  9. Connect the Success and Fail outputs of the register_twilio widget to the input of the Run Function widget.
  10. Create a widget with the following details:
    • Widget Name: conversation_name
    • Service: ui-connector-auth
    • Environment: ui
    • Function: conversation-name
    • Function Parameters:
      • token: 
        {{ widgets.register_twilio.parsed.token }}
      • endpoint: <your-ui-connector-cloud-run-url>.run.app/conversation-name
      • phone: 
        {{ trigger.call.From | replace_first:'+','' }}
      • conversationName: 
        projects/<project>/locations/<location>/conversations/TW-{{ trigger.call.From | replace_first:'+','' }}-{{ trigger.call.CallSid }}
  11. Drag a Fork Stream widget from the sidebar into the flow.
  12. Connect the Success and Fail outputs of the Make HTTP Request widget to the input of the Fork Stream widget.
  13. Connect the Next node of the Fork Stream widget to the SendCallToAgent widget.

  14. Configure the Fork Stream widget as follows:

    • Stream Action: Start
    • Stream Type: Siprec
    • Connector Name: Siprec1
    • Tracks: Both Tracks

    • Stream Parameters:

      • Key: conversation

      • Value:

        projects/<gcp-project-id>/conversations/TW-{{trigger.call.From | replace_first:'+','' }}-{{trigger.call.CallSid}}

  15. Click Save > Publish.

Account details

Follow this step to collect your Twilio Flex account details. You need this information to configure the Flex CTI in Salesforce later.

  1. Navigate to Twilio Home > Account Dashboard, and write down the following information:
    • Account SID
    • My Twilio phone number

Step 2: Set up your development project

To start integrating Agent Assist UI modules, follow these steps.

  1. Run the following code to clone the Agent Assist integration repository and open your project: 
    git clone https://github.com/GoogleCloudPlatform/agent-assist-integrations
cd salesforce/aa-lwc
  2. Run the following commands to download the UI modules JavaScript files which you deploy later as Static Resources. Salesforce requires static resources to load third-party JavaScript. 
    npm run generate-static-resources
npm install

Step 3: Set up your Salesforce environment

You can integrate Agent Assist UI modules in a specific environment, such as production or development. Salesforce calls these environments organizations (orgs).

Configure your org with the Salesforce CLI

Follow these steps to use the Salesforce CLI to configure your org for Agent Assist integration.

  1. Run the following code and authenticate the CLI using the Salesforce login details you normally use. 
    npm run login
  2. Run the following code to deploy the LWC to the org. 
    npm run deploy

Step 4: Create an external client app

The Salesforce LWC uses the client credentials OAuth 2.0 flow to authenticate you. An external client app enables the client credentials flow. Use the app's consumer key and consumer secret to configure the Salesforce LWC to authenticate users with Salesforce.

  1. Navigate to the menu bar > Setup menu, then click Setup. In the Quick Find box, enter External Client App Manager.
    1. Click External Client App Manager > New External Client App > Create, then enter the following information.
    2. External Client App Name: lwc auth
    3. API Name: lwc_auth
    4. Contact Email: your_email@example.com
    5. API (Enable OAuth Settings) > Enable OAuth: Selected
    6. API (Enable OAuth Settings) > Callback URL: https://login.salesforce.com/services/oauth2/callback
    7. API (Enable OAuth Settings) > Selected OAuth Scopes: Access the identity URL service
    8. API (Enable OAuth Settings) > Enable Client Credentials Flow: Selected
    9. Click Create.
  2. Navigate to the menu bar > Setup menu, then click Setup. In the Quick Find box, enter External Client App Manager.
    1. Click your external client app's name > Edit.
    2. Navigate to OAuth Policies > OAuth Flows and External Client App Enhancements.
    3. Ensure Enable Client Credentials Flow is selected.
    4. For Run As, enter your login username.
    5. Click Save.
  3. Navigate to the menu bar > Setup menu, then click Setup. In the Quick Find box, enter External Client App Manager.
    1. Click your external client app's name > Edit.
    2. Navigate to OAuth Settings > App Settings > Consumer Key and Secret.
    3. Enter the verification code sent to your email.
    4. Copy the consumer key and consumer secret somewhere secure. You will need these for a later step.

Establish CORS and content security policies

  1. Navigate to the menu bar > Setup menu, then click Setup.
  2. In the Quick Find box, enter CORS, then click Edit.
    1. Select Enable CORS for OAuth endpoints.
    2. Click Save.
  3. Navigate to the menu bar > Setup menu, then click Setup.
  4. In the Quick Find box, enter Trusted URLs, then click New Trusted URL.
  5. Enter the API Name: ui_connector
    1. Enter the URL of the UI connector Cloud Run Service endpoint you deployed with your Agent Assist Integration Backend. You can find this URL in the Cloud Run console. For example: https://<var>UI_CONNECTOR_SUBDOMAIN</var>.<var>GCP_REGION</var>.run.app.
    2. Select all checkboxes under CSP Directives.
    3. Click Save & New.
  6. Enter the API Name: ui_connector_wss
    1. Enter the URL of the UI connector Cloud Run Service endpoint you deployed with your Agent Assist Integration Backend. You can find this URL in the Cloud Run console. Change the protocol to wss, for WebSockets traffic. For example: wss://<var>UI_CONNECTOR_SUBDOMAIN</var>.<var>GCP_REGION</var>.run.app.
    2. Select all checkboxes under CSP Directives.
    3. Click Save & New.
  7. Enter the API Name: salesforce_domain
    1. Enter the URL of your Salesforce Domain with the following format: https://<var>YOUR_SUBDOMAIN</var>.my.salesforce.com.
    2. Select all checkboxes under CSP Directives.
    3. Click Save.

Step 5: Install Twilio Flex CTI plugin

Salesforce provides Salesforce Open CTI to allow integration of third-party softphones with your Salesforce instance.

Twilio Flex CTI uses Salesforce Open CTI to allow you to use Flex directly within your Salesforce instance. Follow Twilio's instructions to set up Twilo Flex CTI in your Salesforce instance.

Step 6: Install the Salesforce Lightning Web Component

Follow these steps to use the Lightning Experience Editor to add the Salesforce Lightning Web Component into the contact page where your Twilio Flex CTI opens when a new call comes in.

  1. Navigate to the Service Console, and select Contacts.
  2. Select a contact record.
  3. Click the Setup menu > Edit Page.
  4. Click Template > Change.
    1. Select Header and Two Equal Regions.
    2. Click Next.
    3. Map each region to a new region.
    4. Click Done.
  5. From the Components sidebar, move the agentAssistContainerModule into the sidebar. Note: The npm deploy command provided this component.
  6. Click the component you placed in the previous step and fill in the form fields as follows to add configuration details.
    • endpoint: The URL of your integration backend's UI connector. For example, a URL from the Cloud Run console, like: https://<var>UI_CONNECTOR_ENDPOINT</var>.<var>GCP_REGION</var>.run.app.
    • features: Agent Assist features to include. These must be enabled in your conversation profile. Some available features include CONVERSATION_SUMMARIZATION,KNOWLEDGE_ASSIST_V2, and AGENT_COACHING. Note that some features, like SMART_REPLY, are not available for voice.
    • channel: Indicate that the integration is for voice.
    • platform: Indicate that the platform is twilio.
    • conversationProfile: Your Agent Assist conversation profile resource name. For example, projects/<var>GCP_PROJECT_ID</var>/locations/<var>GCP_REGION</var>/conversationProfiles/<var>CONVERSATION_PROFILE_ID</var>
    • consumerKey: The external client consumer key from Step 3.
    • consumerSecret: The external client app consumer secret from Step 3.

Step 7: Test the integration

You can test the voice integration with a test call to the Salesforce call center.

  1. Sign in to Twilio Flex from your Service Console.
  2. Call your Twilio Flex number. You made a note of this in Step 1.
  3. In your Service Console, accept the call. The screen should open a new or existing contact page for the number that called.
  4. If it is a new contact page, save the contact. When the contact page loads, the Salesforce Lightning Web Component should load in the sidebar.
  5. Test both sides of the conversation, ensuring that Agent Assist features are working as you've configured them.