Sam SlotskyEngineering @ Manifold

If you want to integrate text messaging into an application, there’s a service for that! Till is a fully featured SMS micro service that supports basic text and voice messaging, the ability to conduct surveys via SMS, and a whole lot more.

Today I’ll show you how you can use it in a react-electron application, with a focus on using secure credentials.

Consuming the Till API

Till can be implemented with just a few simple APIs. The first one you’ll want to use is /api/send, which supports both basic messages and questions. Consumers send a POST to this endpoint, and the format of the data payload tells Till whether to send a basic message or a series of questions to a list of phone numbers.

We can build off of the JavaScript fetch API to make these requests, and since we are using Electron we can be free from any type of CORS restrictions, although you may have to explicitly disable webSecurity to make this work.

Embedded content: https://gist.github.com/sslotsky/198a827b79e0faa92608fc8ee30a29a1#file-postdata-js

We can now use our postData function to send messages or questions to /api/send, but first we have to solve authentication.

Till us who you are!

Till authentication is done by supplying api_key and username parameters on the URL’s query string. These are provided to you when you sign up with Till. Thanks to Till’s minimal API surface, building an authenticated URL can consistently be done like this:

Embedded content: https://gist.github.com/sslotsky/42612e614008ef90f239ec383be7f9c9#file-apiurl-js

It’s crucial to keep your API key and username secure, and therefore a good practice to use environment variables. To make this simple you can sign up through Manifold and easily retrieve your secrets using our CLI. More on this later!

We can build on what we have to write a function that submits a simple message to the API:

Embedded content: https://gist.github.com/sslotsky/4a549da13888d11773e9f50b3b1020b7#file-api-js

Let’s test drive this thing with a little user input!

Fantastic Voyage

Building user interfaces with React is a real joyride. Integrating React with Electron and including all your favorite syntax goodies can be frustrating, and might leave you with a couple flat tires and an absence of hope.

I’m using a vastly underappreciated repo by Kitze that brings create-react-app defaults into the picture with zero fuss. Assuming that you have a setup that works for you, from here on out we can just write React code!

With that in mind, I’d like to make a form that requires some text for a message and a valid phone number before I call the API. Here’s a basic implementation of this:

Embedded content: https://codesandbox.io/s/8xwk2v408j?from-embed

Here I’m using the phone library for validating phone numbers, disabling the submit button if anything fails validation, and displaying a formatted phone number in green as soon as the user specifies a valid number. When we submit, it just resets the form. That’s where we can hook in our API:

submit = async e => {
  e.preventDefault();
  await sendMessage([this.state.number], this.state.message);
  this.setState({ number: "", message: "" });
};

For posterity, here’s the complete component:

Embedded content: https://gist.github.com/sslotsky/4312c3f7d2e8c933095b97fe0b42257d#file-newmessageform-js

If you render this form in your React app and enter a valid phone number and a message, you should see something like this:

Till it like it is!Till it like it is!

Click the “Send” button, and if the phone number is your own, you should see this in your text messages:

Till me your secrets!

Pssssst, we need to talk. Remember earlier when I mentioned environment variables? You probably already knew to use them for keeping sensitive info out of your repositories. But I want to tell you about a really good way to keep your secrets safe, share them across teams, and retrieve them automatically.

Into the fold

Manifold is a marketplace for cloud services including Till, and it’s also a great secrets management tool. Check out our Getting started post for the basics!

You can sign up with Till through the Manifold Dashboard and have two credentials automatically generated for you: API_KEY and USERNAME. These can be retrieved through the CLI using manifold export to write them to a local .env file, or by using manifold run in order to set those secrets in your environment variables when you run a process. So let’s see how this fits into our setup.

At this point, assuming that you have a Manifold account and have installed the CLI, you can modify your start script in package.json as follows:

"start": "concurrently \"cross-env BROWSER=none manifold run yarn react-start\" \"wait-on [http://localhost:3000](http://localhost:3000) && electron .\""

The difference from before is the manifold run that occurs before yarn react-start. This is going to set your Manifold secrets into environment variables that are referenced from your React code. But you might notice that there’s one minor problem: the variable names themselves!

Do you remember the environment variables that we were using to construct authenticated URLs? They were called REACTAPP_TILL_USERNAME and REACT_APP_TILL_API_KEY. The create-react-app setup requires us to prefix environment variables with REACT_APP, and adding TILL_ also makes it more clear to me what my keys are used for. But these don’t match the credentials that Till provides for us when we provision, and we can’t change them in the Dashboard. What ever shall we do?

Use an alias

The Manifold CLI has us covered here with a feature called aliasing. For starters, let’s use it to see which resources I have provisioned. Executing manifold list resources reveals that the name of my Till resource is till-macabre-light-brown-cylinder. I can use that to create an alias for any secret that’s associated with that resource.

Embedded content: https://gist.github.com/sslotsky/9f00e9aa8f806fe5451b6d098813850c#file-alias-txt

Now when I run my yarn start command, the execution of manifold run will cause my secrets to be injected into the process under their new names. Now I can access them from any machine or add other developers as members of my Manifold team and share the secrets with them!

Till we meet again

That’s it! For an easy way to try this out yourself, you can clone the repo. Go ahead, make changes and send messages Till your face turns purple!

Creds

Shoutouts to some of the awesome folks who made this possible:

Till
TillYour two-way SMS & Voice Microservice
Try Freearrow_right
Stratus Background
StratusUpdate

Sign up for the Stratus Update newsletter

With our monthly newsletter, we’ll keep you up to date with a curated selection of the latest cloud services, projects and best practices.
Click here to read the latest issue.