openapi: 3.1.0 info: title: Twilio Messaging API description: >- Send and receive SMS and MMS messages globally using Twilio's Messaging API. Supports programmable messaging, messaging services, alphanumeric sender IDs, A2P 10DLC registration, toll-free verification, and link shortening. version: '2.0' contact: name: Twilio Support url: https://support.twilio.com email: support@twilio.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html termsOfService: https://www.twilio.com/legal/tos externalDocs: description: Twilio Messaging API Documentation url: https://www.twilio.com/docs/messaging/api servers: - url: https://api.twilio.com/2010-04-01 description: Twilio REST API v1 - url: https://messaging.twilio.com/v1 description: Twilio Messaging Service API tags: - name: Alpha Senders description: Manage alphanumeric sender IDs - name: Media description: Manage media attachments for MMS messages - name: Messages description: Send and manage SMS and MMS messages - name: Messaging Services description: Configure messaging services for scalable messaging - name: Phone Numbers description: Manage sender phone numbers for messaging services - name: Short Codes description: Manage short codes for messaging services security: - accountSid_authToken: [] paths: /Accounts/{AccountSid}/Messages.json: get: operationId: listMessages summary: Twilio List Messages description: >- Retrieve a list of messages associated with your account. The list includes paging information and is sorted by DateSent descending. tags: - Messages parameters: - $ref: '#/components/parameters/AccountSid' - name: To in: query description: Filter by recipient phone number schema: type: string - name: From in: query description: Filter by sender phone number schema: type: string - name: DateSent in: query description: Filter by date sent (YYYY-MM-DD) schema: type: string format: date - name: PageSize in: query description: Number of records to return per page (max 1000) schema: type: integer minimum: 1 maximum: 1000 default: 50 - name: Page in: query description: Page number to retrieve schema: type: integer minimum: 0 responses: '200': description: List of messages content: application/json: schema: $ref: '#/components/schemas/MessageList' '401': description: Unauthorized - invalid credentials '404': description: Account not found post: operationId: createMessage summary: Twilio Send a Message description: >- Send an SMS or MMS message. Specify the recipient, sender, and body or media URL. Messages can be sent from a Twilio phone number, short code, alphanumeric sender ID, or messaging service. tags: - Messages parameters: - $ref: '#/components/parameters/AccountSid' requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateMessageRequest' responses: '201': description: Message created and queued for delivery content: application/json: schema: $ref: '#/components/schemas/Message' '400': description: Invalid request parameters '401': description: Unauthorized - invalid credentials '422': description: Unable to create message /Accounts/{AccountSid}/Messages/{MessageSid}.json: get: operationId: fetchMessage summary: Twilio Fetch a Message description: >- Retrieve details of a specific message by its SID. tags: - Messages parameters: - $ref: '#/components/parameters/AccountSid' - $ref: '#/components/parameters/MessageSid' responses: '200': description: Message details content: application/json: schema: $ref: '#/components/schemas/Message' '401': description: Unauthorized '404': description: Message not found post: operationId: updateMessage summary: Twilio Update a Message description: >- Update the body of a message resource. Can be used to redact message content by posting an empty body. tags: - Messages parameters: - $ref: '#/components/parameters/AccountSid' - $ref: '#/components/parameters/MessageSid' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: Body: type: string description: The updated message body (empty string to redact) Status: type: string enum: - canceled description: Set to canceled to cancel a queued message responses: '200': description: Message updated content: application/json: schema: $ref: '#/components/schemas/Message' '401': description: Unauthorized '404': description: Message not found delete: operationId: deleteMessage summary: Twilio Delete a Message description: >- Delete a message record from your account. The message will no longer appear in your account logs. tags: - Messages parameters: - $ref: '#/components/parameters/AccountSid' - $ref: '#/components/parameters/MessageSid' responses: '204': description: Message deleted '401': description: Unauthorized '404': description: Message not found /Accounts/{AccountSid}/Messages/{MessageSid}/Media.json: get: operationId: listMedia summary: Twilio List Media for a Message description: >- Retrieve a list of media associated with an MMS message. tags: - Media parameters: - $ref: '#/components/parameters/AccountSid' - $ref: '#/components/parameters/MessageSid' - name: PageSize in: query schema: type: integer minimum: 1 maximum: 1000 responses: '200': description: List of media resources content: application/json: schema: $ref: '#/components/schemas/MediaList' '401': description: Unauthorized /Accounts/{AccountSid}/Messages/{MessageSid}/Media/{MediaSid}.json: get: operationId: fetchMedia summary: Twilio Fetch a Media Resource description: >- Retrieve a specific media resource associated with a message. tags: - Media parameters: - $ref: '#/components/parameters/AccountSid' - $ref: '#/components/parameters/MessageSid' - name: MediaSid in: path required: true schema: type: string pattern: ^ME[0-9a-fA-F]{32}$ responses: '200': description: Media resource details content: application/json: schema: $ref: '#/components/schemas/MediaResource' '401': description: Unauthorized '404': description: Media not found delete: operationId: deleteMedia summary: Twilio Delete a Media Resource tags: - Media parameters: - $ref: '#/components/parameters/AccountSid' - $ref: '#/components/parameters/MessageSid' - name: MediaSid in: path required: true schema: type: string pattern: ^ME[0-9a-fA-F]{32}$ responses: '204': description: Media deleted '404': description: Media not found /Services: get: operationId: listMessagingServices summary: Twilio List Messaging Services description: >- Retrieve a list of messaging services associated with your account. tags: - Messaging Services parameters: - name: PageSize in: query schema: type: integer minimum: 1 maximum: 1000 responses: '200': description: List of messaging services content: application/json: schema: $ref: '#/components/schemas/MessagingServiceList' '401': description: Unauthorized post: operationId: createMessagingService summary: Twilio Create a Messaging Service description: >- Create a new messaging service for managing senders and message configuration at scale. tags: - Messaging Services requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateMessagingServiceRequest' responses: '201': description: Messaging service created content: application/json: schema: $ref: '#/components/schemas/MessagingService' '400': description: Invalid request '401': description: Unauthorized /Services/{ServiceSid}: get: operationId: fetchMessagingService summary: Twilio Fetch a Messaging Service tags: - Messaging Services parameters: - $ref: '#/components/parameters/ServiceSid' responses: '200': description: Messaging service details content: application/json: schema: $ref: '#/components/schemas/MessagingService' '404': description: Service not found post: operationId: updateMessagingService summary: Twilio Update a Messaging Service tags: - Messaging Services parameters: - $ref: '#/components/parameters/ServiceSid' requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateMessagingServiceRequest' responses: '200': description: Messaging service updated content: application/json: schema: $ref: '#/components/schemas/MessagingService' '400': description: Invalid request delete: operationId: deleteMessagingService summary: Twilio Delete a Messaging Service tags: - Messaging Services parameters: - $ref: '#/components/parameters/ServiceSid' responses: '204': description: Messaging service deleted '404': description: Service not found /Services/{ServiceSid}/PhoneNumbers: get: operationId: listPhoneNumbers summary: Twilio List Phone Numbers in a Messaging Service tags: - Phone Numbers parameters: - $ref: '#/components/parameters/ServiceSid' responses: '200': description: List of phone numbers content: application/json: schema: type: object properties: phone_numbers: type: array items: $ref: '#/components/schemas/PhoneNumberResource' post: operationId: addPhoneNumber summary: Twilio Add a Phone Number to a Messaging Service tags: - Phone Numbers parameters: - $ref: '#/components/parameters/ServiceSid' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - PhoneNumberSid properties: PhoneNumberSid: type: string description: SID of the phone number to add pattern: ^PN[0-9a-fA-F]{32}$ responses: '201': description: Phone number added '400': description: Invalid request /Services/{ServiceSid}/AlphaSenders: get: operationId: listAlphaSenders summary: Twilio List Alpha Senders in a Messaging Service tags: - Alpha Senders parameters: - $ref: '#/components/parameters/ServiceSid' responses: '200': description: List of alpha senders content: application/json: schema: type: object properties: alpha_senders: type: array items: $ref: '#/components/schemas/AlphaSender' post: operationId: addAlphaSender summary: Twilio Add an Alpha Sender to a Messaging Service tags: - Alpha Senders parameters: - $ref: '#/components/parameters/ServiceSid' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - AlphaSender properties: AlphaSender: type: string description: Alphanumeric sender ID string (max 11 characters) maxLength: 11 responses: '201': description: Alpha sender added '400': description: Invalid request /Services/{ServiceSid}/ShortCodes: get: operationId: listShortCodes summary: Twilio List Short Codes in a Messaging Service tags: - Short Codes parameters: - $ref: '#/components/parameters/ServiceSid' responses: '200': description: List of short codes content: application/json: schema: type: object properties: short_codes: type: array items: $ref: '#/components/schemas/ShortCode' post: operationId: addShortCode summary: Twilio Add a Short Code to a Messaging Service tags: - Short Codes parameters: - $ref: '#/components/parameters/ServiceSid' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - ShortCodeSid properties: ShortCodeSid: type: string description: SID of the short code to add pattern: ^SC[0-9a-fA-F]{32}$ responses: '201': description: Short code added '400': description: Invalid request components: securitySchemes: accountSid_authToken: type: http scheme: basic description: >- Use your Twilio Account SID as the username and Auth Token as the password for HTTP Basic authentication. parameters: AccountSid: name: AccountSid in: path required: true description: The unique identifier of the Twilio account schema: type: string pattern: ^AC[0-9a-fA-F]{32}$ MessageSid: name: MessageSid in: path required: true description: The unique identifier of the message schema: type: string pattern: ^(SM|MM)[0-9a-fA-F]{32}$ ServiceSid: name: ServiceSid in: path required: true description: The unique identifier of the messaging service schema: type: string pattern: ^MG[0-9a-fA-F]{32}$ schemas: Message: type: object properties: sid: type: string pattern: ^(SM|MM)[0-9a-fA-F]{32}$ description: Unique identifier for the message account_sid: type: string pattern: ^AC[0-9a-fA-F]{32}$ description: Account SID that created the message messaging_service_sid: type: string pattern: ^MG[0-9a-fA-F]{32}$ description: SID of the messaging service used to: type: string description: Recipient phone number in E.164 format from: type: string description: Sender phone number, alphanumeric sender ID, or short code body: type: string description: The text body of the message (up to 1600 characters) maxLength: 1600 status: type: string enum: - queued - sending - sent - delivered - undelivered - failed - receiving - received - accepted - scheduled - read - partially_delivered - canceled description: Current status of the message direction: type: string enum: - inbound - outbound-api - outbound-call - outbound-reply description: Direction of the message price: type: string description: Price of the message in the currency specified price_unit: type: string description: Currency unit for the price (e.g., USD) num_segments: type: string description: Number of segments the message was split into num_media: type: string description: Number of media files associated with the message error_code: type: integer description: Error code if the message failed error_message: type: string description: Human-readable error message date_created: type: string format: date-time description: When the message was created date_updated: type: string format: date-time description: When the message was last updated date_sent: type: string format: date-time description: When the message was sent uri: type: string description: Relative URI for this message resource api_version: type: string description: API version used to process the message subresource_uris: type: object description: URIs of related subresources properties: media: type: string MessageList: type: object properties: messages: type: array items: $ref: '#/components/schemas/Message' first_page_uri: type: string next_page_uri: type: string previous_page_uri: type: string page: type: integer page_size: type: integer uri: type: string CreateMessageRequest: type: object required: - To properties: To: type: string description: Recipient phone number in E.164 format From: type: string description: Twilio phone number, short code, or alphanumeric sender ID Body: type: string description: The text content of the message (max 1600 characters) maxLength: 1600 MessagingServiceSid: type: string description: SID of the messaging service to use pattern: ^MG[0-9a-fA-F]{32}$ MediaUrl: type: array items: type: string format: uri description: URLs of media to include in MMS messages (max 10) maxItems: 10 StatusCallback: type: string format: uri description: URL for status callback notifications MaxPrice: type: number description: Maximum price in USD to pay for the message ValidityPeriod: type: integer description: Validity period in seconds (max 14400) maximum: 14400 SendAt: type: string format: date-time description: Time to send a scheduled message (requires messaging service) ScheduleType: type: string enum: - fixed description: Schedule type for scheduled messages ContentSid: type: string description: SID of a content template to use pattern: ^HX[0-9a-fA-F]{32}$ ContentVariables: type: string description: JSON string of variables for content templates MediaResource: type: object properties: sid: type: string pattern: ^ME[0-9a-fA-F]{32}$ description: Unique identifier for the media resource account_sid: type: string pattern: ^AC[0-9a-fA-F]{32}$ parent_sid: type: string description: SID of the parent message content_type: type: string description: MIME type of the media date_created: type: string format: date-time date_updated: type: string format: date-time uri: type: string MediaList: type: object properties: media_list: type: array items: $ref: '#/components/schemas/MediaResource' page: type: integer page_size: type: integer uri: type: string MessagingService: type: object properties: sid: type: string pattern: ^MG[0-9a-fA-F]{32}$ description: Unique identifier for the messaging service account_sid: type: string pattern: ^AC[0-9a-fA-F]{32}$ friendly_name: type: string description: Descriptive name for the messaging service inbound_request_url: type: string format: uri description: URL for incoming message webhooks inbound_method: type: string enum: [GET, POST] fallback_url: type: string format: uri fallback_method: type: string enum: [GET, POST] status_callback: type: string format: uri description: URL for delivery status webhooks sticky_sender: type: boolean description: Whether to use sticky sender for conversations smart_encoding: type: boolean description: Whether to automatically detect Unicode characters area_code_geomatch: type: boolean description: Whether to match sender area code to recipient validity_period: type: integer description: Message validity period in seconds date_created: type: string format: date-time date_updated: type: string format: date-time url: type: string format: uri MessagingServiceList: type: object properties: services: type: array items: $ref: '#/components/schemas/MessagingService' meta: $ref: '#/components/schemas/PaginationMeta' CreateMessagingServiceRequest: type: object required: - FriendlyName properties: FriendlyName: type: string description: Descriptive name for the messaging service InboundRequestUrl: type: string format: uri InboundMethod: type: string enum: [GET, POST] FallbackUrl: type: string format: uri FallbackMethod: type: string enum: [GET, POST] StatusCallback: type: string format: uri StickySender: type: boolean SmartEncoding: type: boolean AreaCodeGeomatch: type: boolean ValidityPeriod: type: integer PhoneNumberResource: type: object properties: sid: type: string pattern: ^PN[0-9a-fA-F]{32}$ phone_number: type: string description: Phone number in E.164 format country_code: type: string capabilities: type: array items: type: string date_created: type: string format: date-time AlphaSender: type: object properties: sid: type: string pattern: ^AI[0-9a-fA-F]{32}$ alpha_sender: type: string description: Alphanumeric sender ID capabilities: type: array items: type: string date_created: type: string format: date-time ShortCode: type: object properties: sid: type: string pattern: ^SC[0-9a-fA-F]{32}$ short_code: type: string country_code: type: string capabilities: type: array items: type: string date_created: type: string format: date-time PaginationMeta: type: object properties: page: type: integer page_size: type: integer first_page_url: type: string format: uri previous_page_url: type: string format: uri next_page_url: type: string format: uri url: type: string format: uri key: type: string