Salesforce Integration

Owned by Valerio Ciotta
Last updated: Jun 07, 2022 by XCALLY Knowledge (Unlicensed)
21 min read

How it works


   Salesforce integration is used to automatically open a task for every call according the conditions (Queue, Call status or Outbound) set in the trigger: the Salesforce Task or Case that will be created automatically, will be populated with information about the call and displayed to the agent in the Salesforce environment.


The following is a list of operations to do to make the integration work:

  1. Download and use the XCALLY Motion Phonebar Windows App and the XCALLY Motion Dialpad Chrome Extension. This step is mandatory only if you choose to define the Salesforce Account as an Integration Tab type (OpenCTI Integration). On the contrary, if you choose to define the Salesforce Account as a New Tab type, you can use an external phone (of course, in this case you must login in the XCALLY Motion Omnidesktop interface) or WebRTC. Learn more about this topic here
  2. Create a Connected App in Salesforce
  3. Create Salesforce Account in XCALLY Motion 
  4. Create Salesforce Configuration for the account created in XCALLY Motion
  5. Create a Trigger (Tools → Triggers) for both inbound and outbound, set the conditions you want to trigger for this integration and add integrations action, by selecting theSalesforce integration, Salesforce Account and the Configuration you want to use. As an alternative for only outbound you can configure a Click-to-Call integration 
  6. Configure Salesforce for OpenCTI Integration (Optional: this step is mandatory only if you want to use the Integration Tab type otherwise you don't need to do it
  7. Test the Integration
  8. Login Agent in Salesforce and/or Motion and start!
On this page:



Any interaction occurred through this integration can be searched by the Agent from the list by:

  • contact's phone number
  • lead's phone number
  • user's email



After the configuration steps listed above, every time there is an outgoing/incoming call the trigger conditions are checked and a Salesforce task is created and assigned to the agent managing the call (if the conditions are met).


When an agent manages a call, his/her account email address will be searched in Salesforce: if the system finds the salesforce task will be assigned, otherwise the task will be assigned to the Salesforce Administrator Account specified in Motion-Salesforce integration.

If all the configuration is properly set, the Salesforce Task will be opened as shown below:

The Task Subject, Description and Fields can be managed and customized in the Create a Salesforce Configuration section.






Requirements - What to know before starting 


In order to have the integration working correctly, please be sure to:

  • install and use the XCALLY Motion Phonebar

    The integration will not work if your Agents are not correctly logged in the XCALLY Motion Phonebar (for example if they are using external phones)!

  • Install a valid HTTPS certificate


 In order to create and assign Salesforce Tasks to Agents properly, make sure:

  • Agent's Email in Salesforce profile is exactly the same as Agent's Email in Motion
  • Agents can access to all properties inside the Task object
  • As for the Integration Type: 

    • For New Tab the Agent must be logged in XCALLY Motion Phonebar, XCALLY OmniDesktop Interface and Salesforce Web Interface. In this case the Agent must ENABLE the browser pop-ups, when he/she receives the first call.


    • For the Integration Tab the Agent must be logged in XCALLY Motion Phonebar and Salesforce Web Interface only. The Agents can manage calls through the XCALLY Motion Phonebar or through the embedded phone on the Salesforce console. The login on the Motion Agent Web interface is optional. Remember to enable Remote control for the agents.


For Integration Tab

This type of integration works only through https connection to XCALLY Motion Server









The Salesforce Accounts Section


The Salesforce Accounts Section is under the Integrations Menu:


The following are the configuration steps described above:


1-Create Connected App in Salesforce


First of all, create a new Connected App in Salesforce to make Salesforce-Motion integration work. If you are in Lightening Experience, make sure to switch to Salesforce Classic and then follow the steps below in order to create the XCALLY Motion Connected App. 

  • Login to Salesforce with an administrator account and go under the Admin Setup section. In the menu, on the left, click on Build -> Create -> Apps 


and then on the New button in the Connected Apps section:


  • Insert the following data into the New Connected App:

  • Connected App Name: xCally Motion
  • API Name: xCally Motion
  • Contact Email: your company mail address
  • Enable OAuth Settings: Enabled
  • Insert the Callback URL: https://login.salesforce.com/services/oauth2/callback
  • Select and add the following OAuth Scopes:
    • Access and manage your Chatter feed (chatter_api)
    • Access and manage your data (api)
    • Access custom permissions (custom_permissions)
    • Access your basic information (id, profile, email, address, phone)
    • Allow access to your unique identifier (openid)
    • Full access (full)
    • Perform requests on your behalf at any time (refresh_token, offline_access)
    • Provide access to custom applications (visualforce)
    • Provide access to your data via the Web (web)


Here you can find all the information about the Connected App creation:
https://help.salesforce.com/apex/HTViewHelpDoc?id=connected_app_create.htm




2-Create a Salesforce Account


To create a new Salesforce Account go in the Integrations Section → Salesforce Accounts and click on 



Enter the following details and click on Add Salesforce Account:

  • Type: chose between Integration Tab or New Tab
    • Integration Tab (OpenCTI Integration): the task will be displayed in a new tab inside Salesforce interface. Remember to properly configure Salesforce to make the integration work.
    • New Tab: The task will be displayed in a new browser tab. Remember: this works only if the agent is logged in Motion interface.
  • Username: this value must be the same as the Salesforce Administrator Account name
  • Password: same as a Salesforce Administrator Account
  • URI: your Salesforce URL e.g. https://login.salesforce.com/
  • Client ID: you can find it in the Salesforce App Settings 
  • Client Secret: you can find it in the Salesforce App Settings 
  • Security Token: you can find it in the Salesforce Personal Settings 
  • Motion or Proxy IP Address: written as <protocol>://<ipaddress>[:<port>] form. It is required to use the Recording URL in the Task Configuration.  Example: https://X.Y.Z.W  
  • Description (optional)     




After the Account is created, you can view it in the list of accounts, edit the account parameters and remove the account. 

You can verify if the account credentials are correct by clicking on Test Salesforce Account.



How to Find the Client ID and Secret

On Salesforce go under Create ---> Apps ---> Connected Apps and click on your App name: here you'll find the Consumer Key (Client ID) and the Consumer Secret (Client Secret)



How to Find the Token

On Salesforce go under My settings --> Personal --> Reset My Security Token:

You will receive the token via email.

Please note that any time you change the Salesforce user password, the Token becomes invalid and must be reset: remember to insert the new one on the XCally Motion Salesforce Account to make integration work!





3-Create a Salesforce Configuration


Find the account from the accounts list and Click on Edit Salesforce Account:




You will see two tabs: Account and Configurations:

In the Account tab, you can modify the account parameters and in the Configurations tab, you can create, update or delete Salesforce configurations. 


A Salesforce configuration is used to design the content of the Salesforce task (Subject, Description and Fields) that is created and displayed for the agent managing calls.

You can create multiple configurations for a single Salesforce Account and use them in different triggers. In this way, for example, you will be able to use different task layout for outbound and inbound calls.


To create a new configuration, Edit the Salesforce account, go under configurations tab and click on 




Choose a Name, Channel (e.g. Voice).

Choose a Type:

  • Inbound in Queue 
  • Outbound Call 



Choose a Ticket Type:

  • Task
  • Case

        

Then, click on Add Salesforce Configuration.

This value is used during the startup of the configuration and is used by the system to generate the template: the configuration will be created with default Subject and Description settings that you can simply use without any modification.

You can also edit the configuration and customize the Subject, Description and Fields of the Salesforce Task according to your needs.


The default Subject and Description settings depends on the type of configuration.

For example, the default subject configuration for Queue Type is [xCALLY Ticket] Queue calleridnum while for Outbound Type it's [xCALLY Ticket] Outbound Call destcalleridnum.

Configuration changes are automatically applied, without any service restart.

Remember you can use Motion Standard Variables or Custom Variables in the configuration.




Subjects


By default, you will find the following three fields already configured

  • the String [XCALLY Ticket]
  • the Queue Variable
  • the Caller number Variable

You can add more than one field in the Subject and all fields will be joined by the blank space.

Use button to add a new fields. New fields are added at the end of the field list.

You can insert 3 different type of fields:

  1. String: static string e.g. a label as [xCALLY Ticket]
  2. Variable: Motion System Variable, e.g. queue or calleridnum (see Motion Variable List)
  3. Custom Variable: any dynamic variable created under Tools > Variables



Descriptions




You can add more than one field in the Description. All fields will be joined by new line.

Use button to add a new Description (it will be added at the bottom of the list).

You can insert two different type of fields:

  1. String: static string e.g. *** Call Info ***
  2. Key Value: name-value item in the form name: value

where the first field is a static string (e.g. Caller Number) and the second field could be filled with the following:

  • String: static string
  • Variable: System Variable like Caller Number (see Motion Variable List)
  • Custom Variable: dynamic variable created under  Tools > Variables

The colon character in the Key Value type is automatically added by the system


Fields


In the drop-down list you can find the complete list of fields available in your Salesforce account: Standard and Custom fields.

Use button to add a new field, choose the Standard or Custom field by scrolling the list of the values:



and define the Type:

  • String: static string (you must insert it)
  • Variable: a System Variable (choose it from the list: e.g. Queue, uniqueid, calleridnum, etc.)
  • Custom Variable: one of the dynamic variables (created under Tools > Variables)
  • Picklist: choose among the list of the integrated Application Fields. You can only select one of the predefined values available for that field (if any).


Repeat the steps above to add more fields.


The only custom fields that can be configured are those of the following type: string, int, picklist, boolean, email, textarea and phone (other field types are not proposed in the configuration)



Advanced


In this section you can set:

  • how to Search the Module as: Account, Lead, Contact, Contact&Lead, Contact&Lead&Account

  • how and if (nothing=no creation) to Create the Module as: Contact, Lead or Account


  • Lead Id, where to insert the Lead name (this field will be shown only if the Module Search field is or contains Lead):


Insert here the Lead Field Name you find on Salesforce:


  • an additional field where to search the customer phone number in the:
    • Account, if the Module Search value chosen is (or contains) Account
    • Contact, if the Module Search value chosen is (or contains) Contact 
    • Lead, if the Module Search value chosen is (or contains) Lead


This is a field, in addition to Phone, to search for customers in Lead, Contact and Account: you can insert here the mobile or fax number field name you have on Salesforce


4a-Configure Salesforce for OpenCTI Integration Type (Lightning Version)


 You need to perform the following steps to make the OpenCTI integration work: 

  • Create a call center adapter
  • Create lightning experience app
  • Install chrome extension
  • Login agents


Remember: use this integration type if you don't want to perform a double login (Salesforce and Motion Omnidesktop Interface). The task will be displayed in a new tab inside Salesforce interface


Create a call center adapter 

  • Login to Salesforce with an administrator account and switch to lightning experience


  • Click on Setup


  • Create a Call Centers: Go to Feature Settings -> Service -> Call center and click Continue


  • Click on Import and upload call_center.xml (Remember to insert the real IP address of your XCALLY Motion Server)


You will see the imported Call Center, called MotionAdapter. 


  • Edit Motion Parameters: set your XCALLY Motion https IP address (Host field) and click on Save


The Display Name property value must start with word Motion


  • Call Center Users: Enable Users to use the integration by clicking on the Manage Call Center Users button and then Find and  Add new Users to the Call Center:


Create lightning experience app

  • Go under Apps -> App Manager and click on New lightning App


  • Fill the required setting as shown below and click Next


  • Select Console navigation and click Next


  • Click on Add and select openCTI softphone. 


  • Customize the layout of the softphone as you desire and then click Next


  • Add items to use in the app: Select Leads, Contacts and Tasks


  • Select user profiles to give them permission to use and see the app. Choose the profiles your agents belongs to and click Finish


  • Click on App launcher button at the top left of the screen and you will see the new Motion app in the app launcher as shown below

  • Click on the Motion app, to see the ligthning app with the softphone embedded inside. 

Install the Motion Dialpad Chrome extension 

You need to install xCALLY Motion Dialpad Chrome extension to use Phone functionality in Salesforce Console App.

The Chrome Extension is available here in the Chrome Web Store.




4b-Configure Salesforce for OpenCTI Integration Type (Classic Version)


Use this integration type if you don't want to use a double login (Salesforce and Motion) and the the Integration Tab mode.

You need to perform the following steps to make the OpenCTI integration work:  

  • Create a call center adapter
  • Create Console App
  • Install chrome extension
  • Login agents


Remember: use this integration type if you don't want to perform a double login (Salesforce and Motion OmniDesktop). The task will be displayed in a new tab inside Salesforce interface.


Create a call center adapter 

  • Login to Salesforce with an administrator account

  • Click on Setup
  • Create a Call Centers: Go to Build -> Customize -> Call Center → Call Centers and click Continue


  • Click on Import and upload call_center.xml (Remember to change the IP address of your Xcally Motion Server)


You will see the imported Call Center, called MotionAdapter. 

  • Edit motion parameters: set your Motion Https IP address and click on Save.

The Display Name property value must start with word Motion


  • Call Center Users: Enable Users to use the integration by clicking on the Manage Call Center Users button and then Find and  Add new Users to the Call Center:


Create Console app

  • Go under Build → Create → Apps and click on New


  • Select Console as App Type and click Next


  • Fill the required setting as shown below and click Next


  • Click on Next. 


  • Select Navigation Tab Items that you want to display and then click Next


  • Click Next


  • Select user profiles to give them permission to use and see the app. Choose the profiles your agents belongs to and click Finish


  • Click on Force.com App Menu button at the top right of the screen and you will see the new xCALLY Motion app in the list as shown below


  • Click on the xCALLY Motion, to see the console app with the softphone embedded inside the app. 


Install the Motion Dialpad Chrome extension 

You need to install xCALLY Motion Dialpad Chrome extension to use Phone functionality in Salesforce Console App.

The Chrome Extension is available here in the Chrome Web Store.





Integration using Trigger


It is mandatory to create a Trigger to make the Salesforce integration work.

Go to Tools -> Triggers Section and click on New Trigger.




Enter the trigger Name, select Voice Channel and click on Add Trigger. 

Edit the trigger to define the trigger's Conditions and Actions.


Do not forget to set the trigger's status ON.

Add Trigger Conditions


You can use properties like Queue, Call status or outbound to define the conditions you want to trigger the Salesforce integration.

E.g.: in the following example the conditions set mean that the integration will be active for Calls in Sales Queue and when the call is answered. 

For more information on trigger conditions, take a look at Voice Trigger Conditions.



Add Trigger Action

To execute the Salesforce integration when the conditions are met, click on Add Action and select Integrations and Salesforce.

You can then select one of the the Salesforce account you have created and the configuration you want to use.





Integration using Click-to-Call


The main goal of the LogCall integration is to perform the creation of a task each time a dial event is triggered, using the ClickToCall tool.

For instance, from a customer tab you can just click on the telephone number and start a conversation with the contact: in this case, a new Task object will be created and opened in a dedicated tab, containing all updated information regarding the phone call.



Configuration Steps for Lightning Version


We have already created a Call Center Adapter in the previous section: now we can edit its parameters.


Change the Manage Task parameters in order to:

  • Create a task during the phone call (true or false): create a Task object during a click to call action
  • Create the task on the customer answer (true or false): create the task, but only in case the customer has answered to the phone call
  • Update the task fields on hangup (true or false): update the information registered inside the Task object after the hangup event (end of phonecall)
  • Refresh the task page on hangup (true or false): immediately refresh the task tab after the hangup event
  • Default status of created task (Not Started, In Progress ecc…): set the default status of Task object after the object is created
  • Default status of updated task (In Progress, Completed…): set the default status of the Task object after the object is updated


In the Field Mapping section, you'll find eleven fields available, each related to an Asterisk* environment variable, that you can use to fill your own custom fields created for the Activity / Task object (these fields are absolutely not mandatory for the ClickToCall LogCall function to work properly):

In order to visualize the Asterisk* variable content inside a custom field:

  • create a custom field of type String (255) 

  • copy the Field Name (ID_Name on Salesforce Classic Version) inside the input field of the related Asterisk* variable
  • save

Now the Activity Task Tab created by LogCall will show the Asterisk* variable content inside your own custom field.


Remember to add users to the call center that can have access to the softphone and perform ClickToCall actions


Return on the main page and click on the colored dots-button on the far left to access to all the registered app.

Click on your dedicated Motion Lightning console app:



Now you can see that you are logged in as Agent on the XCALLY Motion Phonebar.

Click on the PHONE button on the bottom left on the main page, and open the softphone. You will see you are online as an Agent:


If a phone call is already active on the phonebar, you will see the same information on the softphone, and you will have to wait for the phone call to end before performing a new dial event (from the phonebar or the softphone, as well as by clicking a phone number inside the Contact object tab):


If no phonecall is active, it means you are ready to do a new one. To do it as a ClickToCall event, go to Contact / Lead / Account object tab, search a phone number, and click it:


and the XCALLY Motion Phonebar will perform a phone call usng the clicked phone number as target:


You can see the same information regarding the phonecall on the upper part of the sofphone, but in the same time a new event has been triggered and a new Task object regarding an Outbound call to the customer phone has been created and opened in a dedicated tab:


According the configuration fields you managed in the Call Center section, three events can be fired on ClickToCall:

  • no Task object is created (Create a task during the phonecall = false)
  • a new Task object is created when you clicked on the contact phone number (Create a task during the phonecall = true & Create the task on customer answer = false)
  • a new Task object is created when the customer answered the phonecall (Create a task during the phonecall = true & Create the task on customer answer = true).

In case a new Task object has been created, you’ll see all the updated information regarding the phonecall (by default, the field Description is the one that receives information from the remote server):


When hanging up (performed by you or by the contact), three possible events can be triggered:

  • no events at all and the Task object will not be updated with new information regarding the phonecall (Update the task fields on hangup = false)
  • the Task object will be updated with the new information. You can see the updated information once you will enter again the tab or refresh it (Update the task fields on hangup = true & Refresh the task page on hangup = false)
  • the Task object will be updated and the Task object tab will be refreshed, so that the updated information will be immediately visible (Update the task fields on hangup = true & Refresh the task page on hangup = true).


In case the Task object has been updated, you will read the new updated information regarding the phonecall (like hold time, end time, duration, and billable seconds):

 

The softphone is now ready to perform a new phonecall, and the ClickToCall integration is again ready to dial a call by clicking on a phone number visible in the Contact / Lead / Account tab.


Configuration Steps for Classic Version


We have already created a Call Center Adapter in the previous section: now we can edit its parameters.

Change the Manage Task parameters in order to:

  • Create a task during the phone call (true or false): create a Task object during a click to call action
  • Create the task on the customer answer (true or false): create the task, but only in case the customer has answered to the phone call
  • Update the task fields on hangup (true or false): update the information registered inside the Task object after the hangup event (end of phonecall)
  • Refresh the task page on hangup (true or false): immediately refresh the task tab after the hangup event
  • Default status of created task (Not Started, In Progress ecc…): set the default status of Task object after the object is created
  • Default status of updated task (In Progress, Completed…): set the default status of the Task object after the object is updated


In the Field Mapping section, you'll find eleven fields available, each related to an Asterisk* environment variable, that you can use to fill your own custom fields created for the Activity / Task object (these fields are absolutely not mandatory for the ClickToCall LogCall function to work properly):

In order to visualize the Asterisk* variable content inside a custom field:

  • create a custom field of type String (255) 
  • copy the Field Name (ID_Name on Salesforce Classic Version) inside the input field of the related Asterisk* variable
  • save

Now the Activity Task Tab created by LogCall will show the Asterisk* variable content inside your own custom field.


Remember to add users to the call center that can have access to the softphone and perform ClickToCall actions


On the Motion Call Center Dialpad form, in the Salesforce Compatibility mode enter the value Classic_and_Lightning to make the XCALLY Motion Softphone compatible both on Classic and on Lightning version:



If all Call Center configuration parameters have been correctly managed, you'll will find the SoftPhone loaded and ready in the dedicated Motion Classic console app section:


  • Open a Contact / Lead / Account tab
  • Click the PHONE button you find on the bottom right of main page, and open the softphone and on the top of main page, you will see the XCALLY Motion Phonebar ready to perform phone calls.
  • Find a phone number, and click it to trigger a ClickToCall action.


According the configuration parameters you have chosen in Call Center Section, the ClickToCall  action can trigger the creation of a Task object, on dial or on customer answer, with information about the phonecall (LogCall integration):


In the same way, the hangup event can trigger an update of the informations visible on the Task object tab. The tab can automatically be refreshed on the hangup event:



Using Salesforce & Phonebar

Login agents in Salesforce interface and in Motion Phonebar (motion server must be the same as the host configured in the call center adapter settings)

and experience the integration, as in the following two examples:


Test the Integration - Classic Version

  • the Agent (John Doe), that is configured on the XCally Motion Queue Support and on Salesforce, receives a call from a Customer, Jane Miller


and  this will cause the opening of a task, according the conditions (e.g. queue) set in the trigger:


  • the Agent (John Doe) calls a Customer number and this will cause the opening of a task, according the conditions (e.g. Outbound route) set in the trigger:




Test the Integration - Lightning Version

  • the Agent (John Doe), that is configured on the XCally Motion Queue Support and on Salesforce, receives a call from a Customer, Jane Miller


and  this will cause the opening of a task, according the conditions (e.g. queue) set in the trigger:


  • the Agent (John Doe) calls a Customer number and this will cause the opening of a task, according the conditions (e.g. Outbound route) set in the trigger:


Remember to enable Remote control for Agents 





TIP

If the agent is logged with the Motion Phonebar and logged on Salesforce and the Salesforce Task is not opened:

  • Check that the agent can reach your Motion GUI via https

    If you don't have installed a valid certificate, the agent must open the https://your-motion-ip/ address and accept the insecure connection

    Please note that we recommend you to install a valid SSL certiticate on Motion.

  • Check that you have properly configured the integration on the Motion GUI and the Trigger