Universal Telephony Connector – UTC

1. Feature Overview

The Universal Telephony Connector (UTC) enables you to integrate your cloud telephony service provider(s) with LeadSquared. It allows you to –

  1. Integrate multiple instances/accounts of your telephony provider –
    If you have multiple contact centers in different regions (E.g., northern region, southern region, etc.), you can configure each of them as separate tabs.
  2. Integrate multiple telephony providers –
    If you’re using two or more telephony service providers, you can now integrate all of them in one place.
  3. Assign to teams –
    Assign different instances of one telephony provider or even different providers to teams in your account. For example, you can now assign a northern region telephony instance to your northern region team, a western instance to your western team, and so on. For more information on teams, see LeadSquared Teams.

Note: The connector acts as a shell or umbrella under which you can create and configure multiple instances, using either of the following-

To learn more about LeadSquared telephony integrations, read LeadSquared Telephony – Feature Guide.

 

2. Prerequisites

  • You must be an Administrator user to access the connector configuration.
  • Developer experience is required to understand the format of the data and configure the connector with your telephony provider.
  • The following table will distinguish between the APIs owned by LeadSquared and the APIs owned by your telephony provider. The APIs owned by LeadSquared will be available to you on the UTC configuration page. While the APIs owned by your telephony provider will have to be obtained from them. If there is an issue with an API, you will need to contact the relevant API owner –
    LeadSquared APIsTelephony Provider APIs
    Call Route API (Lead/Opportunity routing) – The Call Route API routes incoming calls from existing leads to the respective Lead owner/Opportunity owner in your LeadSquared account.

    Note: LeadSquared does not automatically route the leads to the owners. LeadSqaured provides the details of the Lead/Opportunity Owner to the customer’s telephony provider, who in turn routes the call.

    Click 2 Call API – The Click2Call feature enables your sales reps/agents to place an outbound phone call just by clicking the lead’s phone number (on the Manage Leads or Lead Details pages)
    Agent Popup API – Enable real-time call notifications to users in the form of an incoming call popup on LeadSquared during an inbound call from a lead (made to your virtual number).Call Disposition – Call disposition lets users enter certain information related to a phone call once it ends.
    Call Log API – All inbound and outbound calls made through your Telephony account can be logged in LeadSquared by setting up Call Logs

 

3. Installation

Navigate to Apps>Apps Marketplace, search for the Universal Telephony Connector and click Install.

Installing the connector

 

4. Configuration

  1. Next, hover the cursor over the settingsSettings iconicon and click Configure.
  2. Click the Add New Connector button.
  3. Select the Connector Type (LeadSquared Generic Telephony Connector, Ozonetel V2, etc.).
  4. Name the connector, then click Add.

LeadSquared Telephony

Note: You can add a new instance, clone an existing one or delete an instance using the options highlighted below.

Adding a new connector

 

5. Virtual Numbers

Use this section to add one or more virtual numbers for the connector you’re configuring. You can also tag them if you like. Click the Saveicon to save a virtual number and click Add to add another number.

configure virtual numbers

 

6. Call Route API

The Call Route API automatically routes incoming calls from existing leads to the respective Lead owner/Opportunity owner in your LeadSquared account. The API must be configured as a hook on your telephony provider’s end.

  1. Copy the Lead Route V2 or Opportunity Route API URL  and deploy it in your cloud telephony account.
  2. Use HTTP GET to send the data. Please refer to the ‘Usage’ section to understand how to send the data.
Note: To add an extra layer of security you can Enable Additional Authentication and pass the generated key-value pair in the request header when calling the API. These additional authentication headers can be generated also be generated for the Agent Popup API and Call Log API.

LeadSquared Telephony Integrations

 

7. Agent Popup API

Enable real-time call notifications to users in the form of an Incoming Call Popup during an inbound call from a lead (made to your virtual number). The pop-up displays the lead’s details if the lead exists in your account, or displays an empty form that agents can use to capture the new lead.

Note:

  • Incoming calls matching a lead’s secondary phone number will be tracked without creating a duplicate lead.
  • If you have multiple leads with the same phone number, you can pass the LeadId in the Agent Popup API. This will ensure that the correct lead details appear in the agent popup. For e.g., "LeadId": "4c70ce73-0732-4977-85a2-fb49a978b85c".
  • To enable client-side logging, which allows browser events, messages, and errors to be logged to a log stream (e.g., Loggly), contact your account manager or write to support@leadsquared.com.
  • You can disable the close icon on the Agent Popup form by enabling Hide Close Option “X”. This feature ensures that agents adhere to specific workflows and processes by preventing accidental popup closures.

Agent Pop-Up API Details

  1. Copy the Agent Popup API URL from the Agent popup tab and deploy it in your cloud telephony account.
  2. Use the HTTP POST method to send the data to LeadSquared in JSON format.
  3. Enable Agent Popup by selecting the checkbox.

Refer to the ‘Usage’ section to understand how to send the data.

New agent popup

Custom Mapping
Telephony providers send us varying data using the Agent pop-up API. Enable custom mapping to map the variables received in the JSON file to the corresponding LeadSquared parameters.

Note: SourceNumber denotes the phone number of the caller, DestinationNumber denotes the phone number of the receiver, DisplayNumber represents the DID or virtual number, ivr denotes the IVR path entered by the caller.

LeadSquared Telephony

Agent Panel Settings
The agent panel enables you to embed a softphone and manage your call center actions directly from your LeadSquared account. Add a custom URL and append mail merge parameters (click the help help icon) to configure the agent panel.

Note: Agents will be presented with only the relevant Angent Panels based on the team-mapping configuration. If team-mapping has not been configured across any instance, then the mapping from the default instance will be applicable.

LeadSquared Telephony

SettingDescription
Show on TopDisplays the agent panel over any overlapping window (including the agent pop-up).
Hide Scale ButtonHides the maximize/minimize buttons on the panel.
Panel URLThe source iFrame URL for the panel. Click the help help icon to learn how to append mail merge parameters.
Panel PermissionsConfigure iFrame permissions like microphone, camera, geolocation, etc.
Panel TitleCustomize the display text on the panel title bar.
Panel HeightAdjust the default height of the panel (in pixels).
Panel WidthAdjust the default width of the panel (in pixels).

 

8. Call Log API

All inbound and outbound calls made through your Telephony account can be logged in LeadSquared by setting up Call Logs. These logs will be posted to LeadSquared as incoming/outgoing phone call activities.

You can also enable custom mapping functionality, to map and capture data about each phone call in the relevant LeadSquared activity fields. There are also custom fields available to map additional data provided by your telephony service.

Note:

  • When your Telephony provider calls the LeadSquared API, data can be pushed into LeadSquared using POST method in JSON format.
  • For this API, the Content-Type has to be set to application/x-www-form-urlencoded, and the Body should be passed in the raw JSON format.

Once you’ve finished the configurations, you can check your telephony logs by navigating to My Account>Settings>API and Webhooks>Telephony Logs.

LeadSquared Telephony Integrations

Note: Under custom mapping, on the ‘Custom’ tab (for the default connector instance), you can change the display names of the custom fields/parameters.

Here are the parameters you can post –

{

"SourceNumber":"9611232123",

"DestinationNumber":"9876543210",

"DisplayNumber":"1000001000",

"StartTime":"2015-08-20 18:26:38",

"EndTime":"2015-08-20 18:26:38",

"CallDuration":"12",

"Status":"Answered",

"CallNotes":"Enquired about product",

"ResourceURL":"server/filename.extension",

"Direction":"Inbound",

"CallSessionId":"080673309211440075398",

"CallerName":"Rakesh",

"CallerCity":"Bangalore",

"CallerState":"Karnataka",

"CallerCountry":"India",

"CallerZipCode":"560078"

}
 PropertySample ValueDescriptionMandatory
 SourceNumber+919611795983For Inbound Call-  Lead’s contact  number
For Outbound Call-  Caller’s Number or  Agent’s number
 Yes
