Content Comparison

...

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 your the specified web server address in the format specified in the JSON fileformat, namely API.SendMessage and API.SendFile methods, for example:

...

On the other hand, the Webhook object (section) describes the requests and parameters that your messaging server should send to the Ringotel server. You can send those requests in any format, but if you want to match the existing format of the Ringotel Messaging API, you can try something like this, 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!"
    }
}

...

//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 can be is provided in the Ringotel admin portal when you configure set up the integration. The format of the URL would be as follows: https://shell.ringotel.co/services/<service_id>/a<accountid>

JSON template file:

...

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$"
   }
},