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: Ringotel API

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:

"parameters": {
  "user_id": "number",
  "user_name": "string",
  "contact_id": "number"
}

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.

Each parameter must have the appropriate data type according to the CRM API, i.e. string, number, ISO8601Date, etc.

Parameter list:

"phone": string

Phone number of a CRM user or contact.

“email”: string

Email address of a CRM user or contact.

"user_id": string

CRM user ID.

"contact_id": string

CRM contact(customer, client) ID.

"activity_id": string

CRM Activity record(call) ID.

"activity_type": "inbound" | "outbound"

Activity type description, stores the direction of a call. It has two possible values "inbound" or "outbound".

"user_name": string

Full name of a CRM user.

"contact_name": string

Full name of a CRM contact(customer, client).

"firstname": string

First name of a CRM user or contact.

"lastname": string

Last name of a CRM user of contact.

"subject": string

Call activity subject.

"description": string

Call activity comment.

"company_name": string

CRM organization(company, lead, firm) name.

"company_id": string

CRM organization(lead, firm) id.

"content_url": string

Unencoded URL of a call recording.

"user_number": string

Ringotel user extension number.

"party_number": string

Calling or called party number (depending on the activity_type).

"calling_number": string

Calling party number.

"called_number": string

Called party number.

"call_duration": number

Call duration (in seconds).

"call_timestamp": number | ISO8601Date

Call start timestamp in EPOCH format (milliseconds from Jan 1, 1970). Alternatively, the data type could be set to ISO8601Date format to set the parameter’s value to ISO 8601 format, e.g. 2024-09-10 15:00:00.000.

"call_timestop": number | ISO8601Date

Call end timestamp in EPOCH format (milliseconds from Jan 1, 1970). Alternatively, the data type could be set to ISO8601Date format to set the parameter’s value to ISO 8601 format, e.g. 2024-09-10 15:00:00.000.

"call_cause": string

SIP hangup cause code.

"call_url": string

Unencoded URL to access the call recording.

"domain": string

Ringotel organization domain.

"filename": string

Uploaded file name.

"file": string

Base64-encoded body of an uploaded file.

"since": ISO8601Date

Date of the last contact record modification.

“prefix“: string

Stores the value of the “Search“ field in the Ringotel app, used for the SearchContact method.

“connection_id“: string

Connection (branch) ID.

“connection_name“: string

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:

{
    "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.

"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:

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:

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".

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.

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:

Bearer Authentication example:

Basic Authentication example:

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.

Alternatively, you can specify an absolute path for the API endpoint by replacing request_path with request_url.

"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:

“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.

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:

Contacts

Returns the list of contacts and their properties.

Example:

Organizations

Returns the list of accounts and their properties.

Example:

FindContact

Is used to identify caller on incoming/outgoing call. Must return a specific contact identified by the phone number.

Example:

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:

CreateContact

Creates a new contact with properties.

Example:

UpdateContact

Updates a specific contact identified by ID with the new properties.

Example:

CreateActivity

Creates a new call activity with its properties.

Example:

UpdateActivity

Updates CRM activity identified by activity ID.

Example:

StopCallActivity

Changes the status of a specific activity (identified by activity ID).

Example:

UploadFile

Uploads and attaches a call recording file to a specific activity (identified by ID).

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.