DestinationNumber+919611795980For Inbound Call-  Caller’s Number or  Agent’s number
For outbound Call-  Lead’s contact  number
Yes
DisplayNumber+919020897874Virtual(DID) Number provided by the providerYes
StartTime2015-08-20 18:26:38Start time of the call in ISTYes
*StartTimeUTCTue, 05 Jul 2022 10:30:30 GMTStart time of the call in UTCNo
EndTime2015-08-20 18:26:50End time of the callYes
CallDuration12Duration of call in secondsYes
StatusAnsweredStatus of the call, can be Answered, Missed, VoicemailYes
CallNotesEnquired about a productAdditional notes about the callNo
ResourceURLServer/filename.extensionURL of the file with a recording of the conversationNo
DirectionInboundInbound or OutboundYes
CallSessionId080673309211440075398Call Unique IdentifierNo
CallerNameRamCaller’s NameNo
CallerCityBangaloreCaller’s CityNo
CallerStateKarnatakaCaller’s StateNo
CallerCountryIndiaCaller’s CountryNo
CallerZipCode5600102Caller’s zip codeNo

 

9. Click 2 Call API

The Click2Call feature enables your sales reps/agents to place an outbound phone call just by clicking the lead’s phone number (on the Manage Leads or Lead Details pages). If you use the Opportunities feature, click 2 call can be used to call leads from the Opportunity Management and Opportunity Details pages as well.

Depending on the capabilities of your telephony provider, it can be configured using either a server-side API or a client-side script.

Server-side API

This is the default configuration option.

Your telephony provider’s Click2Call API is configured here, and you can append mail-merge parameters (like agent phone number, lead phone number, etc.) to the API URL to facilitate the calling functionality.

  1. Pass the Click2Call API in the URL textbox.
  2. You may optionally pass custom headers to the API for authentication.
  3. Select the HTTP method needed by the telephony operators Click2Call API.
  4. Map a keyword from the response of the Click2Call API. Typically we use a keyword like “success”. This lets our system know that the API request fired correctly and a response was received.
  5. Choose the format of the API response data (Text, JSON).
  6. Click the Enable Checkbox checkbox.

LeadSquared Telephony Integrations

 

Client-side Script

For telephony providers with JavaScript SDKs, the Click2Call functionality can be configured using a client-side script. The outbound phone call functionality will be handled by the script and the call will be initiated via the browser to the telephony provider.

  1. Enter the URL of the Javascript file, which must be hosted on the LeadSquared domain (external domains are not supported). The JS file will be published only after an internal review process.
  2. You can pass data to the script using mail-merge parameters (like agent phone number, lead phone number, etc.).

LeadSquared Telephony Integration

Note:

  • For a sample JS file template, please reach out to your account manager
  • Additionally, a flag called Is Softphone Enabled must be checked for each agent, in the user settings UI. This also disables the “Agent Panel” for the agents.

LeadSquared User Settings

 

10. Call Disposition

Call disposition lets users enter certain information related to a phone call once it ends.

LeadSquared Telephony Integrations

Note:

  • To use this feature, you must first create a Custom lead field in LeadSquared (say ‘Disposition’). For more information, see How to Create Custom Lead Fields.
  • Disposition is available only on Lead Fields.
  • Only 1 <string> value can be sent to the provider as disposition.
  • User Fields can also be mail-merged in the URL and Data Template – contact support@leadsquared.com to enable this feature.

When a call has ended the agent can select an appropriate disposition value on the Call/Agent-Notification Popup, dispose of the call, and get ready to receive the next upcoming call.

  1. Deploy the URL provided by your telephony service in the URL field with the necessary parameters.
    • @callSessionId  – Call session Id passed by the telephony provider in the agent popup request
    • @customerNumber – Lead Phone number
    • @virtualNumber – The virtual number of your telephony account
    • @dispositionValue – Selected disposition value in the agent popup form*
    • @agentNumber – Agent’s phone number
    • @agentId – User Id of the agent
    • @notes – Notes on the call
    • @comments – Comments on the call
    • @date – The date of the call
  2. Select the HTTP method in which your telephony service accepts the data.
  3. You can initiate the following actions (and make them mandatory if required) once a call is disposed of –
    • Create a task
    • Create a custom activity
    • Update a lead field

*On Default Lead Field you must map the custom field you have created to capture the disposition value (refer to the Note above). This field can then be mapped with @dispositionValue in the URL (GET request), or in the Data Template (POST request).

call disposition field

 

11. Single Sign-on API

This API will help you embed LeadSquared within your telephony application. Use the API and the HTTP POST method to send data to LeadSquared in JSON format. To get the leads details, use the Lead Details API.

