You can add your own messaging service/platform to the list of our out-of-the-box integrations, which are available in the "Integrations" tab, visible only to the organizations created under your Ringotel account.
The main use case for messaging integration is to enable external messaging for users. This means allowing users to send and receive SMS/MMS messages with external contacts instead of internal users. The group functionality and "orgid" lookup are already built-in, so you don't need to implement them additionally. All you need to do is describe the HTTP requests using the JSON data format according to your messaging web server API using the provided template.
How does it work
Step 1: Implement the integration. Implement the JSON file according to the integration framework. For this, copy the JSON template provided below and customize it with your service API details and according to the integration framework described below.
Step 2: Send the JSON file for review. Once you have implemented the JSON integration file, send it over to our team for review at support@ringotel.co. Our team will verify that the file is implemented correctly and provide any feedback if needed. We will then add your integration to our platform, which (by default) will only be visible for your customers.
Step 3: Enable the integration in your Ringotel admin portal. Your messaging service will be listed in the SMS/MMS integrations section, specifically for your Ringotel account. For example:
You can enable the integration for each of your Ringotel organizations. As part of the configuration process, you will need to add SMS phone numbers and assign them to Ringotel users who should have access to sending and receiving messages through those specific SMS numbers. For instance:
Complete JSON file example
{
"id": "YourService",
"name": "YourService",
"logo": "https://example.com/assets/logo.png",
"class": "sms",
"properties": [
"API key"
],
"auth": {
"type": "Bearer",
"token": "$API key$"
},
"API": {
"SendMessage": {
"request_method": "POST",
"request_url": "https://api.example.com/messages",
"request_content_type": "application/json",
"request_parameters": {
"from": "$from$",
"to": "$to$",
"content": "$content$"
},
"response_map": {
"data": {
"id": "$messageid$"
}
}
},
"SendFile": {
"request_method": "POST",
"request_url": "https://api.example.com/messages",
"request_content_type": "application/json",
"request_parameters": {
"from": "$from$",
"to": "$to$",
"content": "$content$"
},
"response_map": {
"data": {
"id": "$messageid$"
}
}
}
},
"Webhook": [
{
"event_key": "delivered",
"event_type": "messageDelivered",
"request_method": "POST",
"request_parameters": {
"method": "$event_key$",
"params": {
"messageid": "$messageid$"
}
}
},
{
"event_key": "file",
"event_type": "mms",
"request_method": "POST",
"request_parameters": {
"method": "$event_key$",
"params": {
"from": "$from$",
"to": "$to$",
"text": "$text$",
"url": "$url$"
}
}
},
{
"event_key": "message",
"event_type": "message",
"request_method": "POST",
"request_parameters": {
"method": "$event_key$",
"params": {
"from": "$from$",
"to": "$to$",
"content": "$content$"
}
}
}
]
}
Implementing the integration
To implement the integration, copy the complete JSON file example, which acts as a template that you should modify according to your messaging service details. The file has the following structure:
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.
"properties":[
"Access Key",
"Secret Key"
],
Authorization
Authentications can be based on Basic or Bearer authentication. Alternatively, the OAuth 2.0 Web Server Flow using the client_id and client_secret can be used.
Bearer Authentication example:
"auth": {
"type": "Bearer",
"token": "$API key$"
},Basic Authentication example:
"auth": {
"type": "Basic",
"username": "$Username$",
"password": "$Password$"
},OAuth2 Authentication example:
"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"
}API
The outgoing messages and files from the Ringotel users will be sent as an HTTP request to the specified web server address in the specified JSON format, namely API.SendMessage and API.SendFile methods, for example:
"API": {
"SendMessage": {
"request_method": "POST",
"request_url": "https://api.example.com/webhook",
"request_content_type": "application/json",
"request_parameters": {
"from": "$from$",
"to": "$to$",
"extension": "$extension$",
"domain": "$domain$",
"content": "$content$"
},
"response_map": {
"data": {
"id": "$messageid$"
}
}
},
"SendFile": {
"request_method": "POST",
"request_url": "https://api.example.com/webhook",
"request_content_type": "application/json",
"request_parameters": {
"from": "$from$",
"to": "$to$",
"extension": "$extension$",
"domain": "$domain$",
"media_url": "$content$"
},
"response_map": {
"data": {
"id": "$messageid$"
}
}
}
},On the other hand, the Webhook object (section) describes the requests and parameters that your messaging server should send to the Ringotel server, for example:
Send message:
//model
{
"event_key": "message",
"event_type": "message",
"request_method": "POST",
"request_parameters": {
"method": "$event_key$",
"params":{
"from": "$from$",
"to": "$to$",
"content": "$content$"
}
}
}
// POST request JSON body
{
"method": "message",
"params":{
"from": "+61855555555",
"to": "+61123456789",
"content": "Hello there!"
}
}
Send file:
//model
{
"event_key": "file",
"event_type": "mms",
"request_method": "POST",
"request_parameters": {
"method": "$event_key$",
"params":{
"from": "$from$",
"to": "$to$",
"text": "$text$",
"url":"$url$"
}
}
},
// POST request JSON body
{
"method": "file",
"params":{
"from": "+61855555555",
"to": "+61123456789",
"text": "Sending a file",
"url":"https://your.server.com/files/8a8d89798as9ud.jpeg"
}
}
"Delivered" notification:
// model
{
"event_key": "delivered",
"event_type": "messageDelivered",
"request_method": "POST",
"request_parameters": {
"method": "$event_key$",
"params":{
"messageid": "$messageid$"
}
}
},
// POST request JSON body
{
"method": "delivered",
"params": {
"messageid": "9612c4e2-27f8-4463-a517-c6306ffdabff"
}
}
The Webhook URL is provided in the Ringotel admin portal when you set up the integration. The format of the URL would be as follows:
The Webhook URL doesn't change, unless you update JSON file with the new service ID. So you can copy the existing URL and use it in the requests.
Additionally, Ringotel can send a Webhook URL in an API request to your server after enabling the integration, for example:
"Subscribe": {
"request_method": "POST",
"request_content_type": "application/json",
"request_url": "https://$Server$/ns-api/v2/subscriptions",
"request_parameters": {
"domain": "$Domain$",
"user": "*",
"model": "message",
"post-url": "$webhook_url$"
}
},