SMS Callbacks

You can create analytics on your SMS and MMS traffic by using event-based webhooks — user-defined HTTP callbacks — to track the delivery status of outgoing and incoming messages.

For every SMS and MMS message you send and receive, Plivo sends a status update to a URL you configure as a callback. You can store the information on your server for delivery status analysis.

The webhooks you integrate with Plivo are triggered by incoming messages or calls. Upon one of these events, Plivo makes an HTTP request (POST or GET) to an endpoint URL you’ve configured for the webhook. In the callback, you can send all the information related to the message either in the POST request’s body or the GET request’s query parameters. To handle a webhook, you must create a listener (web app) that can accept these HTTP requests from Plivo.

​

Webhooks for outbound SMS

Here’s how to use Plivo APIs to send SMS messages from your web application and include a callback URL. Before you get started, you must buy an SMS-enabled Plivo phone number to send messages to the US and Canada. You can purchase numbers from Phone Numbers > Buy Number section of the Plivo console, or by using the Numbers API.

For Plivo to invoke your webhook and send HTTP requests, you must configure the URL parameter with your webhook URL and set the method as either POST or GET, then specify this URL for message status-related callbacks.

See the send SMS usage guide for more information about how to send SMS messages on a two-way SMS-enabled Plivo phone number.

​

Code

import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.messages.create(
    src='<sender_id>',
    dst='<destination_number>',
    text='Hello, this is a sample text',
    url='https://<yourdomain>.com/sms_status/',
)
print(response)
# prints only the message_uuid
print(response.message_uuid)

​

Webhooks for inbound SMS

See the receive SMS usage guide for more information about how to receive SMS messages on a two-way SMS-enabled Plivo phone number.

​

Handle callbacks in your web app

To handle callbacks in your app, your endpoint should:

• Capture HTTP requests
• Respond to the requests

When Plivo sends the HTTP request callbacks to the webhook during an event, you should capture the request (POST or GET based on the type you’ve defined for the URL) and respond with a 200 OK response. You can store the callback data to your database.

​

Test and validate

Let’s take a look at an example. Typically, you would include a URL that points to your web app, but we’ll use a URL from RequestBin, a service that lets you collect, analyze, and debug HTTP requests, so we can check the callbacks.

• Create a new bin in RequestBin.
• Replace the “url” placeholder with the URL of the new bin.
• Run the code that appear above. You should receive the SMS message on the phone number defined in destination field, and see callback requests in RequestBin similar to the screenshots below for callback events such as queued, sent, and delivered.

​

Queued status callback

​

Sent status callback

​

Delivered status callback

​

Validating callbacks

To avoid spoof attacks, you can validate the callbacks that your server URL receives. All requests made by Plivo to your server URLs include X-Plivo-Signature-V2, X-Plivo-Signature-Ma-V2, and X-Plivo-Signature-V2-Nonce HTTP headers. You can use them to validate that a request is from Plivo, as we discuss in our signature validation guide.

​

Conversion feedback to Plivo

You can store the data from the message status callbacks in your database for analytics. You can also choose to provide the data to Plivo as message delivery feedback. Plivo’s Conversion Feedback API lets you update Plivo on conversions for your critical two-factor authentication (2FA) and one-time password (OTP) messages. Your feedback helps us ensure consistently high delivery rates in countries where carrier networks may be unstable. Plivo’s machine-learning-based dynamic routing engine uses all of our customers’ feedback to ensure that your messages are delivered over the best-performing carrier route to the destination mobile network.