Please refer to the ‘Usage’ section to understand how to send the data.

LeadSquared Telephony Integration

Lead Sharing via SSO APIs
Lead Sharing allows agents to temporarily view/edit the information of a lead (during an inbound phone call) that they don’t have access to. For integrations that don’t support the Agent Pop-up functionality, SSO APIs are used for Lead Sharing. Previously, SSO APIs only supported the lead’s phone number to facilitate the identification and sharing of the lead to the agent. Now, the Lead Id is also supported. This will help customers who have leads in their accounts with the same phone number.

Note: 

  • leadId can be passed in the Lead Details API URL instead of leadphonenumber.
  • Lead sharing can also be enabled through Telephony Settings.

 

12. Team Assignment

You can assign a connector to one or more teams. While making an outbound phone call (using click2 call), the users in those teams will see the connector(s) assigned to them and can choose to place the calls from any of the virtual numbers created for a connector.

So for example, you can create 2 connector tabs, say ‘Bangalore’ and ‘Chennai’, and assign them to your Bangalore and Chennai teams respectively. Your Bangalore team will then only see the virtual numbers associated with the Bangalore connector tab.

utc assignment

Note: If you haven’t assigned any of the connector tabs to any teams, while making outbound phone calls your users will see the virtual numbers that are configured in the default connector tab (the one marked with the tick). You set a tab as default by navigating to that tab and clicking Default under the Settings Settings icon icon –

Set as default

 

13. User Agent Mapping

Here, you can map each agent/user to a unique identifier. This will be used to identify the correct agent when the ‘Agent’s Phone Number’ or ‘Source Number’ is not stored in LeadSquared.

You may enter any string/alphanumeric value for the Agent Identifier. When calling the Call Log API or Agent Popup API pass this value in the post body like "AgentId":"abcd1234" . The call log posted for the phone call will be updated with the agent/user associated with the Agent Identifier value, even if the source number is not available. Similarly, the user/agent to display the agent popup to will be identified based on the Agent Id value.

LeadSquared Telephony Integrations

 

14. Integrate with Opportunities

You can integrate the Universal Telephony Connector (UTC) connector with LeadSquared Opportunities. To know how to do this, please refer to Opportunity Integrations in Telephony.

This will enable you to track phone call interactions with your leads, for each opportunity or potential deal. Completed calls will get posted as activities, against the respective opportunities, on the Opportunity Details page.

 

Any Questions?

Did you find this article helpful? Please let us know any feedback you may have in the comments section below. We’d love to hear from you and help you out!

Was this Helpful?

Subscribe
Notify of
guest
25 Comments
Newest
Oldest Most Voted
Inline Feedbacks
View all comments
Keval trivedi
Keval trivedi
5 months ago

Is it possible to get call counts of particular lead, as agent call that lead for 5 times then it will give us the count 5??

Keval trivedi
Keval trivedi
Reply to  Vir Singh
5 months ago

Actually we are not using sierra, without it whether it is possible or not?

gayathri
10 months ago

how do i get post call hangup url

Zaid Assadi
Admin
Reply to  gayathri
10 months ago

Hi, Gayathri. Are you referring to the CallLog URL? You can find it by navigating to Universal Telephony Connector>Call Log API.

Call Log API

Aditya Bhambere
Aditya Bhambere
11 months ago

If the ozonetel vendor is sending campaign name how to capture it? Currently i have enabled custom mapping in Call log Api section. In that I have given display name as Campaign Name. What should be the mapping key here?

Zaid Assadi
Admin
Reply to  Aditya Bhambere
11 months ago

Hi, Aditya. You can find the relevant mapping key by going through the Ozonetel payload. In the following example, the mapping key is CampaignName

mkey

Nikunj
1 year ago

When I pass the ‘AgentName’ parameter with name of employee who has made the call or received the call then I am getting following error response.

{"Status":"Failure","Message":"Invalid UserId Rosesh"}

Please guide what needs to be done to fix this.

Thanks

Zaid Assadi
Admin
Reply to  Nikunj
1 year ago

Hi, Nikunj. “AgentName” is a deprecated parameter.

Agents are identified using their phone numbers by default. If you need to identify agents by name or custom values, then you will need to configure the value in the User-Agent Mapping tab. This value can then be passed in the “AgentId” parameter.

