Share article:
Messages API explained in 5 minutes
In an era of digital natives, reaching others, whether they are your loved ones or customers, has been reduced to something as simple as the press of a button. Yes, it’s an exciting time to be alive but without the right APIs, this would’ve still remained a figment of the imagination. Texting has become the most widely-used and frequently used app on a smarphone with 97% of Americans using it at least once a day. Let’s dive in and find out how the MessageMedia Messages API fits into that picture.
The MessageMedia Messages API provides a number of endpoints for building powerful two-way messaging applications. The Messages API provides access to three main resources:
- Messages
- Replies
- Delivery Reports
Simply put, the Messages endpoint can be used to send SMS, MMS or text to voice messages. The most basic message has the following structure.
{
"messages": [
{
"content": "My first message!",
"destination_number": "+61491570156"
}
]
}
You can specify other properties such as scheduled if you’d like to send the message at a later time, metadata if there’s a need for tracking customer data while sending and receiving messages or even a callback_url to be kept informed when the message changes its status. You can view the full list of properties over here.
The replies endpoint can be used to check for any replies that have been received. Replies can be messages that have been sent from a handset (not an application) in response to a message sent by an application. A response from the check replies endpoint will have the following structure.
{
"replies": [
{
"metadata": {
"key1": "value1",
"key2": "value2"
},
"message_id": "877c19ef-fa2e-4cec-827a-e1df9b5509f7",
"reply_id": "a175e797-2b54-468b-9850-41a3eab32f74",
"date_received": "2016-12-07T08:43:00.850Z",
"callback_url": "https://my.callback.url.com",
"destination_number": "+61491570156",
"source_number": "+61491570157",
"vendor_account_id": {
"vendor_id": "MessageMedia",
"account_id": "MyAccount"
},
"content": "My first reply!"
}
]
}
Each reply will contain details about the reply message, as well as details of the message the reply was sent in response to, including any metadata specified. A reply ID will also be included in the response which is intended to be used with the confirm replies endpoint to ensure the replies that have been processed are no longer returned in subsequent check replies requests
Delivery reports are a notification of the change in status of a message as it is being processed. The delivery reports endpoint can be used to check for any delivery reports that have been received. A response from the check delivery reports endpoint will have the following structure.
{
"delivery_reports": [
{
"callback_url": "https://my.callback.url.com",
"delivery_report_id": "01e1fa0a-6e27-4945-9cdb-18644b4de043",
"source_number": "+61491570157",
"date_received": "2017-05-20T06:30:37.642Z",
"status": "enroute",
"delay": 0,
"submitted_date": "2017-05-20T06:30:37.639Z",
"original_text": "My first message!",
"message_id": "d781dcab-d9d8-4fb2-9e03-872f07ae94ba",
"vendor_account_id": {
"vendor_id": "MessageMedia",
"account_id": "MyAccount"
},
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
]
}
Each delivery report will contain details about the message, including any metadata specified, the new status of the message and the timestamp at which the status changed. Every delivery report will have a unique delivery report ID for use with the confirm delivery reports endpoint. Similarly to the check replies endpoint, the confirm delivery reports endpoint is intended to be used in conjunction with the delivery reports endpoint to ensure the delivery reports that have been processed are no longer returned in subsequent check delivery reports requests.
Want to know more? Read this tutorial on how you can send appointment reminders in Ruby using the Messages API. Happy coding!
