JSON Framework for integrating an SMS/MMS provider

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:

The outgoing messages and files from users will be sent as an HTTP request to your web server address in the format specified in the JSON file, 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. 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:

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:

The Webhook URL can be provided in the Ringotel portal when you configure 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.

JSON template file: