Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?


Today we'll use Twilio's Programmable SMS to respond to incoming messages directly from a C++ application running on a ESP8266. When a SMS or MMS is sent to your Twilio number, we'll use ngrok to route a secure connection from Twilio to a route on your ESP8266. We'll then apply some logic on Twilio's request, possibly blink some LEDs, and send a reply using Twilio's markup language TwiML.

Sound difficult? Not a bit, byte, or even a nibble! We'll have you hooked on our webhooks in no time.



Webhooks are user-defined HTTP callbacks. They are usually triggered by some event, such as receiving an SMS message or an incoming phone call. When that event occurs, Twilio makes an HTTP request (usually a POST or a GET) to the URL configured for the webhook.

To handle a webhook, you only need to build a small web application that can accept the HTTP requests. Almost all server-side programming languages offer some framework for you to do this. Examples across languages include ASP.NET MVC for C#, Servlets and Spark for Java, Express for Node.js, Django and Flask for Python, and Rails and Sinatra for Ruby. PHP has its own web app framework built in, although frameworks like Laravel, Symfony and Yii are also popular.

どのフレームワークや言語を選んだにせよ、WebhookはあらゆるTwilioアプリケーションに対して同様に機能します。 これらはTwilioに与えられたURIに対するリクエストを生成します。 アプリケーションはデータベースの読み書き、他のAPIとの統合、あるいは何らかの演算など、必要とされるあらゆる処理を実行し、それからTwilioに実行してほしい指示をTwiMLのレスポンスとしてTwilioに応答します。


TwiML is the Twilio Markup Language, which is just to say that it's an XML document with special tags defined by Twilio to help you build your SMS and voice applications. TwiML is easier shown than explained. Here's some TwiML you might use to respond to an incoming phone call:

<?xml version="1.0" encoding="UTF-8"?>
    <Say>Thanks for calling!</Say>

And here's some TwiML you might use to respond to an incoming SMS message:

<?xml version="1.0" encoding="UTF-8"?>
    <Message>We got your message, thank you!</Message>

すべてのTwiMLドキュメントはルートの<Response>要素と、その中に含まれるひとつ以上の動詞からなります。 動詞とは、電話をかけてきた人にあいさつする<Say>や、受信メッセージへの返信としてSMSを送信する<Message>といったような、Twilioにおこなってほしいアクションのことです。 TwiMLで実行できることがあまねく網羅されたリファレンスについては、TwiML APIリファレンスを参照してください。


There are a number of prerequisites you'll need to keep in mind in order to properly follow this guide. At the heart (or maybe the brain) is the Espressif ESP8266, found on modules as inexpensive as $2. Boasting TLS 1.2 support, it's one of the most budget-friendly parts that can exercise Twilio's APIs securely.

At a minimum for integrating Twilio webhooks, you'll need an ESP8266, a method of programming it, and a way to securely route to the ESP. To follow this particular article, you'll additionally need to ensure you can program your ESP8266 from the Arduino IDE.


If you haven't yet selected a development board, we'd suggest checking the tested board list from the Arduino on ESP8266 Github repository. They don't cover every ESP8266 variation or roll-your-own PCBs, but picking a tested variant is the quickest way to get started.

During the development of this guide, we were using the ESP8266 Thing from Sparkfun. Note that the Thing overloads the DTR pin and may cause trouble with your serial monitor; our code examples use the SoftwareSerial library for debugging. You can disable or enable it by changing the #define USE_SOFTWARE_SERIAL in the .ino file. If your board supports Hardware Serial without hiccups, we'd suggest changing our code to use that instead of a software serial port.

Arduino IDE

Arduino用のESP8266コアでは非常に有用なArduinoライブラリーでESP8266のプログラムを簡単に始められる便利なXtensa gccツールチェインが提供されています。

Although it is beyond the scope of the guide, please let us know any success you have receiving and replying to SMS and MMS messages on the ESP8266 using other toolchains. We'd love to hear your methodology in the comments!


In our Twilio helper libraries we've included code to assist in formulating correct TwiML. Alas, with a part supporting 16 megabytes maximum flash memory with RAM measured in kilobytes, we have to generate our own TwiML from scratch. Don't worry, though - Twilio's markup language is very simple and very powerful.

For this example application, one path will respond to incoming SMS and MMSes with a canned, generic message. In another, we demonstrate very simple (insecure) authentication against a master number, allowing that number to turn on and off the onboard LED on many ESP8266 development boards.

In this code, we receive an incoming text message and immediately prep a response starting with <?xml version=\"1.0\" encoding=\"UTF-8\"?>.

We then decide if a message is from an 'authorized' number, which we defined as matching our master_number variable. If we are authorized and receive a body only containing '0' or '1', we turn off or on the onboard LED and use the <Response> and <Message> tags. An authorized incoming SMS with '?' as the body will respond with instructions and the current status of the LED, again in the <Response> and <Message> tags. Unauthorized requests with any of those three commands will be warned off.

