Messageリソース
A Message resource represents an inbound or outbound message. Twilio creates a Message when any of the following occur:
- You send an SMS, WhatsApp, or Channels message via the REST API
- You use the <Message> verb in TwiML
- You originate a message from a Programmable Wireless SIM
- Someone sends a message to one of your Twilio numbers
With this REST API, you can:
Are you looking for step-by-step instructions for sending your first SMS with Twilio using the helper libraries? Check out one of our SMS quickstarts in your programming language of choice: C#/.NET, Java, Node.js, PHP, Python, or Ruby.
Or, if you're looking to get up and running with the Twilio API for WhatsApp Quickstart: C#/.NET, Java, Node.js, PHP, Python, or Ruby.
Message properties
| Resource Properties in REST API format | |
|---|---|
body
|
The message text. Can be up to 1,600 characters long. |
num_segments
|
The number of segments that make up the complete message. A message body that is too large to be sent in a single SMS message is segmented and charged as multiple messages. Inbound messages over 160 characters are reassembled when the message is received. Note: When using a Messaging Service to send messages, |
direction
|
The direction of the message. Can be: |
from
|
The phone number (in E.164 format), alphanumeric sender ID, or Wireless SIM that initiated the message. For incoming messages, this will be the number of the sending phone. For outgoing messages, this value will be one of your Twilio phone numbers or the alphanumeric sender ID used. |
to
|
The phone number in E.164 format that received the message. For incoming messages, this will be one of your Twilio phone numbers. For outgoing messages, this will be the sending phone. |
date_updated
|
The date and time in GMT that the resource was last updated specified in RFC 2822 format. |
price
|
The amount billed for the message, in the currency specified by |
error_message
|
The description of the |
uri
|
The URI of the resource, relative to |
account_sid
|
The SID of the Account that sent the message that created the resource. |
num_media
|
The number of media files associated with the message. A message can send up to 10 media files. |
status
|
The status of the message. Can be: |
messaging_service_sid
|
The SID of the Messaging Service used with the message. The value is null if a Messaging Service was not used. |
sid
|
The unique string that that we created to identify the Message resource. |
date_sent
|
The date and time in GMT that the resource was sent specified in RFC 2822 format. For outgoing messages, this is when we sent the message. For incoming messages, this is when we made the HTTP request to your application. |
date_created
|
The date and time in GMT that the resource was created specified in RFC 2822 format. |
error_code
|
The error code returned if your message |
price_unit
|
|
api_version
|
The API version used to process the message. |
subresource_uris
|
A list of related resources identified by their URIs relative to |
Create a Message resource
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json
To send a new outgoing message, make an HTTP POST to this Messages list resource URI.
If you want to send messages while in trial mode, you must first verify your 'To' phone number with Twilio. You can verify your phone number by adding it to your Verified Caller IDs in the console.
When creating a new message via the API, you must include the To parameter. This value should be either a destination phone number or a Channel address. You also need to pass a Body or MediaUrl containing the message's content.
A WhatsApp media message can only contain one media object. Additional MediaURL parameters will be ignored.
You must also include either the From parameter or MessagingServiceSid parameter. You may use MessagingServiceSid if sending your message with a messaging service. Alternatively, you can choose a specific number in a messaging service to set as the From.
There is a slight difference in how Twilio's API responds based on the parameter you include:
From: Twilio will validate the phone numbers or Channel addresses synchronously. The API returns either aqueuedstatus or an error.MessagingServiceSid: the API will first return a status ofaccepted. Twilio then determines the optimalFromphone number. Any delivery errors will be sent asynchronously to your StatusCallback URL.
パラメーター
| Parameters in REST API format | |
|---|---|
account_sid
Path
|
The SID of the Account that will create the resource. |
to
必須
|
The destination phone number in E.164 format for SMS/MMS or Channel user address for other 3rd-party channels. |
status_callback
オプション
|
The URL we should call using the |
application_sid
オプション
|
The SID of the application that should receive message status. We POST a |
max_price
オプション
|
The maximum total price in US dollars that you will pay for the message to be delivered. Can be a decimal value that has up to 4 decimal places. All messages are queued for delivery and the message cost is checked before the message is sent. If the cost exceeds |
provide_feedback
オプション
|
Whether to confirm delivery of the message. Set this value to |
attempt
オプション
|
Total number of attempts made ( including this ) to send out the message regardless of the provider used |
validity_period
オプション
|
How long in seconds the message can remain in our outgoing message queue. After this period elapses, the message fails and we call your status callback. Can be between 1 and the default value of 14,400 seconds. After a message has been accepted by a carrier, however, we cannot guarantee that the message will not be queued after this period. We recommend that this value be at least 5 seconds. |
force_delivery
オプション
|
Reserved |
content_retention
オプション
|
Determines if the message content can be stored or redacted based on privacy settings |
address_retention
オプション
|
Determines if the address can be stored or obfuscated based on privacy settings |
smart_encoded
オプション
|
Whether to detect Unicode characters that have a similar GSM-7 character and replace them. Can be: |
persistent_action
オプション
|
Rich actions for Channels Messages. |
schedule_type
オプション
|
Indicates your intent to schedule a message. Pass the value |
send_at
オプション
|
The time that Twilio will send the message. Must be in ISO 8601 format. |
send_as_mms
オプション
|
If set to True, Twilio will deliver the message as a single MMS message, regardless of the presence of media. |
from
Required if messaging_service_sid is not passed
|
A Twilio phone number in E.164 format, an alphanumeric sender ID, or a Channel Endpoint address that is enabled for the type of message you want to send. Phone numbers or short codes purchased from Twilio also work here. You cannot, for example, spoof messages from a private cell phone number. If you are using |
messaging_service_sid
Required if from is not passed
|
The SID of the Messaging Service you want to associate with the Message. Set this parameter to use the Messaging Service Settings and Copilot Features you have configured and leave the |
body
Required if media_url is not passed
|
The text of the message you want to send. Can be up to 1,600 characters in length. |
media_url
Required if body is not passed
|
The URL of the media to send with the message. The media can be of type |
例 1
例 2
例 3
A note on message rate limiting
As you send more messages via the API, Twilio will queue them up for delivery at your prescribed rate limit. API requests for messages that exceed the specified rates will be queued and executed as capacity is available.
If your application tries to enqueue more than 4 hours worth of outbound traffic (e.g., enqueuing more than 14,400 messages to Canada over one long code phone number), the API will start returning 429 errors.
If you need to enqueue a large volume of messages, you may find that it's helpful to leverage Twilio's Messaging Services. See our guide on how to set up and send messages from a messaging service in your language of choice for more tips.
Schedule a Message resource
Note: Message Scheduling is currently in public beta.
If you'd like to cancel scheduled messages, navigate to the Cancel a Scheduled Message section to learn more.
Message scheduling functionality gives you the ability to schedule an SMS, MMS or WhatsApp message for a fixed time in the future.
POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json
To schedule a new outgoing message, make an HTTP POST to the Messages list resource URI shown above with the following two required parameters:
ScheduleType: This parameter indicates your intent to schedule a message. You should pass the value "fixed" to schedule a message to be sent at a fixed time.SendAt: This parameter indicates when Twilio will send a message. Your datetime should be in ISO-8601 format.
In addition to the two scheduling parameters, you must still include the regular parameters to send a message as described in the Create a Message Resource section: To, Body, MediaUrl (if sending an MMS), and MessageServiceSid (you can pass the MessagingServiceSid in either the MessagingServiceSid parameter or the From parameter).
Important Considerations for the Message Scheduling Beta Release
For the full list of Message Scheduling beta limitations, please see the Message Scheduling FAQ support article. If any of these limitations are blockers, please reach out to us via support@twilio.com:
Please note that message scheduling will have the following soft limitations at launch:
- Message Scheduling will only be accessible on Messaging Services. You need to pass a
MessageServiceSidinstead of aFromPhone Number in order to schedule messages. If you pass aFromPhone number, the scheduling parameters will be dropped from the API request and the message will be sent immediately. - A message must be scheduled at least 15 min in advance of message send time and cannot be scheduled more than 7 days in advance of the request.
- If you plan to use message scheduling at scale, please review all the beta limitations in the support article.
例 4
Note: There is no status callback event for the scheduled status. You can continue to receive existing callback events by including the optional StatusCallBack parameter in the message request.
Response Status Codes
Valid Parameters: An HTTP 201 (scheduled) will be returned in the synchronous API response when your request parameters are valid. When a message is scheduled, you will see scheduled instead of accepted.
Invalid Parameters: An HTTP 400 code will be returned in the API response when your request parameters are invalid.
例 5
例 6
Note: Ensure that your approved WhatsApp sender is added to the number pool of your Messaging Service you intend to use for scheduling a WhatsApp message.
WhatsApp requires that business-initiated notifications sent by your application be templated and pre-registered, with the exception of messages sent as a reply to a user-initiated message. (See Conversational Messaging on WhatsApp for more details).
When scheduling a WhatsApp message, the check for pre-registered templates will only be done at the time of sending the message and not at the time of scheduling the message. If your message does not adhere to the pre-approved WhatsApp templates in your account, the message will be scheduled and fail at send time.
Canceling Scheduled Messages
Once a message is scheduled, you can cancel it from being sent. See the "Cancel a Scheduled Message" section to learn how to cancel scheduled messages.
Fetch a Message resource
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json
Returns a single message specified by the provided Message {SID}.
パラメーター
| Parameters in REST API format | |
|---|---|
account_sid
Path
|
The SID of the Account that created the Message resource to fetch. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Message resource to fetch. |
例 1
Read multiple Message resources
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json
Returns a list of messages associated with your account. If you are using the Twilio REST API or the Twilio-CLI, the list includes paging information. If you use one of Twilio's Server-Side Helper Libraries, paging happens under the hood.
When getting the list of all messages, results will be sorted on the DateSent field with the most recent messages appearing first.
If you are using the Twilio REST API and plan on requesting more records than will fit on a single page, you may want to use the provided nextpageuri. This method ensures that your next request picks up where it left off and can prevent you from retrieving duplicate data if you are actively sending or receiving messages.
This is not necessary if you are using a Twilio Helper Library, which will automatically handle paging. Take a look at the Helper Library documentation for more information.
You may also filter the list by providing the following query string parameters to the listing resource:
パラメーター
| Parameters in REST API format | |
|---|---|
account_sid
Path
|
The SID of the Account that created the Message resources to read. |
to
オプション
|
Read messages sent to only this phone number. |
from
オプション
|
Read messages sent from only this phone number or alphanumeric sender ID. |
date_sent
オプション
|
The date of the messages to show. Specify a date as |
例 1
例 2
例 3
例 4
Update a Message resource
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json
Updates the body of a Message resource.
This action is primarily used to redact messages: to do so, POST to the above URI and set the Body parameter as an empty string: "". This will allow you to effectively redact the text of a message while keeping the other message resource properties intact.
パラメーター
| Parameters in REST API format | |
|---|---|
account_sid
Path
|
The SID of the Account that created the Message resources to update. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Message resource to update. |
body
オプション
|
The text of the message you want to send. Can be up to 1,600 characters long. |
status
オプション
|
When set as |
例 1
Cancel a Scheduled Message
Before you use this functionality:
- Ensure the status value of canceled is spelled with one "l", (canceled) and not two (cancelled).
- Ensure that you store the
MessageSidof the messages you schedule. You need to reference theMessageSidfor each message cancelation request - There is no bulk cancelation. If you’d like to cancel multiple messages, you must send in a cancelation request for each message and reference the
MessageSid. - There is a new status callback event for "Canceled". You can continue to receive existing callback events by including the optional StatusCallBack parameter in the message request.
Note: We make the best attempt to cancel a scheduled message when we receive your request. A message cannot be canceled once it has reached a finalized state.
例 2
Delete a Message resource
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json
メッセージの記録をアカウントから削除します。
レコードが削除されるとAPIおよびアカウントポータルに表示されなくなります。
成功すると、Bodyのない HTTP 204 (No Content) を返します。
Attempting to delete an in-progress message record will result in an error.
パラメーター
| Parameters in REST API format | |
|---|---|
account_sid
Path
|
The SID of the Account that created the Message resources to delete. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Message resource to delete. |
Note: Deleting a message will also delete any media associated with the message, unless the same media object is associated with another message on your account that has not been deleted. For example, if you sent 1000 media messages with the same media attachment, that media object would remain accessible until the 1000 message records associated with it were deleted.
例 1
Message Media Subresources
Mediaリストサブリソース
Message instance resources have a Media list resource for the set of media elements included with a given Message:
/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}/Media
Mediaインスタンスサブリソース
Message instance resources have Media instance subresources. If media exists on a given message, you can retrieve information about images and other media.
/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}/Media/{MediaSid}
Appendix
メッセージステータス値
The following are the possible values for the 'Status' parameter:
| Status | 概要 |
|---|---|
| accepted | Twilio has received your API request to send a message with a Messaging Service and a From number is being dynamically selected. This will be the initial status when sending with a Messaging Service and the From parameter. |
| scheduled | The message is scheduled to be sent. This will be the initial status when scheduling a message with a Messaging Service |
| queued | The API request to send a message was successful and the message is queued to be sent out. This will be the initial status when you are not using a Messaging Service |
| sending | Twilioはネットワークで一番近いキャリアにメッセージを送信中です。 |
| sent | The nearest upstream carrier accepted the message. |
| receiving | インバウンドメッセージがTwilioで受信され、現在処理中です。 |
| received | 受信メッセージ専用です。 いずれかのTwilio番号でメッセージが受信されました。 |
| delivered | Twilioは上位キャリアーからのメッセージ送達確認（利用可能な場合は宛先の電話機への送達確認）を受信しました。 |
| undelivered | Twilio has received a delivery receipt indicating that the message was not delivered. This can happen for many reasons including carrier content filtering and the availability of the destination handset. |
| failed | メッセージが送信できませんでした。 これはキューのオーバーフロー、アカウントの停止、およびメディアのエラー（MMSの場合）を含むさまざまな理由で起こりえます。 failedのメッセージに対してはTwilioによる課金は行われません。 |
| read | On WhatsApp messages only. The message has been delivered and opened by the recipient in the conversation. The recipient must have enabled read receipts. |
| canceled | (Beta feature) The message has been canceled. This status is only accessible when using a Messaging Service |
Minimum library values that support "READ" receipts for WhatsApp messages
- C#: 5.30.0
- Java: 7.39.0
- Node: 3.32.0
- PHP: 5.33.0
- Python: 6.28.0
- Ruby: 5.24.0
Back to the Message properties list.
配信関連のエラー
When a message's status is 'failed' or 'undelivered', the ErrorCode and ErrorMessage properties will contain one of the following.
Note that the ErrorMessage is meant to be a human-readable description – the values returned are subject to change in the future. A full list of Twilio Error Codes and troubleshooting tips can help you troubleshoot delivery issues.
| エラー コード | エラーメッセージ | 概要 |
|---|---|---|
| 30001 | キューオーバーフロー | You tried to send too many messages too quickly, and your message queue overflowed. Try sending your message again after waiting for some time. |
| 30002 | アカウントサスペンド | メッセージ送信と配送の間にあなたのアカウントがサスペンド状態になりました。 Twilioにご連絡をお願い致します。 |
| 30003 | 到達できない電話機 | 送信先の電話機の電源がオフになっているか、無効な電話機です。 |
| 30004 | メッセージがブロックされました | The destination number you are trying to reach is blocked from receiving this message (e.g., due to blacklisting). |
| 30005 | 不明な到達先電話機 | あなたが送信しようとしている先の番号は不明か、すでに存在していません。 |
| 30006 | 固定電話回線もしくはキャリアに到達不可 | この番号はメッセージの受信ができません。 考えられる原因は、固定電話回線もしくは、ショートコード、到達できないキャリアです。 |
| 30007 | キャリア違反 | Your message was flagged as objectionable by the carrier. To protect their subscribers, many carriers have implemented content or spam filtering. Learn more about carrier filtering |
| 30008 | 不明なエラー | いずれのカテゴリーにも属さないエラーです。 |
| 30009 | 失われたセグメント | マルチパートの受信メッセージに関連づけられたひとつ以上のセグメントが受信されませんでした。 |
| 30010 | メッセージの金額が設定した最大理金額を超えました。 | メッセージの料金が、max priceパラメータの値を超えました。 |
The following ErrorCodes apply only when you are sending a message via WhatsApp or a Channel.
| ErrorCode | ErrorMessage | 概要 |
|---|---|---|
| 63001 | Channelがリクエストを認証できませんでした | Channelの認証クレデンシャルが不正です。 Console内のChannelページでクレデンシャルを確認するか、Channelとの再認証を行なってください。 |
| 63002 | ChannelがFromアドレスを見つけられませんでした。 | Fromアドレスが構成済みのChannelと一致しませんでした。 Channelページから、正しいChannelエンドポイントアドレスを使用していることを確認してください。 |
| 63003 | ChannelがFromアドレスを見つけられませんでした | Toアドレスが不正です。 |
| 63005 | Channelが指定されたコンテンツを受け付けませんでした | |
| 63006 | Channelに対して指定されたコンテンツの書式設定に失敗しました | |
| 63007 | 指定されたFromアドレスのChannelが見つかりませんでした | Fromアドレスが構成済みのChannelと一致しませんでした。 Channelページから、正しいChannelエンドポイントアドレスを使用していることを確認してください。 |
| 63008 | Could not execute the request because the channel module is misconfigured | TwilioでChannel構成を確認してください。 |
| 63009 | リクエストの実行時にChannelがエラーを返しました | 詳細情報については、Channel固有のエラーメッセージを参照してください。 |
| 63010 | Channels - Twilio内部エラー | |
| 63012 | Channelが、リクエストの完了を妨げる内部エラーを返しました | |
| 63013 | Channelプロバイダーのポリシーに違反したため、メッセージの送信に失敗しました。 | 詳細情報については、Channel固有のエラーメッセージを参照してください。 |
| 63014 | ユーザーアクションによってブロックされたため、そのユーザーへのメッセージ配信に失敗しました。 | 詳細情報については、Channel固有のエラーメッセージを参照してください。 |
Back to the Message properties list.
NumSegmentsプロパティ
For outbound messages, this property indicates the number of SMS messages it took to deliver the body of the message.
If the body of a message is more than 160 GSM-7 characters (or 70 UCS-2 characters), Twilio will segment and annotate your messages to attempt proper reassembly on the recipient's handset (not supported by all carriers and handsets). This ensures your body text transmits with the highest fidelity.
On inbound messages, this property indicates the number of SMS messages that make up the message received.
If the body of a message is more than 160 GSM-7 characters (or 70 UCS-2 characters), Twilio will attempt to reassemble the message received by your Twilio phone number. All carriers and handsets do not necessarily support this.
それぞれのセグメントの送受信に課金されます。
Back to the Message properties list.
StatusCallback Request Parameters
The parameters Twilio passes to your application in its request to the StatusCallback URL include a subset of the standard request parameters and these additional parameters:
| パラメーター | 概要 |
|---|---|
| MessageStatus | The status of the message. Message delivery information is reflected in message status. The possible values are listed in the Message resource. |
| ErrorCode | The error code (if any) associated with your message. If your message status is failed or undelivered, the ErrorCode can give you more information about the failure. If the message was delivered successfully, no ErrorCode will be present. Find the possible values here. |
| ChannelInstallSid | メッセージの送信に使用される、インストール済のChannelのSID（Channel詳細ページにて確認できます）です。 Channelを使用して送信されるメッセージにのみ存在します。 |
| ChannelStatusMessage | メッセージの配信失敗時にChannelによって返されるエラーメッセージです。 メッセージがChannelによって送信され、かつ配信に失敗した場合にのみ存在します。 |
| ChannelPrefix | このメッセージの送信されたChannelを識別するためのChannel固有のプレフィックスです。 |
| EventType | Contains post-delivery events. If the Channel supports Read receipts, this parameter will be included with a value of READ after the user has read the message. Currently supported only for WhatsApp. |
ヘルプが必要ですか？
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.