Welcome to Nexmo Developer

We are improving our Documentation, API references, learning resources & tooling to help you more effectively use our services. We want to help you find everything you need to integrate Nexmo APIs into your code.

As we start this transition, we’d love to hear from you with thoughts & suggestions. If you’ve got something, positive or negative, to tell us, please tell us using the feedback tool at the bottom of each guide or file an issue on GitHub. - Nexmo

Receiving an SMS

With Nexmo's SMS API you can receive SMS messages on your virtual numbers.

To receive SMS messages, you need to buy a number and setup a webhook endpoint.

Buy a number

Log into the Nexmo dashboard and go to Numbers > Buy numbers  . Here you can buy a number with SMS capabilities.

Note: You can also buy numbers with Nexmo CLI. Run nexmo help or go here  to see how.

Implementing a webhook endpoint

To process incoming SMS messages, we will implement a webhook endpoint with a lightweight backend framework.

Install Express by typing: npm install express

The code below handles the incoming SMS messages.

var Express = require('express')

let app = Express()

app.get('/incoming-sms', (req, res) => {
  console.log(req.query)
  res.sendStatus(200)
})

app.listen(3000)

Store this as app.js and run it locally using node app.js.

This will run locally. Your webhook endpoint needs to be accessible on the public internet in order for Nexmo's servers to send messages to you. You can do this easily using a service like ngrok.com  .

Note: The Nexmo API expects a 200 OK response. The code samples provided already do this.

Configure the webhook

Go to Numbers > Your Numbers  in the dashboard and press edit next to the number you wish to receive SMS on.

Enter the URL for your webhook endpoint, then press update. Nexmo's API will send a request to this address for every SMS that is received.

Manage your numbers webhook

Send a message to your number

From your mobile device, send a message to the number you virtual number. The server running your webhook should print a copy of your message to the terminal.

Now that the server works, you can change the behaviour of the webhook endpoint to do something more interesting (respond to messages, store messages in a database) etc.

Payload

When a message is received on your number you will receive a GET request on the specified webhook URL.

Below you can find an example of what to expect in the payload.

{
    "msisdn": "447700900000",
    "to": "447700900001",
    "messageId": "0B00000057CC7BC7",
    "text": "Hello world",
    "type": "text",
    "keyword": "HELLO",
    "message-timestamp": "2017-01-01 00:00:00"
}