Understanding Messaging API Callbacks - Part 1

The callback functionality of the messaging API is a great utility allowing you to track the delivery status of sent messages, and receive replies to your dedicated phone number without the need of making additional API calls.

In this first of 2-post series, I will walk through how to set up callbacks for your app and how to develop and test callback features without having a hosted endpoint.

Sample code in this blog post is taken from the Happy Chat demo app available on our GitHub and is written in node.js and Angular 5.

Using Postman

This blog post will refer to and use Postman quite frequently. If you’re already familiar with Postman or would prefer to use a different tool to make API calls, feel free to skip this bit, otherwise here’s a quick how-to on using Postman to send messages using the messaging API.

Let’s take the example of sending an SMS message. To do this we need to set a few things; the request type, the request URL, any request headers and finally the request payload. We can use Postman to do this easily.

Firstly, change the request type to POST by cliking the dropdown at the top of the screen. If this is a fresh tab, it will be set to GET by default. Then in the input field labelled Enter request URL we need to put the URL used for sending SMS messages using the messaging API: https://tapi.telstra.com/v2/messages/sms

Next, set the headers by clicking on headers. To send an SMS we need to supply our authorisation token, the content type and the accept parameters like so:

Now, we can click on body to set up the request body. The minimum information required by the messaging API is a phone number to send the message to and the content body of the message:

Finally, click on send to use Postman to send the SMS and the contents in the body field will be sent to the phone number specified in the to address!

This is a pretty quick run-down on how to use Postman for the purpose of following this blogpost, if you'd like more details on using Postman there are loads of resources online inluding their own official documentation. With that out of the way, lets get onto how to make the most of the messaging API using callbacks!

Setting up the receive message callback

When provisioning a number using the https://tapi.telstra.com/v2/messages/provisioning/subscriptions endpoint there are two optional request parameters you can provide: activeDays and notifyURL. Here, the notifyURL parameter will be the URL that the messaging API will send all received message data to. For example, your provisiong request payload may look something like this:

{
  "activeDays": "30",
  "notifyURL": "https://my-messaging-app.com/myReceiveMessageEndpoint"
}

It may take up to a minute but now any messages sent from regular phone numbers to your provisioned number will be picked up by the messaging API and their contents will be directed to the URL you specified in the notifyURL parameter. Additionally, the value of the notifyURL can be changed at anytime by sending this request again with a different value set for the notifyURL parameter.

Received messages arrive at your notifyURL will look like this:

{
  "to":"+61...",
  "from":"+61...",
  "body":"Hello",
  "sentTimestamp":"2018-01-08T11:07:40",
  "messageId":"QMASApiA0000041513"
}

One immediate drawback of this is that we need somewhere to host our app in order to pick up this callback from the messaging API, which isn't always feasible while we're still developing. However, we can get around this by using request bin and Postman.

[UPDATE: Since this post was written, the site https://requestb.in/ is no longer available. You can try alternatives such as https://requestbin.com/ or https://hookbin.com/. The post has been updated to point to the https://requestbin.com/ service.]

Lets run through a full example of this. First navigate to https://requestbin.com/ and set up a mock endpoint by clicking on the create button.

The URL you see on this page will be our notifyURL. Now, open Postman and send a the provisiong request with the request bin URL as our notifyURL

{
  "notifyURL": "https://requestbin.com/r/u74vmvu7"
}

Now in your browser navigate to the request bin URL and append ?inspect to the end. Using the URL here, that would be https://requestbin.com/r/u74vmvu7?inspect. From this screen we can see any requests that are picked up here, including messaging we send back to our messaging API number.

Try sending an SMS message to a phone you'll be able to reply from using the messaging API and reply to it. Refresh the request bin page and you should see the message you replied with!

You can see the message ID of the retreived message, the senders phone number, a timestamp of when the message was sent and the message content. Pretty cool stuff, you can now provision a number with a mock URL and use request bin to confirm that it’s all working properly.

Stay tuned for part two of this post series where I will cover receiving and handling delivery notifications using the callback.

Thanks for reading and happy coding!

[Updated] Link to part 2 available here https://dev.telstra.com/content/understanding-messaging-api-callbacks-part-2