Build a “Serverless” SMS Hub in Under 7 Minutes with Node.js, StdLib, and MessageBird

Update: The MessageBird API on Standard Library has been deprecated. Your existing SMS hubs will continue to function, but we recommend using our utils.sms API instead.

With giants such as Uber and Domino’s among their customers, MessageBird has dominated the international programmatic telecommunications market by enabling developers to seamlessly build powerful SMS functionality into their apps.

We at StdLib are now extremely excited to announce an official partnership with MessageBird! The MessageBird API on StdLib allows users to not only send text messages, but set StdLib functions as handlers that trigger in response to incoming SMS messages.

In this guide, we’ll walk through a simple example here of creating a StdLib service that responds to incoming messages. The end result will be fully customizable to support whatever SMS messaging functionality you require. Let’s get started!

What You’ll Need Beforehand

• 1x Command Line Terminal
• A Cell Phone
• 7x Minutes (or 420x Seconds)

Minute 1: Claim Your StdLib Namespace

Start by claiming your StdLib namespace

Getting started with StdLib is easy — head over to our website, choose a username and hit “Claim Namespace”. Your namespace, or username, is where all your services get published. For instance, your SMS handler will be called lib.<username>.messagehub.

In order to deploy services to StdLib, you’ll need to install our open source command line tools. If you don’t have at least Node.js version 8.x installed, you can download the latest version, along with npm, here.

With Node installed, install the StdLib CLI by opening up a terminal and running:

$ npm install lib.cli -g

Note: Even if you’ve previously installed the CLI, you’ll still need to update to the latest version for this tutorial using the above command.

Next, we’re going to create a workspace for your StdLib functions. Create a new folder and initialize it with the following commands:

$ mkdir stdlib-workspace
$ cd stdlib-workspace
$ lib init

Enter the credentials you created earlier.

Minute 2: Initialize MessageBird on StdLib

Next, we’ll get started with MessageBird on StdLib by claiming your first phone number. We’re going to be using a service called messagebird.numbers to interact with MessageBird numbers.

Navigate to the messagebird.numbers service page on StdLib and accept the terms of service by clicking the link underneath the service description.

Click the link under the description to view and accept the terms of service

The same terms of service applies to the other MessageBird functions as well.

After you’ve done that, return to your terminal and call the available function like this:

$ lib messagebird.numbers.available --country <CA or US>

Currently, only Canadian and US numbers are available — choose the appropriate country code based on your location. You should see a list of available, unclaimed telephone numbers.

Choose one from the list, then run:

$ lib messagebird.numbers.initialize --number <chosen phone number>

The initialize function will claim an initial number, and is free.

Once you have successfully initialized MessageBird on StdLib, you can test it by sending a text message with the messagebird.sms.create function. Run the following command from your terminal:

$ lib messagebird.sms.create \
  --recipient <your personal phone number> \
  --body Hello from StdLib!

And you should receive a text message from the number you’ve just claimed!

The messagebird.sms.create function will choose one of your claimed numbers by default, but you can also choose a specific number to send a message from using the originator parameter like this: --originator <your claimed phone number>.

Minute 3: Fork the SMS Handler Sourcecode

Now that you’ve claimed your first MessageBird phone number, we’ll walk you through the process of creating a handler that will respond to incoming SMS messages. From your main StdLib workspace in your terminal, fork the starter sourcecode by running:

$ lib create -s @messagebird/messagehub

You’ll be prompted to give your service a name — you can call it whatever yu want, but the rest of the tutorial will assume you call your service “messagehub”.

The code will appear in the folder <your username>/messagehub. Run $ cd <your username>/messagehub and run $ atom . or something similar to open the directory in your favorite text editor. Your handler service contains three endpoints within the functions directory:

1. __main__.js, the main endpoint of your handler. This function will receive events triggered by incoming SMS messages to your MessageBird number and will call other handlers appropriately
2. messaging/more.js, a handler for incoming messages that contain the word “more” as their sole contents
3. messaging/__notfound__.js, a “not found” handler. If the incoming message can not be mapped to a named function (like more) this handler will be triggered

You can test the outputs of your MessageBird hub for given input messages from your command line by running:

$ lib . --message more

This will route to your messaging/more.js handler, and you’ll see a simulated output of what someone texting your phone number would receive in reply. Try some other messages as well!

Minute 4: Setting Your StdLib Token

Looking through your hub’s code, you may have noticed that the definition of lib contains a process.env.STDLIB_TOKEN environment variable. We’ll have to add this to our service’s env.json file to get our hub working.

First, fetch your StdLib Token from the StdLib Dashboard. You’ll be asked to log in again — once you’ve done so, click on Library Tokens on the left and you’ll see this page:

Click “Show Token” to See Your Library Token

This is your StdLib auth token, click Show token to see its value and copy and paste it to your env.json file under STDLIB_TOKEN for "local" and "dev" environments.

Default contents of the env.json file

Minute 5: Deploying Your Handler

When you’re ready, run the following command from your service directory:

$ lib up dev

This will release your service to a mutable development environment. Your service will be available at https://<username>.api.stdlib.com/messagehub@dev/, but you won’t need to call it directly.

Minute 6: Setting Your Handler

The final step is setting the service you just deployed as a handler. Run the following command from your command line:

$ lib messagebird.handlers.sms.set \
  --number <your previously claimed phone number> \
  --identifier <username>.messagehub[@dev]

You can see a list of your claimed numbers by running $ lib messagebird.numbers.list if you need to see your claimed number again.

Minute 7: Testing Your Hub

To test your new hub, simply send an SMS message to your claimed MessageBird number:

Some sample texts you can send to your new message hub

And that’s it! You now have an SMS message hub built on MessageBird!

Customizing Your Handler

You can customize the handler to run any kind of code you’d like — text back responses from other APIs, use message contents to query a database, forward incoming messages to Slack using Slack’s API — the sky is the limit! Just install whatever npm packages you need and add new handlers within the functions directory with whatever logic you want.

Thanks for reading! For more content, features, and announcements, stay tuned by following us on Twitter @StdLibHQ, MessageBird @messagebird, or me @hacubu. You can also join our Slack channel by going to our homepage and requesting an invite under the “Community” tab. Reach out anytime.

I can’t wait to see what you build!

Jacob Lee is one of the co-founders of StdLib and firm believer in the FaaS future. He’s an east-coast transplant and ex-Googler who loves skiing, playing squash, and traveling. Follow him on Twitter @hacubu!