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:

__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:

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