Page Comparison

...

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.

...

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:

// 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"
    }
}

...

JSON template file: