Overview

When COVID hit, we wanted to find a way to better reach and serve our community after going digital. We had an idea to setup a text number service where people could text a number with a keyword and get all the up-to-date information they need. This idea turned into a weekend project, which turned into a 30 minute project from start to finish. This ended up being the project that I worked on and setup. Outside of serving at City Church, I'm a Software Engineer at a large company and work with these types of services everyday. We understand everyone doesn't, so we wanted to make all the resources available so almost anyone could set up their own text number service, specific to them at almost no cost.

How does it work?

There are a large number of services that exist that do this already, but they either cost too much money or can be overkill for what we wanted to do. Since I'm a software engineer, I knew I could build something that fit our need with little cost, highly customizable, and quickly.

We use a few online services to make this happen. The first one is Twilio, which gives us a number and handles the receiving/sending of SMS messages. First, we signed up for an account, bought a number (local to our area), and we were off to the races. We will dig into more later how to setup this account and how much it cost.

While Twilio gives us a number and handles the incoming/outgoing SMS messages, it doesn't have any logic on how to handle what each keyword means and how to reply. Twilio lets you setup what are called webhooks. All this means is, when Twilio gets a message it needs to go somewhere tell it what the message is and wait to see how to reply. To do this, we use Amazon Web Services and a service they offer called AWS Lambda.

I know I'm starting to get technical, but we will land the plane. We did all the heavy lifting for you, so you should just hav to follow the steps below. While it is a fairly simple setup process, if you have someone on your staff who is technical, they would probably be the best person to setup this service.

Pricing

Twilio will be the majority of your pricing, but still very small. You have to pay for the phone number and then each SMS message, both incoming and outgoing. The phone number costs a total of $1.00 a month and then $0.0075 for each incoming or outgoing message (that's not a typo, it's less then a penny!).

So to run some quick examples, let's say you have 1 number and get a total of 250 messages from people. Since we have 250 incoming, we will probably have 250 outgoing (you got to respond!). So this comes to a total of $1.00 + (250 * 0.0075) + (250 * 0.0075) = $4.75.

Amazon Web Services pricing is even less, even sometimes free! With each AWS account, you get a "free tier" of resources for 12 months, which the project will mostly likely stay in. For AWS Lmabda you get a total of 1 million requests a month. So let's just assume that's free. You also need to use API Gateway to let your Lambda function be available on the internet. You also get a total of 1 million requests a month for free. For the sake of this project, a request is going to be each time someone texts your number. So unless you expect to get over 1 million requests a month, you aren't going to pay a dime.

You might want to keep this service available after the 12 months, but the pricing doesn't immediately skyrocket. With AWS Lambda you are only charged for how many "seconds" your application runs. Most of the requests to process your text message, will actually be less then a second. How much does each second cost? Only $0.00001667... Again not a typo, that's a real cost point. It's so low in fact, that the examples on their webside start at a minimum of 30 million request and that comes to a total of... $5.83 cents...

So far between both services, we are looking at under 5 dollars a month for 250 incoming messages. $1.00 of that being just for the number, meaning as you grow, the cost grows slower. So for basically the cost of a cup of coffee from our wonderful friends at Storied Coffee, I can provide a valuable service to my church or organization. Perfect!

Ok, I get it. It's great. How do I set it up?

To setup, we'll do the AWS Lambda side first. We need the URL it generates after we create it for Twilio.

First, either create an account or login to an existing one. I assume for most people, you have to create a new one. This shouldn't take long and even though it might ask for a credit card, know that if you follow the guidelines here it should never be charged (with that said, I'm not responsible for any unexpected bill charges, sorry). After creating an account and logging in, you will want to search and open "Lambda".

You will then be brought to the Lambda dashboard. You might see a welcome or get started screen, or be brought right into your functions. Either way, you are going to want to look for a button that says "Creat Function" and click it.

Fill in a name for your function and then make sure the "Runtime" is set to "Node.js 12.x" (should be selected by default). Then click "Create Function".

