Receive an SMS with Python

Receive an SMS with Python

Published May 31, 2019 by Mark Lewin
Categories:

Earlier in this series we showed you how to send an SMS. In this post, we’ll show you how to receive SMS messages on your Nexmo virtual number.

To receive inbound SMS, you need to create a publicly-accessible webhook and configure your Nexmo account to use it. We’ll cover that process in this post and you can find the source code on Github.

Prerequisites

You need a Nexmo account. If you don’t already have one you can sign up here. It’s free to get started.

You’ll use Python 3 and Flask to write your webhook. You can install flask with the pip3 package manager:

Lastly, you’ll need to install the Nexmo CLI. You will use this to purchase a Nexmo virtual number (if you haven’t already got one) and to send a test SMS.

When you have all these things, you’re ready to start coding!

Create the Webhook for Inbound SMS

When Nexmo receives an SMS on your virtual number, it looks to see if you have configured a webhook on your account so that it can forward the SMS to your application. You can configure this webhook to apply either to a specific number or your account as a whole.

Nexmo makes either a GET or POST request depending on which “HTTP Method” you have configured in your account settings. Because you want your webhook to work regardless of your account settings you will code the handler to accept both types of request.

Create a file called sms-receive.py and enter the following code:

This code captures any request sent to the /webhooks/inbound-sms endpoint and unpacks it:

  • request.is_json: Checks to see if the request is in JSON format. By default a request is considered to include JSON data if the mimetype is application/json or application/*+json
  • request.args: Retrieves the key/value pairs in the URL query string.
  • request.form: Retrieves the key/value pairs in the body, from a HTML post form, or any request that isn’t JSON-encoded.

This approach enables your application to retrieve the message details from either a GET or POST request.

Having parsed the incoming request data it pretty-prints it to the terminal using pprint and then sends a HTTP 204 status response (success, no content) to Nexmo. It is important to return this response otherwise Nexmo will keep trying to redeliver.

Make Your Webhooks Accessible

For Nexmo’s APIs to make requests to your webhook endpoint it must be accessible over the public internet.

A great tool for exposing your local development environment to the internet is ngrok. Our tutorial shows you how to install and use it.

Launch ngrok using the following command:

Make a note of the public URLs that ngrok creates for you. These will be similar to (but different from) the following:

On their free plan, every time you restart ngrok the URLs change and you will have to update your delivery receipt URL. This is extra work you could do without, so leave it running for the duration of this tutorial.

Purchase a Nexmo Number

If you don’t already have a Nexmo virtual number to use for this example, you’ll need to buy one. You can do this in the developer dashboard but it’s often more convenient to perform these account management tasks using the Nexmo CLI. So that’s what we’ll do here.

To check which numbers are available, use nexmo number:search, passing it your two-character country code. For example, GB for Great Britain or US for the USA. You want to ensure that the number you purchase is able to receive SMS:

Choose a number from the list and buy it using the following command:

You will be prompted to confirm your purchase. Make a note of the number that you bought.

Configure Your Nexmo Account

The next thing you need to do is configure your account with the webhook URL so that Nexmo can forward any inbound SMS to your application.

This is another task that you could perform either in the dashboard or by using the Nexmo CLI. Here’s how to do it with the CLI. Replace the following placeholders with your own values:

  • NEXMO_VIRTUAL_NUMBER: Your own virtual number, which should include the international dialling code and omit the leading zero, for example: 447700900001.
  • WEBHOOK_URL: Your webhook endpoint with the ngrok URL as the domain name. For example: http://abc123.ngrok.io/webhooks/inbound-sms.

This configures your virtual number to use your webhook. If you want to create a “catch all” webhook to capture SMS sent to any of your numbers, visit your account settings page and enter the URL in the “Inbound messages” textbox under “Default SMS Setting”. Nexmo always uses the number-specific webhook if it has been set.

Try it Out

With ngrok running on port 3000 in one terminal window, launch your Python application in another:

Use the Nexmo CLI to send a test SMS to your Nexmo number:

In the terminal window that is running your Python application you should see that your webhook received the inbound SMS:

Further Reading

If you want to learn more about the SMS API, check out the following resources:

Leave a Reply

Your email address will not be published.