Ringotel offers a comprehensive set of APIs to manage your Ringotel account (Admin API) and facilitate messaging between Ringotel users (Messaging API). You can access the API documentation through the following link: https://ringotel.atlassian.net/wiki/spaces/RSW/pages/2091548680/Ringotel+API+Settings?atlOrigin=eyJpIjoiMzNjNzFhNjEzNzJkNDIyY2E0YjNiMWFlMTNkYjcxMWEiLCJwIjoiYyJ9
Additionally, we provide a no-code framework for integrating with CRM (and other third-party) systems. In essence, the CRM system needs to have HTTP API endpoints to receive requests from the Ringotel server. Ringotel will send requests at various stages of the workflow, such as during integration setup in the portal, contact creation, incoming/outgoing calls, etc. The endpoints and their format depend on the desired functionality and data you wish to receive in this integration.
Prerequisites
The integration has the following prerequisites:
The CRM must be capable of both receiving and responding to HTTPS requests containing JSON content.
The CRM must have the capability to authorize requests from a Ringotel server using Basic, Bearer, or OAuth2 methods.
The CRM needs to handle data in a predefined format for both incoming and outgoing transactions.
When interacting with Ringotel, the CRM is expected to respond with standard HTTP codes such as 200 OK or 403 Forbidden for authentication requests.
Implementation
The No-code Framework for Integrating with CRM systems is essentially a JSON file that outlines the integration implementation process. It includes details like authentication methods, HTTP requests and responses as per the CRM system API documentation, variables and parameters utilized in these requests/responses, and other relevant information. At the end of this document, you will discover a template that can be customized and shared with your team for review.
The JSON file adheres to the following structure and aligns with the workflow detailed below.
Description
These variables describe the integration internally and how it will be shown in the Ringotel admin portal.
“id”: string
ID of the integration. Used internally and should be unique.
"name": string
Name of the integration that is displayed in the Admin Portal.
"logo": string
Non-encoded URL to the integration logo that is displayed in the Admin Portal.
"class": string
Integration type. Should be set to crm.
Properties
Defined properties will be displayed as fields in the integration form within the Ringotel Admin Portal configuration. These fields will retain the values provided, which can then be utilized across the JSON file.
Example:
Integration requires client ID, client secret and instance URL for authentication
These fields are added as properties in the JSON file:
"properties":[ "Instance URL", "Client ID", "Client Secret" ]
This causes these fields to appear in the Ringotel admin portal when configuring the integration:
The provided values are then used in the “Authentication“ section of the JSON document.
Parameters
Parameters store values that can be used throughout the JSON file in the methods request, response, URLs, Variables, and Authentication.
Declaration example:
| Code Block | ||
|---|---|---|
| ||
"parameters": {
"user_id": "number",
"user_name": "string",
"contact_id": "number"
} |
| Info |
|---|
You do not need to declare and/or use all listed parameter in your JSON document, only the parameters needed can be declared and used. |
| Info |
|---|
Each parameter must have the appropriate data type according to the CRM API, i.e. |
Parameter list:
| Expand | ||
|---|---|---|
| ||
"phone": Phone number of a CRM user or contact. “email”: Email address of a CRM user or contact. "user_id": CRM user ID. "contact_id": CRM contact(customer, client) ID. "activity_id": CRM Activity record(call) ID. "activity_type": Activity type description, stores the direction of a call. It has two possible values "user_name": Full name of a CRM user. "contact_name": Full name of a CRM contact(customer, client). "firstname": First name of a CRM user or contact. "lastname": Last name of a CRM user of contact. "subject": Call activity subject. "description": Call activity comment. "company_name": CRM organization(company, lead, firm) name. "company_id": CRM organization(lead, firm) id. "content_url": Unencoded URL of a call recording. "user_number": Ringotel user extension number. "party_number": Calling or called party number (depending on the "calling_number": Calling party number. "called_number": Called party number. "call_duration": Call duration (in seconds). "call_timestamp": Call start timestamp in EPOCH format (milliseconds from Jan 1, 1970). Alternatively, the data type could be set to "call_timestop": Call end timestamp in EPOCH format (milliseconds from Jan 1, 1970). Alternatively, the data type could be set to "call_cause": SIP hangup cause code. "call_url": Unencoded URL to access the call recording. "domain": Ringotel organization domain. "filename": Uploaded file name. "file": Base64-encoded body of an uploaded file. "since": Date of the last contact record modification. “prefix“: Stores the value of the “Search“ field in the Ringotel app, used for the SearchContact method. “connection_id“: Connection (branch) ID. “connection_name“: Connection (branch) name. |
Syntax
The syntax for using Variables, Parameters and Properties can use either $variable$ or {variable} forms.
If you wish to use the {variable} syntax, you will need to specify "var_char": "{}" in the JSON file, before using this notation.
Example:
| Code Block | ||
|---|---|---|
| ||
{
"id": "ExampleCRM",
"name": "Example CRM",
"logo": "https://assets.ringotel.net/img/services/example.png",
"class":"crm",
"var_char": "{}",
"parameters": {
...
}
...
} |
Use case 1:
API call to the CRM API returns a list of users, called “records“ and we are storing the values of user ID and Name fields in the "user_id" and "user_name" parameters respectively.
| Code Block | ||
|---|---|---|
| ||
"response_map": {
"records": [
{
"Id": "$user_id$",
"Name": "$user_name$"
}
]
} |
Use case 2:
We are deleting a contact using the DeleteContact method, which uses contact_id to find the contact by its ID.
Method example:
| Code Block | ||
|---|---|---|
| ||
"DeleteContact": {
"request_method": "DELETE",
"request_path": "/crm/v3/objects/contacts/{contact_id}"
} |
Variables
Variables store values that can be used throughout the JSON file in the methods request, URLs, and Authentication.
In a variable definition, it is possible to use Parameters to calculate variable’s value.
Declaration example:
| Code Block | ||
|---|---|---|
| ||
"variables": [
{
"parameter": "activity_type",
"values": {
"inbound": "INBOUND",
"outbound": "OUTBOUND"
},
"name": "call_direction"
}
] |
Use case 1:
Creating a Variable call_duration_millis which stores the duration of the call in milliseconds using the value from the Parameter "call_duration".
| Code Block | ||
|---|---|---|
| ||
{
"name": "call_duration_millis",
"parameter": "call_duration",
"values": {
"default": "$call_duration$*1000"
}
} |
Use case 2:
Creating a Variable call_title which sores the title of a call which is based on the value currently stored in the Parameter activity_type.
| Code Block | ||
|---|---|---|
| ||
{
"name": "call_title",
"parameter": "activity_type",
"values": {
"inbound": "Incoming call from $party_number$",
"outbound": "Outgoing call to $party_number$"
}
} |
URLs
"resource_url": string
Unencoded API base URL. If specified, added in front of the request_path property value in the API methods.
Example: https://api.example.com
"contact_url": string
Unencoded URL to a contact profile. If specified, will be used to open a contact profile in CRM via the Ringotel app.
Example: https://api.example.com/contacts/$contact_id$
"activity_url": string
Unencoded URL to an activity(call) page. If specified, will be used to open an activity page in CRM via the Ringotel app.
Example: https://api.example.com/activity/$activity_id$
Authentication
Authentications can be based on the OAuth 2.0 Web Server Flow using the client_id and client_secret. Alternatively, Basic or Bearer authentication can be used.
OAuth2 Authentication example:
| Code Block | ||
|---|---|---|
| ||
"OAuth2": {
"client_id": "$Client ID$",
"client_secret": "$Client Secret$",
"flow_type": {
"default": "0"
},
"authorization_endpoint": "https://login.example.com/services/oauth2/authorize",
"authorization_parameters": {
"default": "scope=api%20refresh_token"
},
"token_endpoint": "https://login.example.com/services/oauth2/token",
"token_parameters": {
"content_type": "application/x-www-form-urlencoded;charset=utf-8"
},
"request_auth": "Bearer"
} |
Bearer Authentication example:
| Code Block | ||
|---|---|---|
| ||
"auth": {
"type": "Bearer",
"token": "$API key$"
}, |
Basic Authentication example:
| Code Block | ||
|---|---|---|
| ||
"auth": {
"type": "Basic",
"username": "$Username$",
"password": "$Password$"
}, |
API
The API object defines the requests (“hooks“) that are triggered at different stages of the workflow. It contains the set of methods that defines the functionality of the integration. Each method can have the following properties:
“request_method”: string
HTTP request method. Must be one of the follwoing: GET, POST, DELETE, PUT, PATCH.
“request_path”: string
The request path to the API endpoint. Full request URL is constructed from resource_url and request_path.
| Info |
|---|
Alternatively, you can specify an absolute path for the API endpoint by replacing |
"request_content_type": string
Defines requests Content-type, e.g. "multipart/form-data".
“request_parameters”: object|array
Describes the request parameters and its values sent to the API endpoint. Added in the URL query for GET requests or as the request body for other requests.
Example:
| Code Block | ||
|---|---|---|
| ||
"CreateContact": {
"request_method": "POST",
"request_path": "/contacts",
"request_parameters":
{
"firstname": "$firstname$",
"surname": "$lastname$",
"email": "$email$",
"phone": "$phone$",
"title": "$job_title$"
},
"response_map":
{
"id": "$contact_id$"
}
}, |
“response_map”: object|array
Describes the JSON body returned in the API endpoint response. Map the response parameters to the Ringotel variables to utilise in the integration.
Example:
The Contacts method initiates an HTTP request to the API endpoint, fetching a collection of CRM contacts stored in the result array. Additionally, the request restricts the output to a maximum of 100 records by providing the ?limit=100 query parameter.
| Code Block | ||
|---|---|---|
| ||
"Contacts": {
"request_method": "GET",
"request_path": "/contacts?limit=100",
"response_map":
{
"result":
[
{
"id": "$contact_id$",
"firstname": "$firstname$",
"surname": "$lastname$",
"email": "$email$",
"phone": "$phone$",
"mobile": "$mobile$",
"title": "$job_title$"
}
]
}
}, |
| Info | |||||
|---|---|---|---|---|---|
It is possible to have more than one API call in the method if needed, the structure will turn into the call collection with each element having the same structure. The API calls will be executed in sequence they are defined in the document. Example:
|
API methods description and examples
Users
Provides the list of CRM users to map with the Ringotel users. Each user needs to have unique identifier (ID).
Example:
| Code Block | ||
|---|---|---|
| ||
"Users": {
"request_method": "GET",
"request_path": "/query?q=SELECT Id,FirstName,LastName,Email,Phone FROM User",
"response_map":
{
"records": [
{
"Id": "$user_id$",
"FirstName": "$firstname$",
"LastName": "$lastname$",
"Email": "$email$",
"Phone": "$phone$"
}
]
}
} |
Contacts
Returns the list of contacts and their properties.
Example:
| Code Block | ||
|---|---|---|
| ||
"Contacts": {
"request_method": "GET",
"request_path": "/query?q=SELECT Id,FirstName,LastName,Email,Phone,Account.Name,MobilePhone,Title FROM Contact",
"response_map":
{
"records":
[
{
"Id": "$contact_id$",
"FirstName": "$firstname$",
"LastName": "$lastname$",
"Email": "$email$",
"Phone": "$phone$",
"MobilePhone": "$mobile$",
"Account":{
"Name":"$company_name$"
},
"Title": "$job_title$"
}
]
}
} |
Organizations
Returns the list of accounts and their properties.
Example:
| Code Block | ||
|---|---|---|
| ||
"Organizations": {
"request_method": "GET",
"request_path": "/query?q=SELECT Id, Name FROM Account",
"response_map":
{
"records":
[
{
"Id": "$company_id$",
"Name":"$company_name$"
}
]
}
} |
FindContact
Is used to identify caller on incoming/outgoing call. Must return a specific contact identified by the phone number.
Example:
| Code Block | ||
|---|---|---|
| ||
"FindContact": {
"request_method": "GET",
"request_path": "/query?q=SELECT Id,FirstName,LastName,Email,Phone,Account.Name,MobilePhone,Title FROM Contact WHERE Phone LIKE '%$phone$' OR MobilePhone LIKE '%$phone$'",
"response_map":
{
"records":
[
{
"Id": "$contact_id$",
"FirstName": "$firstname$",
"LastName": "$lastname$",
"Email": "$email$",
"Phone": "$phone$",
"MobilePhone": "$mobile$",
"Account":{
"Name":"$company_name$"
},
"Title": "$job_title$"
}
]
}
} |
SearchContacts
Is used to filter through CRM contact records using the Ringotel Search field. Returns a list of contacts filtered by the phone number or name.
Example:
| Code Block | ||
|---|---|---|
| ||
"SearchContacts": {
"request_method": "GET",
"request_path": "/query?q=SELECT Id,FirstName,LastName,Email,Phone,Account.Name,MobilePhone,Title FROM Contact WHERE Phone LIKE '%25$prefix$' OR MobilePhone LIKE '%25$prefix$'OR FirstName LIKE '%25$prefix$%25'OR LastName LIKE '%25$prefix$'%25",
"response_map": {
"records": [
{
"Account": {
"Name": "$company_name$"
},
"Email": "$email$",
"FirstName": "$firstname$",
"Phone": "$phone$",
"Title": "$job_title$",
"Id": "$contact_id$",
"LastName": "$lastname$",
"MobilePhone": "$mobile$"
}
]
}
} |
CreateContact
Creates a new contact with properties.
Example:
| Code Block | ||
|---|---|---|
| ||
"CreateContact": {
"request_method": "POST",
"request_path": "/sobjects/Contact",
"request_parameters":
{
"FirstName": "$firstname$",
"LastName": "$lastname$ ",
"Email": "$email$",
"Phone": "$phone$",
"AccountId": "$company$"
},
"response_map":
{
"id": "$contact_id$"
}
} |
UpdateContact
Updates a specific contact identified by ID with the new properties.
Example:
| Code Block | ||
|---|---|---|
| ||
"UpdateContact": {
"request_method": "PATCH",
"request_path": "/sobjects/Contact/$contact_id$",
"request_parameters":
{
"FirstName": "$firstname$",
"LastName": "$lastname$",
"Email": "$email$",
"Phone": "$phone$",
"AccountId": "$company$"
},
"response_map":
{
"id": "$contact_id$"
}
} |
CreateActivity
Creates a new call activity with its properties.
Example:
| Code Block | ||
|---|---|---|
| ||
"CreateActivity": {
"request_method": "POST",
"request_path": "/sobjects/Task/",
"request_parameters":
{
"Subject":"$call_title$",
"OwnerId":"$user_id$",
"WhoId":"$contact_id$",
"CallType":"$activity_type$"
},
"response_map":
{
"id": "$activity_id$"
}
} |
UpdateActivity
Updates CRM activity identified by activity ID.
Example:
| Code Block | ||
|---|---|---|
| ||
"UpdateActivity": {
"request_method": "PATCH",
"request_path": "/sobjects/Task/$activity_id$",
"request_parameters":
{
"Subject": "$subject$",
"Description": "$comment$"
}
} |
StopCallActivity
Changes the status of a specific activity (identified by activity ID).
Example:
| Code Block | ||
|---|---|---|
| ||
"StopCallActivity": {
"request_method": "PATCH",
"request_path": "/sobjects/Task/$activity_id$",
"request_parameters":
{
"Status":"Completed",
"CallDurationInSeconds": "$call_duration_millis$"
}
} |
UploadFile
Uploads and attaches a call recording file to a specific activity (identified by ID).
Example:
| Code Block | ||
|---|---|---|
| ||
"UploadFile": {
"request_method": "POST",
"request_path": "/sobjects/Attachment",
"request_content_type": "application/json",
"request_parameters": {
"Name":"$filename$",
"ParentId":"$activity_id$",
"ContentType":"audio/wav",
"Body":"$file$",
"OwnerId":"$user_id$"
}
} |
Pagination
Pagination is done using the parameter paging_cursor, which needs to be defined in the Parameters tab.
Pagination is set to run either until no data is returned of after the first 2000 records are returned.
The paging_cursor value can be initialized during parameter definition.
Example
| Code Block |
|---|
"parameters": {
"paging_cursor": { "default":0}
} |
Afterwards it can be mapped using response_map as any other parameter and the new value will be used in the next loop.
Example
| Code Block |
|---|
"Contacts": {
"request_method": "GET",
"request_url": "$paging_cursor$",
"request_headers": { "Version" : "2021-07-28"},
"response_map":
{
"contacts":[
{
"id":"$contact_id$",
"email":"$email$",
"phone":"$phone$",
"firstName":"$firstname$",
"lastName":"$lastname$",
"companyName":"$company_name$"
}
],
"meta":{
"nextPageUrl":"$paging_cursor$"
}
}
}, |
In this example the entire endpoint URL is used as the paging cursor and the next URL is returned in the request and is mapped
You can also initialize it with an array of values and it will iterate through them until either all values are used, no data is returned, or the first 2000 records are returned.
Example
| Info | ||
|---|---|---|
|
this will initialize the cursor with a value of 200 and will increment it by 200 after each loop until it reaches 600.
This is useful when the CRM pagination is using the paging cursor to skip records and does not return anything in response that you can map.
Example:
| Code Block |
|---|
"GetContacts": {
"request_method": "GET",
"request_path": "api/contacts?limit=200&skip=$paging_cursor$",
"response_map":
{
"result":[
{
"firstname":"$firstname$",
"lastname":"$lastname$",
"email": "$email$",
"phone": "$phone$",
"mobile": "$mobile$",
"id": "4x$contact_id$",
"salutationtype": "$job_title$",
"account_id": "$company_id$"
}
]
} |
In this example the paging_cursor is used to indicate how many records to sip and the next value is not returned in the response, which means the cursor will iterate through the values in the array provided during parameter initialization.(the first 600 records in batches of 200 using the values from the example)
Below is an example of a JSON document for CRM integration. Please provide the completed JSON file to our team, and we will review it before adding it to the list of available CRM integrations for your Ringotel account. Should you have any questions/feedback, please don't hesitate to contact us at support@ringotel.co.
| View file | ||
|---|---|---|
|