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
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
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.
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>
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!
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
__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
messaging/more.js, a handler for incoming messages that contain the word “more” as their sole contents
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:
This is your StdLib auth token, click Show token to see its value and copy and paste it to your
env.json file under
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> \
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:
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!