• Choose:

Receiving SMS and MMS

Inbound texts are delivered via a webhook to your server. The webhook will be an HTTP POST request that includes a payload with information about the inbound SMS or MMS. To receive the message, you’ll need to create a minimal web application that will accept the webhook request.

Install Dependencies

We will use the express framework to setup a webserver that will receive webhooks. Create a new npm project and install express and body-parser. This will allow you to receive incoming HTTP requests

npm init
npm install express body-parser --save

Create an express application to accept webhooks

Now create a new file, receive.js, and import the dependencies.

const express = require('express');
const bodyParser = require('body-parser');

Next, setup the Node app to parse requests as JSON.

const app = express();

Handling the request

Then create a POST handler, this should be the same endpoint that you have configured Telnyx to send requests to.

app.post('/webhook', (req, res) => {
    console.log(`New message from ${req.body.from}: ${req.body.body}`);

Start the server.

const port = 8080;
app.listen(port, () => console.log(`App running on port ${port}`));

From your terminal run this command to start the server.

node receive.js

A sample webhook from Telnyx would look like this:

    "sms_id": "8d7b47fc-be08-4820-8ce3-58fd4fe42a76",
    "direction": "inbound",
    "from": "+15555555",
    "to": "+16666666",
    "body": "Hello world"

The final step involves making your application accessible from the internet. So far, we've set up a local web server. This is typically not accessible from the public internet, making testing inbound requests to web applications difficult.

The best workaround is a tunneling service. They come with client software that runs on your computer and opens an outgoing permanent connection to a publicly available server in a data center. Then, they assign a public URL (typically on a random or custom subdomain) on that server to your account. The public server acts as a proxy that accepts incoming connections to your URL, forwards (tunnels) them through the already established connection and sends them to the local web server as if they originated from the same machine. The most popular tunneling tool is ngrok. Check out the ngrok setup walkthrough to set it up on your computer and start receiving webhooks from inbound messages to your newly created application.

Once you've set up ngrok or another tunneling service you can add the public proxy URL to your Messaging Profile. To do this, click the edit symbol next to your Messaging Profile. Under “Inbound”, paste the forwarding address from ngrok into the Webhook URL field. Add /webhooks to the end of the URL to direct the request to the webhook endpoint in your Flask app.

Receiving Messages Webhook URL

For now you'll leave “Failover URL” blank, but if you'd like to have Telnyx resend the webhook in the case where sending to the Webhook URL fails, you can specify an alternate address in this field.

Now that your Messaging Profile is configured, you're ready to receive an SMS or MMS.

Send a message from your phone to your Telnyx number. Soon after you’ll see an event printed in your terminal when the inbound SMS or MMS request is received by your Flask application.

Congrats, you’ve learned how to recieve messages with Telnyx.

Was this page helpful?