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:



              Twilioは通常のWebブラウザー同様、application/x-www-form-urlencoded形式でHTTPリクエストをユーザーのアプリケーションに送信します。 (Twilioが)このリクエストにパラメーターと値を含めることで、Twilioはユーザーのアプリケーションにデータを送信し、これを使用してレスポンスの前に処理を行うことができます。

              You can configure the URLs and HTTP Methods Twilio uses to make its requests via your account portal or using the REST API.

              Note that Twilio cannot cache POSTs. If you want Twilio to cache static TwiML pages, then have Twilio make requests to your application using GET.

              When Twilio receives a message for one of your Twilio numbers or Channels, it makes a synchronous HTTP request to the message URL configured for that number or Channel and expects to receive TwiML in response.



              パラメーター 説明
              Message SID このメッセージの 34 文字のユニークな識別子です。 後で REST API を使ってこのメッセージを取得する時に使えます。
              SmsSid MessageSidと同様の値。廃止される予定、後方互換のために用意されています。
              AccountSid このメッセージに関連付けられた アカウント の、34 文字の ID です。
              MessagingServiceSid The 34 character id of the Messaging Service associated with the message.
              From このメッセージの送信された電話番号またはChannelアドレスです。
              To 受信者の電話番号またはChannelアドレスです。
              Body テキストの本文メッセージ。最大1600文字までです。
              NumMedia メッセージに関連付けられたメディアアイテムの数です。


              パラメーター 説明
              MediaContentType{N} MediaUrl{N}に保存されたメディアのContentTypesです。 MediaContentType{N}の順番は、MediaUrl{N}の順番と一致します。 MediaContentType{N}が使用されるのではなく、NumMediaによって複数のメディア要素が含まれている場合、Nはメディアの0で始まるインデックス値となります(たとえば、MediaContentType0となります)。
              MediaUrl{N} メッセージで受信されたメディアの内容を参照するURLです。 MediaContentType{N}が使用されるのではなく、NumMediaによって複数のメディア要素が含まれている場合、Nはメディアの0で始まるインデックス値となります(たとえば、MediaUrl0となります。)

              Twilioは From と To の電話番号から、場所の検索も行います。 次のパラメーターが存在する場合、Twlilio はこれらのパラメーターを送信します。

              パラメーター 説明
              FromCity 送信者の都市名です。
              FromState 送信者の州名です。
              FromZip 送信者の郵便番号です。
              FromCountry 送信者の国名です。
              ToCity 相手の都市名です。
              ToState 相手の州名です。
              ToZip 相手の郵便番号です。
              ToCountry 相手の国名です。

              For status callbacks, Twilio also sends status-related parameters:

              パラメーター 説明
              MessageStatus The status of the message. Can be: accepted, queued, sending, sent, failed, delivered, undelivered, receiving, received, or read (WhatsApp only). For more information, see detailed descriptions.
              SmsStatus Same as MessageStatus value. Deprecated and included for backward compatibility.



              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.

              インタープリターはTwiMLドキュメントを上から下に見て動詞を順番に実行します。例として下記のTwiMLメッセージはhttps://demo.twilio.com/sms/welcomeにコントロールをリダイレクトする前に"Hello World" を送信者に返信します。

              <?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.



              誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。



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

                    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