Sending outbound SMS messages with MessageBird

⏱ 5 min build time || Watch the Video Tutorial

In this MessageBird Developer Tutorial you’ll learn how to send your first SMS using the MessageBird SMS Messaging API.

Before we get started, have you set up your NodeJS development environment and project directory with the MessageBird SDK?

  • No! Make sure you to set this up before continuing; you can read this MessageBird Developer Tutorial to learn how to do so.
  • Yes! Great! Now you can make your first API request and send an SMS message with MessageBird using NodeJS.

Getting started

First, let's create a new file in the directory of your

package.json
file and call it
send_sms.js
.

In this file, let's include the MessageBird SDK using

require()
. The SDK expects a single argument, your API key. Next, to start testing the SDK, you can simply replace the string
YOUR-API-KEY
in the following Javascript code and thus hardcode your API key.

Pro-tip: For production applications, we recommended storing the key in a configuration file or environment variable instead, and pass this variable with the key to the

require()
function. You'll see this in practice later in our MessageBird Developer Tutorials for building common use cases.

var messagebird = require('messagebird')('YOUR-API-KEY');

Now, to send a message with the SDK, we call

messages.create()
on the SDK object and pass a Javascript hash as the first argument. This hash contains values for the required attributes
originator
,
recipients
and
body
:

messagebird.messages.create({
originator : '31970XXXXXXX',
recipients : [ '31970YYYYYYY' ],
body : 'Hello World, I am a text message and I was hatched by Javascript code!'
},

But wait, what do these attributes mean? 🤔

  • The

    originator
    is the sender for the message; it can be a telephone number including country code or an alphanumeric string (with a maximum length of 11 characters). You can use the number you bought as part of our Getting Started tutorial as originator. Keep in mind that alphanumeric senders are not supported in every country including the United States, so it’s important to check the country restrictions. If you can't use alphanumeric IDs, use a real phone number instead. You can check our originator article in Help Center to learn more about this topic.

  • The

    recipients
    are the phone numbers that will receive the message. All numbers should be in the international format with country code. You must specify this attribute as an array even if you have just a single recipient. You can send a message to up to 50 numbers at a time. For testing, add your own mobile telephone number here so you can receive the test message on your phone.

  • The

    body
    is the content of the message. Keep in mind that SMS messages are limited to 160 characters, and if you enter a longer value for the body it will be split into multiple parts which are each sent and billed separately.

Make sure to replace the values in the sample code with adequate data for testing. There are additional optional attributes as well; you can find them in our SMS Messaging API documentation.

The second argument to the SDK function is a callback. The API call is asynchronous and triggers the callback function once it has received a response from the MessageBird servers. The callback has two arguments,

err
and
response
. The first one is only set when the API request has failed, while the second is set when the request was successful. You can write a simple callback implementation to log the result to the console:

function (err, response) {
if (err) {
console.log("ERROR:");
console.log(err);
} else {
console.log("SUCCESS:");
console.log(response);
}
});

Your first Node.js script is ready. Let's go ahead and save it!

Keep in mind that the MessageBird SDK throws an exception when something goes wrong with your API request. It's okay for now, but in production applications you should provide user-friendly error handling and not expose the raw values for

err
and
response
.

Testing

Enough said, let's try running it from the command line:

node send_sms.js

If everything works fine, you should see the API response as output from the script. If you used a live API key and had verified your number or added test credits to your account the message will arrive to your phone in seconds.

Nice work! 🎉

You've just sent your first SMS message with MessageBird's SMS Messaging API using Node.js!

Start building!

Head over to the next MessageBird Developer Tutorial and learn how to set up inbound messaging functionality.

Want to start building your solution but not quite sure how to get started? Feel free to let us know at support@messagebird.com; we'd love to help!

Cookie Settings