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
The integration process works as follows: your messaging service will be listed in the SMS/MMS integrations section, specifically for your Ringotel account.
To enable the integration, you can do this 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:
Implementing the integration
To implement the integration, download the JSON file below, which acts as a template that you should modify with the 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: https://shell.ringotel.co/services/<service_id>/a<accountid>
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$"
}
},