Might take a little bit, but once the function is created, you should be brought to a screen that looks like this.

If you see something like this screen, perfect! We just need to do a few more things and then it's over to Twilio to get your number!

From this screen, you are going to click "Add Trigger". This is how we connect the API Gateway and get a URL for your service. After hitting "Add Trigger" select "AWS Gateway" from the dropdown and fill it out similar to how I have it below, again changing the name to whatever you would like. When complete, go ahead and click "Add". This again, might take a minute.

After it's created, you should see something similar to what's below. Under the new trigger, you should see a URL listed next to "API endpoint". Copy this and save it for later! This is the URL we will use when we setup Twilio. To make sure it works, open a new tab/window and try to go to it. If working correctly, you should see "Hello from Lambda!". It might take up to 30 seconds for it to work, so if it doesn't work the first time, wait a minute and try again.

Next, click the function name at the top (the one with the orange icon) to go back to the first screen. Scroll down a little bit and you should see a section for "Function Code". This is how it knew to return "Hello from Lambda!" before. We are going to replace this with the the code in this file. If you look at it, it might be confusing, but you should be able to see the keywords that we have setup at City Church. Some of these include "new", "jesus", "groups", etc. Each keyword has a "message" that we associate with it. The "message" is what will be sent back to the user! So if I text my number "groups", it will find that keyword and then send the "message" that I wrote back to the user. What you are going to do first, is copy this code and replace all the code in "Function Code". It should then look something like this.

To make it specific to your church or organization, we are going to want to edit what is inbetween the " " after the word "message. Don't be scared if you've never programmed before, this is just typing sentences! If you want to use the existing keywords, then just replace the working and/or the links to our website with yours. If you want different case words, replace ours with what you want! The definition case "new" means that a keyword option is "new". If you want to change this to maybe "first time", then you would make it case "first time". Now you have your own keyword! The important thing with keywords is that they all have to be lowercase. The user texting can text whatever case they want (iNcLudInG tHiS), but we check again lowercasing. After you make the changes you want, Just hit the "Save" button in the upper right and you're done! If you ever want to add more keywords or change a message, you will come back to this function and just edit the "Function Code" section again. You do not need to go through all the steps, just this section.

Now that our AWS account is created, our lambda function is running, and our messages are written, we should get a number so people can start using it. Head over to Twilio and create an account.
After creating an account, go the Twilio Console and from the left menu, go to "Phone Numbers". We are first going to buy a number.

You should then see the following screen (or something similar). Click the big red "+" icon at the top to buy a number.

From there, go ahead and use their search tool to pick whatever number you want. The only requirement is that under "CAPABILITIES" you select "SMS". This is a required feature that your number needs to be sure it can receive and send text messages.

After you buy the number, open the menu on the left again and select "Programmable SMS". We now just need to attach the number to your Lambda function.

From there, select "SMS" -> "Messaging Services". Here is where you will take your number and attach the URL from before. Click the blue "+" icon, enter a "Name", select "Marketing,2-way" for your "Use Case" and then hit "Create".


From there, you need to change "Inbound Settings" to be "Send an Incoming Message Webhook". This will give you an option for "Request URL" and "Fallback URL". Take the URL you saved from before and put it in both fields. When done, hit "Save".

And... that's it! Go ahead and try to text your number. If might take a little bit to reply on the first attempt, but you should get a custom response from one of your keywords! Congrats!

In Closing

Let's recap what we did. We setup a new AWS and Twilio account, create a new Lambda function with our own code for messages and keywords, bought our own number and got it to communite withour function. Amazing! Give yourself a pat on the back!

Unless you plan on adding more keywords, messages or changing links you should never have to touch this again. Twilio will keep working as long as their is money in your account and AWS will forever keep running. You should also make it a habbit to check on billing every so often, but you shouldn't have to run any of the setup steps again.

If you had issues setting this up, we would love to help. You can comment below or email myself at [email protected] and I would love to help!

In the same, if you got it to work and have people using it, let us know! We would love to see how you are using these tools to better reach your church or organization.