With the advancement of technology, notifying people has become a one-step process. Gone are the days when people remind each other of events or other occasions by word of mouth. A more effective, efficient and reliable method of notifying people is through messaging. If Harry has an appointment scheduled for 6pm on Wednesday, we can send him a confirmation a day before, followed by a reminder an hour before the actual appointment. Harry has a busy schedule so by notifying him, he will be aware that he’s expected for that particular appointment.
This tutorial will cover:
- Sending a message using metadata and scheduling a message
- Checking the status of a message
- Checking for replies to messages
- Checking for delivery reports
- Confirming receipt of a reply and delivery report once it has been processed
- Implementing webhooks
If you get stuck on any section at any time, you can look at the code in this repository to help you out.
Prerequisites
In order to work through this tutorial, you need:
Installing Messages Ruby SDK
For this part you'll need a code editor such as Sublime Text or Atom. We'll be using Ruby to develop our app, so you'll need to make sure you've installed it on your machine as well. Now create an empty folder for your project, let's name it "testApp". Now, open up your command prompt, cd to the directory and run the following command to install the Messages SDK:
gem install messagemedia_messages_sdk
Sending a message
Create an app.rb file inside that folder and open it up in your editor. Write down the following code. I've commented it, so you can understand what's going on with each line.
require 'message_media_messages.rb' # This gem contains all the logic for dealing with the MessageMedia Messages API
require 'pp' # This gem is for displaying 'pretty' JSON
def setup
# The API credentials needed to access the Messages API
auth_user_name = 'API_KEY'
auth_password = 'API_SECRET'
use_hmac = false # Change this to true if you are using HMAC keys
# Instantiating the client
client = MessageMediaMessages::MessageMediaMessagesClient.new(
auth_user_name: auth_user_name,
auth_password: auth_password,
use_hmac: use_hmac
)
return client
end
def send_message
client = setup();
# Creating the message structure
messages = client.messages
body_value = '{
"messages":[
{
"content":"Hi Harry, you have an appointment with Dr. Harrod today at 6pm. Reply Y to confirm or N to cancel.",
"destination_number":"MOBILE_NUMBER",
"metadata": {
"name": "Ibrahim"
},
"scheduled": "2018-04-30T11:49:02.807Z",
"delivery_report": "true"
}
]
}';
# Parsing the message body and converting it into a Ruby object
body = JSON.parse(body_value);
# Finally, sending the message
result = messages.create_send_messages(body)
# Displaying the response in the console
pp result
end
# Call the send_message function
send_message
We’ve scheduled the message to be sent a day before Harry’s appointment and we’ve also included some metadata in the message body. Metadata can be used when you don’t want to store persistent data in the application. Up to 10 key / value metadata data pairs can be specified in a message. Before you send the message, add in your API credentials and Harry’s number which is +61491570156. Now you’re good to go!
This is what a successful response body should look like.
Checking the status of the message
The submitted message is queued (check the status of the above screenshot). You don’t know when and if the message was actually sent from the initial API response. We can find out more about this by checking the message status using the message ID which can be found in the response object.
Let’s add some code to check the status of the last message we sent.
def check_status
client = setup()
messages = client.messages
message_id = 'YOUR_MESSAGE_ID'
result = messages.get_message_status(message_id)
print result.inspect
end
# Call the check_status function
check_status
Don’t forget to replace the messageID placeholder with an actual messageID. In my case, it was fbbe1ae6-8ad7-441d-bc4c-551880911e2b. This is the response I received:
The response structure is very similar to the send_message one. You can see in the response that the message is currently scheduled to be delivered. Let’s hope Harry doesn’t miss his appointment and to make sure he doesn’t we’ll send him another reminder in the next section where we’ll find out how to check for replies.
Checking for replies
Replies sent from a handset will show up when we call the replies function so let’s try sending a message to Harry from our mobile phone.
Now let’s add some code to check for replies.
def check_replies
client = setup()
replies = client.replies
result = replies.get_check_replies()
print result.inspect
end
# Call the check_replies function
check_replies
Each request to the check replies endpoint will return any replies received that have not yet been confirmed using another endpoint similar to replies called confirm replies. A response from the check replies endpoint will have the structure shown below.
Check delivery reports
Delivery reports are a notification of the change in status of a message as it is being processed.
Each request to the check delivery reports endpoint will return any delivery reports received that have not yet been confirmed using the confirm delivery reports endpoint.
Now let’s add some code to check for delivery reports.
def check_delivery_reports
client = setup()
deliveryReports = client.delivery_reports
result = deliveryReports.get_check_delivery_reports()
pp result
end
# Call the check_delivery_reportsfunction
check_delivery_reports
A response from the check delivery reports endpoint will have the following structure.
Confirming replies and delivery reports
The confirm replies endpoint is intended to be used in conjunction with the check replies endpoint to allow for robust processing of reply messages. Once one or more reply messages have been processed they can then be confirmed using the confirm replies endpoint, so they are no longer returned in subsequent check replies requests. The confirm delivery reports endpoint works in the exact same manner but with the check delivery reports endpoint instead.
The confirm replies endpoint takes a list of reply IDs as follows:
{
"reply_ids": [
"011dcead-6988-4ad6-a1c7-6b6c68ea628d",
"3487b3fa-6586-4979-a233-2d1b095c7718",
"ba28e94b-c83d-4759-98e7-ff9c7edb87a1"
]
}
And the confirm delivery reports endpoint takes a list of delivery report IDs as follows:
{
"delivery_report_ids": [
"011dcead-6988-4ad6-a1c7-6b6c68ea628d",
"3487b3fa-6586-4979-a233-2d1b095c7718",
"ba28e94b-c83d-4759-98e7-ff9c7edb87a1"
]
}
It is likely that you poll the check replies or check delivery reports endpoint for results. As you can tell, this can be become very tedious very quickly. Why? You will have to poll the endpoint for every send_message request that you make so for a 1000 messages sent that's 1000 requests to each endpoint. Jeez! It’s not recommended to process replies or reports separately. Instead, you can use webhooks. A webhook is basically a URL and if a web application implements that webhook, then messages can be POSTed to that URL when certain things happen.
By using webhooks, you can automatically receive changes to the message status, replies received in response to the message or delivery reports received for the message.
Webhooks
To enable webhooks, simply specify a callback_url parameter in the message body of your send_message function.
"messages":[
{
"content":"Just a reminder, you’ve got an appointment today.",
"destination_number":"+61491570156",
"metadata": {
"name": "Ibrahim"
},
"delivery_report": "true",
"callback_url": "https://my.callback.url.com"
}
]
I personally like to test out callback invocations at a website called Webhook Tester. This website allows you to easily test webhooks and other types of HTTP requests. It logs any requests sent to that URL instantly and the best part is you don't even have to refresh.
Let’s try sending a message using a callback_url from Webhook Tester. To get a callback url, visit Webhook Tester and then copy the unique URL that should be generated for you on the landing page.
Let’s modify our message body to add support for the callback_url. This is what your message body should look like. I’ve added in my callback_url.
"messages":[
{
"content":"Just a reminder, you’ve got an appointment today",
"destination_number":"+61491570156",
"metadata": {
"name": "Ibrahim"
},
"delivery_report": "true",
"callback_url": "https://webhook.site/d49c3883-c1fd-4cf5-8977-52a4ea57ddc2"
}
]
A few seconds after invoking the send_message function, you should see something similar on your Webhook Tester screen.
On the left-hand side of the screen, you’ll find multiple requests. These are your delivery reports and each one will have a different status. This illustrates how the message status changes as it passes from the sender to our gateway to the carrier and finally to the receiver. To get a ‘prettier’ view of the response object, tick the “Format JSON” box on the very top of the screen right under the navigation bar.
Here is a snippet of one of my delivery reports:
Conclusion
Harry is on his way to the appointment. He says he would’ve forgotten about it if it weren’t for you. You’ve not only ensured Harry attends his appointment but also learnt a lot along the way. Great job!
Get the code
All the code for this tutorial is available in the Ruby Messaging Tutorial Github repo
Resources