Finally, we respond with application/xml as the MIME type and a status code of 200.

        Manually generating TwiML on the ESP8266.


        Manually generating TwiML on the ESP8266.


        Actually setting up a route on the ESP8266 web server is very simple with the ESP8266WebServer library. At a minimum, you will need to instantiate a ESP8266WebServer object, set up a single route and function to handle requests, and start the server listening. Twilio expects TwiML in response - so once you get the route working properly, you'll want to return TwiML to direct Twilio on how to respond to the incoming message.

        In our code, this line:

        twilio_server.on("/message", handle_message);

        sets up a route at /message, and handle_message is a function pointer to a void function (our implementation is in the Github Repo). When a request is made to /message, that function is called and the ESP8266 goes through the previously dicussed logic to pick a response (and possibly blink the LED!).


              Instantiating an ESP8266WebServer at port 8000, setting up a route with a callback function, starting the ESP8266 server, and handling incoming connections.

              Setting up a Route on the ESP8266 for a Twilio Webhook

              Instantiating an ESP8266WebServer at port 8000, setting up a route with a callback function, starting the ESP8266 server, and handling incoming connections.


              If all went well, you now have a webserver running on the ESP8266 on a friendly network! If you have made it this far, the remainder of your plumbing will be spent outside of the ESP8266.

              First, however, you're going to need to find the webserver. Use whatever means is easiest to find the IP address of the ESP8266 on your local network. If you are hooked up to serial on the board, this might be as easy as looking for the assigned IP address in a message similar to this successful run:

              Connected to WiFi, IP address:
              Connecting to host api.twilio.com
              Certificate fingerprints match.

              While your ESP8266 almost certainly won't be found at, when you do find the IP you can test by visiting it (in a browser) at:

              <YOUR ESP8266'S IP ADDRESS>:8000/message

              and verifying you get an xml response.

              If it works, you're ready to share it with the world and let Twilio know where to find your ESP. But first, we need to find a way to expose it.


              A simple way to test our new ESP8266 server is with ngrok. ngrok makes it very easy to tunnel secure requests to your local network, ensuring that encryption isn't broken until inside your (hopefully) more controllable internal network.

              On a machine which can see the ESP8266 and has ngrok installed, simply run the following command in your choice of terminal (replacing with the IP address of your ESP8266):

              ngrok http

              ... and that's really all you need. You should see ngrok take over your terminal with a nice summary:

              ngrokを使用して、Espressif ESP8266へのリクエストをルーティングする

              Configuring a Messaging Webhook with Twilio

              Now that our ESP8266 is exposed to the world with ngrok, there is only one more step before we can text our $2 piece of silicon for fun and profit.


              Scroll down, and you will see a section to configure webhook URLs for messaging. Simply paste in the secure ngrok URL followed by /message and you'll be good to go:


              After that, you're cooking with Twilio. Try texting '0', '1', '?' and whatever else you desire from the master_number and other numbers and see what you get. That's really all it takes to hook up your ESP8266 device with Twilio!

              予備のWebhook URL

              You'll note there is an optional 'Primary Handler Fails' field. In your final application, you will likely want to add a secondary endpoint for Twilio to fall back on if the ESP8266 is unreachable, so you can handle the logic for when it comes back online.

              Simply add a URL to that field and Twilio will failover automatically on an error code or if the primary webhook doesn't respond within 15 seconds. Refer to our Availability and Reliability guide for more details on the fallback URL.

              Protect your webhooks

              Twilio supports HTTP Basic and Digest Authentication. Authentication allows you to password protect your TwiML URLs on your web server so that only you and Twilio can access them.

              Learn more about HTTP authentication here.

              メディア付きの応答を返す (MMSメッセージ - 日本未対応)

              To send an MMS, it's as simple as adding a new tag to the TwiML with a <Media> tag. You can include up to 10 individual media tags in a response.

              これは本記事の範囲外の話題になりますが、これによって受信メッセージへの返信としてESP8266にホストされた(または動的に生成された)画像を送り返すことができることになります - 素晴らしい!

              Add-on でメッセージを拡張する

              メッセージを送る電話番号についての情報がもっと必要ですか? メッセージそのものの持つ感情や他のデータのために、分析が必要ですか?  Add-onマーケットプレイスで利用できるAdd-onなら、こうしたこと、またはそれ以上のことも実現できます。


              Who Needs More than 64 kB of RAM, Let Alone 640 kB?

              Between this article and our article on how to send SMS and MMS messages from an ESP8266, we've covered how to handle incoming and outgoing messages with the Espressif ESP8266 and the Twilio API. Now you can deploy your web apps to environments servers couldn't previously go.

              The next step is up to you. Use Twilio and your imagination to set up a security, home automation, or remote monitoring app - we'd love to hear what you build! Contact us on Twitter with a link to your next big Thing.

              Paul Kamp Samuel Mendes David Prothero Kat King
              Rate this page:


              We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.