> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes. # create > Send an SMS or MMS message. Send an SMS or MMS message. Pass the destination and source numbers first, then any other fields in `options`. A message with `media` is sent as MMS. ### Schema ```yaml openapi: 3.1.0 info: title: API version: 1.0.0 paths: /api/messaging/messages: post: operationId: subpackageMessages_create_message summary: Send a message description: >- Create and queue an outbound message for delivery. The channel is determined by the `from` number: - **SMS/MMS** when `from` is a purchased SignalWire phone number or shortcode. The message is MMS when `media` is present or `send_as_mms` is set, otherwise SMS. - **WhatsApp** when `from` is a `whatsapp:`-prefixed [WhatsApp number](/docs/platform/messaging/whatsapp/send-messages). Set `message_type` for a content message, or `template_id` for an [approved template](/docs/platform/messaging/whatsapp/message-templates). Free-form WhatsApp content is only allowed within the 24-hour customer service window. Use this SignalWire REST operation for JSON requests. Integrations built around form-encoded requests and Message SIDs can use the Compatibility API's [Create message](/docs/compatibility-api/rest/messages/create-message) operation instead. #### Permissions The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Messaging_. [Learn more about API scopes](/docs/platform/your-signalwire-api-space). tags: - subpackage_messages responses: '201': description: >- Response returned when a message is successfully created and queued for delivery. content: application/json: schema: $ref: '#/components/schemas/Message.Message' '400': description: The request is invalid. content: application/json: schema: $ref: '#/components/schemas/Types.StatusCodes.StatusCode400' '401': description: Access is unauthorized. content: application/json: schema: $ref: '#/components/schemas/Types.StatusCodes.StatusCode401' '422': description: The request contains invalid parameters. See errors for details. content: application/json: schema: $ref: '#/components/schemas/Message.MessagesCreateStatusCode422' '500': description: An internal server error occurred. content: application/json: schema: $ref: '#/components/schemas/Types.StatusCodes.StatusCode500' requestBody: content: application/json: schema: $ref: '#/components/schemas/Message.SendMessageRequest' tags: - name: subpackage_messages servers: - url: https://%7BYour_Space_Name%7D.signalwire.com description: SignalWire API components: schemas: MessageCreateMessageRequestCustomVariables: type: object properties: {} description: >- Your own key/value string pairs to attach to the message — for example, an order or case number you want to recognize later. When you also set `status_callback`, SignalWire includes these pairs as a `custom_variables` object in every status callback it sends to that URL, so you can match each callback to a record in your own system. If you don't set `status_callback`, there is nowhere for the variables to be delivered. Each value must be a non-empty string of at most 1024 bytes. You can send at most 20 pairs. Each key must start with a letter or underscore and contain only letters, numbers, and underscores, and cannot begin with the reserved prefixes `signalwire_`, `sw_`, `rtc_`, or `internal_` (case-insensitive). Keys are case-sensitive. title: MessageCreateMessageRequestCustomVariables Message.CreateMessageRequest: type: object properties: to: type: string description: >- Destination phone number in E.164 format (`+` followed by 5-17 digits). Also accepts passthrough numbers like `988`/`+988`. from: type: string description: >- Source phone number. Must be a purchased SignalWire phone number on the project in E.164 format, or a shortcode (5-6 digits). Verified caller IDs are not permitted. body: type: string description: >- Message body text. Required if `media` is not provided. Subject to provider-specific character limits. media: type: array items: type: string format: uri description: >- Array of HTTP or HTTPS URLs for media attachments. Presence of media makes the message MMS. Maximum 8 items. send_as_mms: type: boolean default: false description: >- Force the message to be sent as MMS even when no media attachments are provided. status_callback: type: string format: uri description: >- A valid URL to receive message status callback events at each state change. See the [Message status callback](/docs/apis/rest/webhooks/message-status-callback) webhook for the payload your URL will receive. custom_variables: $ref: '#/components/schemas/MessageCreateMessageRequestCustomVariables' description: >- Your own key/value string pairs to attach to the message — for example, an order or case number you want to recognize later. When you also set `status_callback`, SignalWire includes these pairs as a `custom_variables` object in every status callback it sends to that URL, so you can match each callback to a record in your own system. If you don't set `status_callback`, there is nowhere for the variables to be delivered. Each value must be a non-empty string of at most 1024 bytes. You can send at most 20 pairs. Each key must start with a letter or underscore and contain only letters, numbers, and underscores, and cannot begin with the reserved prefixes `signalwire_`, `sw_`, `rtc_`, or `internal_` (case-insensitive). Keys are case-sensitive. required: - to - from description: Request body for sending a new SMS or MMS message. title: Message.CreateMessageRequest MessageWhatsAppTextMessageRequestCustomVariables: type: object properties: {} description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. title: MessageWhatsAppTextMessageRequestCustomVariables MessageWhatsAppTextMessageRequestMessageType: type: string enum: - whatsapp_media_text title: MessageWhatsAppTextMessageRequestMessageType MessageWhatsAppImageMessageRequestCustomVariables: type: object properties: {} description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. title: MessageWhatsAppImageMessageRequestCustomVariables MessageWhatsAppImageMessageRequestMessageType: type: string enum: - whatsapp_media_image title: MessageWhatsAppImageMessageRequestMessageType Message.WhatsAppImageBody: type: object properties: link: type: string format: uri description: A public HTTP/HTTPS URL to the image. id: type: string description: >- The ID of media previously uploaded to WhatsApp. Mutually exclusive with `link`. caption: type: string description: Optional caption shown with the image. description: Body for an image message. Provide either `link` or `id` (not both). title: Message.WhatsAppImageBody MessageWhatsAppContentMessageRequestDiscriminatorMappingWhatsappMediaAudioCustomVariables: type: object properties: {} description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. title: >- MessageWhatsAppContentMessageRequestDiscriminatorMappingWhatsappMediaAudioCustomVariables Message.WhatsAppAudioBody: type: object properties: link: type: string format: uri description: A public HTTP/HTTPS URL to the audio file. id: type: string description: >- The ID of media previously uploaded to WhatsApp. Mutually exclusive with `link`. description: >- Body for an audio message. Provide either `link` or `id` (not both). Captions are not supported. title: Message.WhatsAppAudioBody MessageWhatsAppVideoMessageRequestCustomVariables: type: object properties: {} description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. title: MessageWhatsAppVideoMessageRequestCustomVariables MessageWhatsAppVideoMessageRequestMessageType: type: string enum: - whatsapp_media_video title: MessageWhatsAppVideoMessageRequestMessageType Message.WhatsAppVideoBody: type: object properties: link: type: string format: uri description: A public HTTP/HTTPS URL to the video. id: type: string description: >- The ID of media previously uploaded to WhatsApp. Mutually exclusive with `link`. caption: type: string description: Optional caption shown with the video. description: Body for a video message. Provide either `link` or `id` (not both). title: Message.WhatsAppVideoBody MessageWhatsAppDocumentMessageRequestCustomVariables: type: object properties: {} description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. title: MessageWhatsAppDocumentMessageRequestCustomVariables MessageWhatsAppDocumentMessageRequestMessageType: type: string enum: - whatsapp_media_document title: MessageWhatsAppDocumentMessageRequestMessageType Message.WhatsAppDocumentBody: type: object properties: link: type: string format: uri description: A public HTTP/HTTPS URL to the document. id: type: string description: >- The ID of media previously uploaded to WhatsApp. Mutually exclusive with `link`. caption: type: string description: Optional caption shown with the document. filename: type: string maxLength: 240 description: Optional filename shown to the recipient. Maximum 240 characters. description: Body for a document message. Provide either `link` or `id` (not both). title: Message.WhatsAppDocumentBody MessageWhatsAppStickerMessageRequestCustomVariables: type: object properties: {} description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. title: MessageWhatsAppStickerMessageRequestCustomVariables MessageWhatsAppStickerMessageRequestMessageType: type: string enum: - whatsapp_media_sticker title: MessageWhatsAppStickerMessageRequestMessageType Message.WhatsAppStickerBody: type: object properties: link: type: string format: uri description: >- A public HTTP/HTTPS URL to the sticker file. Meta requires `.webp` format. id: type: string description: >- The ID of media previously uploaded to WhatsApp. Mutually exclusive with `link`. description: >- Body for a sticker message. Provide either `link` or `id` (not both). Captions are not supported. title: Message.WhatsAppStickerBody MessageWhatsAppLocationMessageRequestCustomVariables: type: object properties: {} description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. title: MessageWhatsAppLocationMessageRequestCustomVariables MessageWhatsAppLocationMessageRequestMessageType: type: string enum: - whatsapp_media_location title: MessageWhatsAppLocationMessageRequestMessageType Message.WhatsAppLocationBody: type: object properties: latitude: type: number format: double minimum: -90 maximum: 90 description: Latitude, between -90 and 90. longitude: type: number format: double minimum: -180 maximum: 180 description: Longitude, between -180 and 180. name: type: string description: The name of the location. address: type: string description: The address of the location. required: - latitude - longitude - name - address description: Body for a location message. All fields are required. title: Message.WhatsAppLocationBody MessageWhatsAppContentMessageRequestDiscriminatorMappingWhatsappMediaContactsCustomVariables: type: object properties: {} description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. title: >- MessageWhatsAppContentMessageRequestDiscriminatorMappingWhatsappMediaContactsCustomVariables Message.WhatsAppContactName: type: object properties: formatted_name: type: string description: The contact's full formatted name. Required. required: - formatted_name description: The name fields of a shared contact. title: Message.WhatsAppContactName Message.WhatsAppContact: type: object properties: name: $ref: '#/components/schemas/Message.WhatsAppContactName' description: The contact's name. `formatted_name` is required. required: - name description: >- A shared contact card. Additional fields (phones, emails, org, etc.) follow the WhatsApp contacts message format. title: Message.WhatsAppContact MessageWhatsAppReactionMessageRequestCustomVariables: type: object properties: {} description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. title: MessageWhatsAppReactionMessageRequestCustomVariables MessageWhatsAppReactionMessageRequestMessageType: type: string enum: - whatsapp_media_reaction title: MessageWhatsAppReactionMessageRequestMessageType Message.WhatsAppReactionBody: type: object properties: message_id: type: string description: The ID of the message being reacted to. emoji: type: string description: The emoji to react with. required: - message_id - emoji description: Body for a reaction message. title: Message.WhatsAppReactionBody MessageWhatsAppInteractiveCtaMessageRequestCustomVariables: type: object properties: {} description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. title: MessageWhatsAppInteractiveCtaMessageRequestCustomVariables MessageWhatsAppInteractiveCtaMessageRequestMessageType: type: string enum: - whatsapp_interactive_cta title: MessageWhatsAppInteractiveCtaMessageRequestMessageType MessageWhatsAppInteractiveBodyAction: type: object properties: {} description: >- The interactive action. Its contents depend on `type` (for example, a `buttons` array, list `sections`, or Flow parameters). title: MessageWhatsAppInteractiveBodyAction MessageWhatsAppInteractiveBodyHeader: type: object properties: {} description: Optional header object. title: MessageWhatsAppInteractiveBodyHeader MessageWhatsAppInteractiveBodyBody: type: object properties: {} description: 'Optional body object, e.g. `{ "text": "How can we help?" }`.' title: MessageWhatsAppInteractiveBodyBody MessageWhatsAppInteractiveBodyFooter: type: object properties: {} description: Optional footer object. title: MessageWhatsAppInteractiveBodyFooter Message.WhatsAppInteractiveBody: type: object properties: type: type: string description: >- The interactive type, e.g. `button`, `list`, `cta_url`, `location_request_message`, or `flow`. action: $ref: '#/components/schemas/MessageWhatsAppInteractiveBodyAction' description: >- The interactive action. Its contents depend on `type` (for example, a `buttons` array, list `sections`, or Flow parameters). header: $ref: '#/components/schemas/MessageWhatsAppInteractiveBodyHeader' description: Optional header object. body: $ref: '#/components/schemas/MessageWhatsAppInteractiveBodyBody' description: 'Optional body object, e.g. `{ "text": "How can we help?" }`.' footer: $ref: '#/components/schemas/MessageWhatsAppInteractiveBodyFooter' description: Optional footer object. required: - type - action description: >- Body for an interactive message. `type` and `action` are required; `header`, `body`, and `footer` are optional. The shape of `action` depends on the interactive type — buttons, list sections, a call-to-action URL, a location request, or a Flow — and follows the WhatsApp interactive message format. title: Message.WhatsAppInteractiveBody MessageWhatsAppInteractiveListMessageRequestCustomVariables: type: object properties: {} description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. title: MessageWhatsAppInteractiveListMessageRequestCustomVariables MessageWhatsAppInteractiveListMessageRequestMessageType: type: string enum: - whatsapp_interactive_list title: MessageWhatsAppInteractiveListMessageRequestMessageType MessageWhatsAppInteractiveReplyButtonMessageRequestCustomVariables: type: object properties: {} description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. title: MessageWhatsAppInteractiveReplyButtonMessageRequestCustomVariables MessageWhatsAppInteractiveReplyButtonMessageRequestMessageType: type: string enum: - whatsapp_interactive_reply_button title: MessageWhatsAppInteractiveReplyButtonMessageRequestMessageType MessageWhatsAppInteractiveLocationRequestMessageRequestCustomVariables: type: object properties: {} description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. title: MessageWhatsAppInteractiveLocationRequestMessageRequestCustomVariables MessageWhatsAppInteractiveLocationRequestMessageRequestMessageType: type: string enum: - whatsapp_interactive_location_request_message title: MessageWhatsAppInteractiveLocationRequestMessageRequestMessageType Message.WhatsAppContentMessageRequest: oneOf: - type: object properties: message_type: $ref: >- #/components/schemas/MessageWhatsAppTextMessageRequestMessageType to: type: string description: Recipient phone number in E.164 format. from: type: string description: >- Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. status_callback: type: string format: uri description: >- A valid URL to receive message status callback events at each state change. custom_variables: $ref: >- #/components/schemas/MessageWhatsAppTextMessageRequestCustomVariables description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. body: type: string description: The message text. required: - message_type - to - from - body description: >- Send a plain text WhatsApp message. Allowed only within the 24-hour customer service window. - type: object properties: message_type: $ref: >- #/components/schemas/MessageWhatsAppImageMessageRequestMessageType to: type: string description: Recipient phone number in E.164 format. from: type: string description: >- Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. status_callback: type: string format: uri description: >- A valid URL to receive message status callback events at each state change. custom_variables: $ref: >- #/components/schemas/MessageWhatsAppImageMessageRequestCustomVariables description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. body: $ref: '#/components/schemas/Message.WhatsAppImageBody' required: - message_type - to - from - body description: Send an image message, with an optional caption. - type: object properties: message_type: type: string enum: - whatsapp_media_audio description: 'Discriminator value: whatsapp_media_audio' to: type: string description: Recipient phone number in E.164 format. from: type: string description: >- Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. status_callback: type: string format: uri description: >- A valid URL to receive message status callback events at each state change. custom_variables: $ref: >- #/components/schemas/MessageWhatsAppContentMessageRequestDiscriminatorMappingWhatsappMediaAudioCustomVariables description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. body: $ref: '#/components/schemas/Message.WhatsAppAudioBody' required: - message_type - to - from - body description: Send an audio message. - type: object properties: message_type: $ref: >- #/components/schemas/MessageWhatsAppVideoMessageRequestMessageType to: type: string description: Recipient phone number in E.164 format. from: type: string description: >- Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. status_callback: type: string format: uri description: >- A valid URL to receive message status callback events at each state change. custom_variables: $ref: >- #/components/schemas/MessageWhatsAppVideoMessageRequestCustomVariables description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. body: $ref: '#/components/schemas/Message.WhatsAppVideoBody' required: - message_type - to - from - body description: Send a video message, with an optional caption. - type: object properties: message_type: $ref: >- #/components/schemas/MessageWhatsAppDocumentMessageRequestMessageType to: type: string description: Recipient phone number in E.164 format. from: type: string description: >- Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. status_callback: type: string format: uri description: >- A valid URL to receive message status callback events at each state change. custom_variables: $ref: >- #/components/schemas/MessageWhatsAppDocumentMessageRequestCustomVariables description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. body: $ref: '#/components/schemas/Message.WhatsAppDocumentBody' required: - message_type - to - from - body description: Send a document message, with an optional filename and caption. - type: object properties: message_type: $ref: >- #/components/schemas/MessageWhatsAppStickerMessageRequestMessageType to: type: string description: Recipient phone number in E.164 format. from: type: string description: >- Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. status_callback: type: string format: uri description: >- A valid URL to receive message status callback events at each state change. custom_variables: $ref: >- #/components/schemas/MessageWhatsAppStickerMessageRequestCustomVariables description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. body: $ref: '#/components/schemas/Message.WhatsAppStickerBody' required: - message_type - to - from - body description: Send a sticker message. Captions are not supported. - type: object properties: message_type: $ref: >- #/components/schemas/MessageWhatsAppLocationMessageRequestMessageType to: type: string description: Recipient phone number in E.164 format. from: type: string description: >- Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. status_callback: type: string format: uri description: >- A valid URL to receive message status callback events at each state change. custom_variables: $ref: >- #/components/schemas/MessageWhatsAppLocationMessageRequestCustomVariables description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. body: $ref: '#/components/schemas/Message.WhatsAppLocationBody' required: - message_type - to - from - body description: Share a location. - type: object properties: message_type: type: string enum: - whatsapp_media_contacts description: 'Discriminator value: whatsapp_media_contacts' to: type: string description: Recipient phone number in E.164 format. from: type: string description: >- Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. status_callback: type: string format: uri description: >- A valid URL to receive message status callback events at each state change. custom_variables: $ref: >- #/components/schemas/MessageWhatsAppContentMessageRequestDiscriminatorMappingWhatsappMediaContactsCustomVariables description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. body: type: array items: $ref: '#/components/schemas/Message.WhatsAppContact' description: One or more contacts to share. required: - message_type - to - from - body description: Share one or more contact cards. - type: object properties: message_type: $ref: >- #/components/schemas/MessageWhatsAppReactionMessageRequestMessageType to: type: string description: Recipient phone number in E.164 format. from: type: string description: >- Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. status_callback: type: string format: uri description: >- A valid URL to receive message status callback events at each state change. custom_variables: $ref: >- #/components/schemas/MessageWhatsAppReactionMessageRequestCustomVariables description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. body: $ref: '#/components/schemas/Message.WhatsAppReactionBody' required: - message_type - to - from - body description: React to a message with an emoji. - type: object properties: message_type: $ref: >- #/components/schemas/MessageWhatsAppInteractiveCtaMessageRequestMessageType to: type: string description: Recipient phone number in E.164 format. from: type: string description: >- Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. status_callback: type: string format: uri description: >- A valid URL to receive message status callback events at each state change. custom_variables: $ref: >- #/components/schemas/MessageWhatsAppInteractiveCtaMessageRequestCustomVariables description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. body: $ref: '#/components/schemas/Message.WhatsAppInteractiveBody' required: - message_type - to - from - body description: >- Send a call-to-action URL interactive message. The `body.type` is `cta_url` and `action` carries the button's display text and URL. - type: object properties: message_type: $ref: >- #/components/schemas/MessageWhatsAppInteractiveListMessageRequestMessageType to: type: string description: Recipient phone number in E.164 format. from: type: string description: >- Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. status_callback: type: string format: uri description: >- A valid URL to receive message status callback events at each state change. custom_variables: $ref: >- #/components/schemas/MessageWhatsAppInteractiveListMessageRequestCustomVariables description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. body: $ref: '#/components/schemas/Message.WhatsAppInteractiveBody' required: - message_type - to - from - body description: Send a list interactive message (up to 10 items). - type: object properties: message_type: $ref: >- #/components/schemas/MessageWhatsAppInteractiveReplyButtonMessageRequestMessageType to: type: string description: Recipient phone number in E.164 format. from: type: string description: >- Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. status_callback: type: string format: uri description: >- A valid URL to receive message status callback events at each state change. custom_variables: $ref: >- #/components/schemas/MessageWhatsAppInteractiveReplyButtonMessageRequestCustomVariables description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. body: $ref: '#/components/schemas/Message.WhatsAppInteractiveBody' required: - message_type - to - from - body description: >- Send a reply-button interactive message (up to 3 buttons). The `body.type` is `button` and each entry in `action.buttons` is a `reply` button. - type: object properties: message_type: $ref: >- #/components/schemas/MessageWhatsAppInteractiveLocationRequestMessageRequestMessageType to: type: string description: Recipient phone number in E.164 format. from: type: string description: >- Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. status_callback: type: string format: uri description: >- A valid URL to receive message status callback events at each state change. custom_variables: $ref: >- #/components/schemas/MessageWhatsAppInteractiveLocationRequestMessageRequestCustomVariables description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. body: $ref: '#/components/schemas/Message.WhatsAppInteractiveBody' required: - message_type - to - from - body description: Request the customer's location. discriminator: propertyName: message_type description: >- A WhatsApp content message. The `message_type` field determines the shape of `body`. title: Message.WhatsAppContentMessageRequest MessageWhatsAppTemplateMessageRequestCustomVariables: type: object properties: {} description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. title: MessageWhatsAppTemplateMessageRequestCustomVariables MessageWhatsAppTemplateMessageRequestHeaderTemplateParameters: oneOf: - type: array items: type: string - type: object additionalProperties: description: Any type - type: string description: >- Values for the placeholders in the template header. An array for positional parameters, an object for named parameters, or a media URL string for a document/media header. title: MessageWhatsAppTemplateMessageRequestHeaderTemplateParameters MessageWhatsAppTemplateMessageRequestBodyTemplateParameters: oneOf: - type: array items: type: string - type: object additionalProperties: description: Any type description: >- Values for the placeholders in the template body. An array for positional parameters or an object for named parameters. title: MessageWhatsAppTemplateMessageRequestBodyTemplateParameters Message.WhatsAppTemplateMessageRequest: type: object properties: to: type: string description: Recipient phone number in E.164 format. from: type: string description: >- Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. status_callback: type: string format: uri description: >- A valid URL to receive message status callback events at each state change. custom_variables: $ref: >- #/components/schemas/MessageWhatsAppTemplateMessageRequestCustomVariables description: >- Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. template_id: type: string description: >- The template to send, by SignalWire template ID or Meta template ID. The template must be `approved`. header_template_parameters: $ref: >- #/components/schemas/MessageWhatsAppTemplateMessageRequestHeaderTemplateParameters description: >- Values for the placeholders in the template header. An array for positional parameters, an object for named parameters, or a media URL string for a document/media header. body_template_parameters: $ref: >- #/components/schemas/MessageWhatsAppTemplateMessageRequestBodyTemplateParameters description: >- Values for the placeholders in the template body. An array for positional parameters or an object for named parameters. button_template_parameters: type: array items: type: string description: >- Values for URL-button placeholders. Positional only (an array); named parameters are not supported for buttons. required: - to - from - template_id description: >- Send an approved WhatsApp template. Use this to reach a customer for the first time or outside the 24-hour window. Do not include `body` or `message_type`. title: Message.WhatsAppTemplateMessageRequest Message.SendMessageRequest: oneOf: - $ref: '#/components/schemas/Message.CreateMessageRequest' - $ref: '#/components/schemas/Message.WhatsAppContentMessageRequest' - $ref: '#/components/schemas/Message.WhatsAppTemplateMessageRequest' description: >- Request body for `POST /api/messaging/messages`. The channel is determined by the `from` number: - An SMS/MMS request when `from` is a purchased phone number or shortcode. - A WhatsApp **content** message when `from` is a `whatsapp:`-prefixed number and `message_type` is set. - A WhatsApp **template** message when `from` is a `whatsapp:`-prefixed number and `template_id` is set. title: Message.SendMessageRequest uuid: type: string format: uuid description: Universal Unique Identifier. title: uuid Message.MessageStatus: type: string enum: - queued - initiated - sent - delivered - undelivered - failed - read description: Delivery state of a message. title: Message.MessageStatus Message.MessageDirection: type: string enum: - inbound - outbound description: The direction of a message. title: Message.MessageDirection Message.MessageKind: type: string enum: - sms - mms - whatsapp description: The kind of message. title: Message.MessageKind Message.Message: type: object properties: id: $ref: '#/components/schemas/uuid' description: >- The unique ID of the message. This is the `MessageSegment` ID, consistent with the dashboard and the `/api/messaging/logs` endpoint. from: type: string description: The source phone number. to: type: string description: The destination phone number. body: type: string description: >- The message body text. Returns an empty string when the message has been redacted. status: $ref: '#/components/schemas/Message.MessageStatus' description: Delivery state of the message. direction: $ref: '#/components/schemas/Message.MessageDirection' description: The direction of the message. kind: $ref: '#/components/schemas/Message.MessageKind' description: The kind of message. media: type: array items: type: string format: uri description: >- Array of URLs for any media attachments on the message. Empty for SMS. number_of_segments: type: integer description: Number of segments the message body was split into for delivery. error_code: type: - string - 'null' description: >- Provider-specific error code if delivery failed. Null when no error occurred. error_message: type: - string - 'null' description: >- Human-readable error message if delivery failed. Null when no error occurred. created_at: type: string format: date-time description: Date and time when the message was created. project_id: $ref: '#/components/schemas/uuid' description: The ID of the project the message belongs to. status_callback_url: type: - string - 'null' format: uri description: >- Callback URL configured to receive message status events. Null if no callback was configured. message_uri: type: string description: >- Relative URL for retrieving the message via the `/api/messaging/logs` endpoint. required: - id - from - to - body - status - direction - kind - media - number_of_segments - error_code - error_message - created_at - project_id - status_callback_url - message_uri description: A message record. Returned by the create and update endpoints. title: Message.Message TypesStatusCodesStatusCode400Error: type: string enum: - Bad Request title: TypesStatusCodesStatusCode400Error Types.StatusCodes.StatusCode400: type: object properties: error: $ref: '#/components/schemas/TypesStatusCodesStatusCode400Error' required: - error description: The request is invalid. title: Types.StatusCodes.StatusCode400 TypesStatusCodesStatusCode401Error: type: string enum: - Unauthorized title: TypesStatusCodesStatusCode401Error Types.StatusCodes.StatusCode401: type: object properties: error: $ref: '#/components/schemas/TypesStatusCodesStatusCode401Error' required: - error description: Access is unauthorized. title: Types.StatusCodes.StatusCode401 Types.StatusCodes.RestApiErrorItem: type: object properties: type: type: string description: The category of error. code: type: string description: A specific error code. message: type: string description: A description of what caused the error. attribute: type: - string - 'null' description: The request parameter that caused the error, if applicable. url: type: string description: A link to documentation about this error. required: - type - code - message - url description: Details about a specific error. title: Types.StatusCodes.RestApiErrorItem Message.MessagesCreateStatusCode422: type: object properties: errors: type: array items: $ref: '#/components/schemas/Types.StatusCodes.RestApiErrorItem' description: List of validation errors. required: - errors description: The request contains invalid parameters. See errors for details. title: Message.MessagesCreateStatusCode422 TypesStatusCodesStatusCode500Error: type: string enum: - Internal Server Error title: TypesStatusCodesStatusCode500Error Types.StatusCodes.StatusCode500: type: object properties: error: $ref: '#/components/schemas/TypesStatusCodesStatusCode500Error' required: - error description: An internal server error occurred. title: Types.StatusCodes.StatusCode500 ``` ## **Response Example** ### Response (201) ```json { "id": "c2d3e4f5-a6b7-8901-cdef-234567890abc", "from": "+15559876543", "to": "+15551234567", "body": "Your order #12345 has shipped!", "status": "queued", "direction": "outbound", "kind": "sms", "media": [], "number_of_segments": 1, "error_code": null, "error_message": null, "created_at": "2024-05-06T12:20:00Z", "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status_callback_url": null, "message_uri": "/api/messaging/logs/c2d3e4f5-a6b7-8901-cdef-234567890abc" } ``` ## **Examples** ### Send an SMS ```typescript {9-11} import { RestClient } from "@signalwire/sdk"; const client = new RestClient({ project: "your-project-id", token: "your-api-token", host: "your-space.signalwire.com" }); const message = await client.messages.create("+15559876543", "+15551234567", { body: "Your Bayview Taxi van is 5 minutes away.", }); console.log(message.id, message.status); ``` ### Send an MMS with a status callback ```typescript {9-14} import { RestClient } from "@signalwire/sdk"; const client = new RestClient({ project: "your-project-id", token: "your-api-token", host: "your-space.signalwire.com" }); const message = await client.messages.create("+15559876543", "+15551234567", { body: "Here is your receipt.", media: ["https://example.com/receipts/4410.png"], status_callback: "https://example.com/webhooks/message-status", custom_variables: { ride_id: "ride-4410" }, }); ``` > Send an SMS or MMS message.