TwiML™ for Programmable SMS


TwiML (the Twilio Markup Language) is a set of instructions you can use to tell Twilio what to do when you receive an incoming call, SMS, or fax.

TwiML can be generated using one of the Twilio Language Helper Libraries, or written manually to instruct Twilio on what actions to take in response to various SMS related events.

Not sending messages? TwiML powers more than just Twilio Programmable SMS – check out the documentation on how to use TwiML with Programmable Voice and Programmable Fax.

A basic TwiML SMS response example

The following manual TwiML will instruct Twilio to respond to an incoming SMS with a "Hello World!" reply:

<?xml version="1.0" encoding="UTF-8"?>
    <Message><Body>Hello World!</Body></Message>

The same TwiML can also be generated using the examples in these following code samples. The redirect control allows you to point at another TwiML file from your current file.

Toggle between the code in your language of choice and TwiML in the top bar of the code viewer:


        Building an SMS Application? Our SMS Quickstarts will show you how to send, receive, and reply with SMS using your choice of web language.



        For example, here's code demonstrating how to send two unique messages one after the other using helper libraries. Select your choice of language to see how it's done:



              When a message arrives at your Twilio phone number, Twilio sends a request to your web application--just like a web browser--using the webhook URL that you've specified. For more information about Twilio's request, including the parameters sent to your application, please see our guide to Twilio's Request to your Webhook URL.



              All phone numbers in requests from Twilio are in E.164 format if possible. For example, (415) 555-4345 would come through as '+14155554345'. However, there are occasionally cases where Twilio cannot normalize an incoming caller ID to E.164. In these situations, Twilio will report the raw caller ID string.


              Twilio からのリクエストに含まれるすべての日付と時刻には、 RFC 2822 フォーマットの GMT 時間が使用されます。 たとえば、2010 年 8 月 19 日午後 6 時 13 分 (太平洋夏時間) は、「Fri, 20 Aug 2010 01:13:42 +0000」となります。



              Opt out keywords are passed to your application to notify you that a user has opted out. All future messages to the user will result in an error. 'Start' and 'Yes' keywords will also be passed to your application and to opt users back in.


              パラメーター 説明
              OptOutType String indicateing whether the message is a STOP, HELP, or START message.



              そのリクエストへのレスポンスとして、Twilioに対してメッセージへの応答としてどんなことを行うのか伝えることができます。 番号のURLはこちらで構成できます。


              Twilio は通常のウェブ ブラウザと同じように振る舞いますので、新しいことを覚える必要はありません。

              • Cookie: 通常のWebブラウザーと同様、TwilioはHTTP Cookieを受け入れ、これらを (Twilioからの) 各リクエストに追加します。
              • リダイレクト: こちらも通常のWebブラウザーと同様、HTTPリダイレクト (HTTPステータスコード301、307、など) に従います。
              • キャッシュ: こちらも通常のWebブラウザーと同様、HTTPヘッダーで許可されており (ETagおよびLast-Modifiedヘッダー) 、かつHTTPメソッドがGETである場合、Twilioはファイルのキャッシュを行います。


              Twilio は、2 つの電話番号の間でやり取りされる複数の SMS をまたいで cookie の状態を保持します。 このため、複数のメッセージを 1 つの会話として扱うことができ、その会話のセッション識別子などのデータを cookie に格納して、後で使用できます。 この会話の cookie は、4 時間使用しないと期限切れになります。

              MIME Type に対応

              Twilio はユーザー アプリケーションのレスポンスの MIME Type に応じて異なる動作をします。

              MIME Type 動作
              text/xml, application/xml, text/html Twilioは返されたドキュメントをTwiML XMLの命令セットとして解釈します。 これはもっとも一般的に使用されるレスポンスです。
              text/plain Twilioはメッセージ中にある送信者にテキストファイルの内容を返します。


              When your application responds to a Twilio request with XML, Twilio runs your document through the TwiML interpreter. To keep things simple, the TwiML interpreter only understands a few specially-named XML elements. In TwiML parlance, these are divided into three groups: the root <Response> element, "verbs" and "nouns." We discuss each group below.

              The interpreter starts at the top of your TwiML document and executes instructions ("verbs") in order from top to bottom. As an example, the following TwiML Message snippet sends "Hello World" as a message reply to the sender before redirecting control to the TwiML at https://demo.twilio.com/welcome/sms.

              <?xml version="1.0" encoding="UTF-8" ?>
                  <Message>Hello World!</Message>

              1 つの TwiML 文書に複数の <Message> 動詞を挿入して、複数のメッセージを送信できます。 たとえば、

              <?xml version="1.0" encoding="UTF-8" ?>
                  <Message>This is message 1 of 2.</Message>
                  <Message>This is message 2 of 2.</Message>


              <Response> 要素

              <Response> 要素は、Twilio の XML マークアップのルート要素です。 Twilio のリクエストに対する TwiML レスポンスでは、必ずすべての動詞をこの要素の中にネストします。 それ以外の構造は無効となります。

              <?xml version="1.0" encoding="UTF-8"?>
                  <Message>I'm hungry!</Message>




              制御フローが他のドキュメントに渡されるために、TwiMLドキュメントの一部の動詞に到達できない特定のケースがあります。 これは通常、動詞の「action」属性が設定されている場合に起こります。

              For example, if a <Message> is followed by a <Redirect>, the <Redirect> is unreachable if the <Message> verb's 'action' URL is set. In this case, SMS session flow continues with the TwiML received in your response to the 'action' URL request.

              制御フローに関係する動詞は、 <Message><Redirect> です。


              A Noun in TwiML is anything nested inside a verb that is not itself a verb. It's whatever the verb is acting on. This is usually just text. But sometimes, as in the case of <Message> with its <Media> and <Body> nouns, there are nested XML elements that are nouns.


              You can use status callbacks to have Twilio reach out to your app when the status of a message has changed.

              Status callbacks do not control application flow, so TwiML does not need to be returned; however, it's recommended that you respond to status callbacks with either a 204 No Content or a 200 OK with Content-Type: text/xml and an empty <Response/> in the body. Failure to respond properly will result in warnings in Debugger.



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



                    Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                    Sending your feedback...
                    🎉 Thank you for your feedback!
                    Something went wrong. Please try again.

                    Thanks for your feedback!

                    Refer us and get $10 in 3 simple steps!


                    Get link

                    Get a free personal referral link here


                    Give $10

                    Your user signs up and upgrade using link


                    Get $10

                    1,250 free SMSes
                    OR 1,000 free voice mins
                    OR 12,000 chats
                    OR more