Nikunj
1 year ago

Hi,

I have a question regarding ‘Call Log API’. Is it possible to update the call based on the ‘CallSessionId’?

In my case, the first request will have the call details without note and another request for same call log will have note. So, it should update the fields based on the new request received for the given ‘CallSessionId’.

Right now the response is as below
{“Status”:”Success”,”Message”:”Phone Call Logged Successfully”,”ProspectActivityId”:”xxxxx-xxxx-xxxxx-a15e-06xxx7fe6″,”Details”:”Call Log was already processed”}

Please guide how I can achieve this

Thanks

Last edited 1 year ago by Nikunj
Zaid Assadi
Admin
Reply to  Nikunj
1 year ago

Hi, Nikunj. There’s a V2 API, but it only allows for updating call recording, call duration, and the owner. An activity id will need to be passed mandatorily.

Let us know if this helps.

Nikunj
Reply to  Zaid Assadi
1 year ago

Thanks Zaid for the update.

Actually we would like to update note and call recording for the activity created by UTC.

Also it’s preferable that Call Log API will handle this rathen than making a new API call.

Please guide.

Zaid Assadi
Admin
Reply to  Nikunj
1 year ago

As of now, if a new call log request comes with the same call session id, it will be ignored as a duplicate.

So, the call note will have to be sent in the first call log request, and the call recording can be updated with the V2 API.

I hope this helps.

Nikunj
Reply to  Zaid Assadi
1 year ago

Noted. So is it possible to make changes in UTC and instead of ignoring the duplicate call log, it simply updates the record. This can be configurable as well, so the user can decide whether to update or ignore.

Zaid Assadi
Admin
Reply to  Nikunj
1 year ago

Currently, it isn’t possible to make those changes.

I’ve passed our conversation to the product team, and they’ll include this feature request in their product backlog. We’ll let you know when the changes are live. Thank you.

Nikunj
Reply to  Zaid Assadi
1 year ago

Sure. Please let me know, it would be really helpful.
Thanks

velmurugan
velmurugan
1 year ago

Hi Team,

How to get user agent mapping id while calling click2call API

Last edited 1 year ago by velmurugan
Zaid Assadi
Admin
Reply to  velmurugan
1 year ago

Hi. The User-Agent Mapping Id is not a mail merge parameter that can be used while calling the Click2Call API. 

A list of available parameters can be viewed on the Click2Call configuration tab.  

telephony answer.png
Vrindha
Vrindha
1 year ago

Hello Team, Do we have any parameter for country code? For example, the below c2c URL is for both national and international outbound calls. What parameter should we mention in countrycode?
http://mcube.vmc.in/api/outboundcall?apikey=”&exenumber=”&countrycode=”&custnumber=”&mct=”&wct=”&refid=”&url=”&did=”

Sri Sudhan
Admin
Reply to  Vrindha
1 year ago

Hi Vrindha, we don’t have a parameter for country code. Instead, we have mail merge parameters you can use for phoneNumberWithCC and phoneNumberWithoutCC.

Mudit Garg
Mudit Garg
1 year ago

I was trying POST call log API, verified request body is in correct format and content type set tp application/x-www-form-urlencoded, but i get this everytime :
{“Status”:”Failure”,”Message”:”Unexpected character encountered while parsing value: S. Path \u0027\u0027, line 0, position 0.”}

Sri Sudhan
Admin
Reply to  Mudit Garg
1 year ago

Hi, Mudit. You’re getting an “Unexpected character encountered…” error because the data you’re passing in the request is invalid. Please check the payload and try passing the API again. If the issue still persists, do let us know. Hope this helps!

Mudit Garg
Mudit Garg
Reply to  Sri Sudhan
1 year ago

Found the solution with help of support team.
In case anyone like me stumbles on same issue, I was trying this API from POSTMAN, where you can set body type to x-www-form-urlencoded and POSTMAN will create content-type header for you.

What this document lacks in such case is to clearly explain that Content-Type has to be manually set to application/x-www-form-urlencoded and body payload should go as raw JSON format (the solution)

Sri Sudhan
Admin
Reply to  Mudit Garg
1 year ago

Thank you for pointing this out, Mudit. The article has been updated accordingly.