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

### messages.create

Send an outbound SMS or MMS message. The `from_` number determines the channel;
pass `media` or `send_as_mms=True` to send an 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'
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

```

## Parameters

All parameters are keyword-only.

**`to`** `str` — required

Destination phone number in E.164 format.

---

**`from_`** `str` — required

Sending phone number in E.164 format. It must belong to your project. The
trailing underscore avoids Python's reserved word; the SDK sends it as `from`.

---

**`body`** `str | None` — default: None

Text content of the message.

---

**`media`** `list[str] | None` — default: None

URLs of media attachments. Supplying media sends the message as MMS.

---

**`send_as_mms`** `bool | None` — default: None

Send as MMS even when no media is attached.

---

**`status_callback`** `str | None` — default: None

URL that receives delivery status updates for this message.

---

**`custom_variables`** `dict[str, str] | None` — default: None

Your own key/value string pairs, up to 20. When `status_callback` is set, every
status callback includes them as a `custom_variables` object so you can match
it to a record in your own system.

---

**`extras`** `Mapping[str, Any] | None` — default: None

Additional request body fields merged into the payload as sent.

---

**`request_options`** `RequestOptions | None` — default: None

Per-call timeout and retry overrides. See
[`RequestOptions`](/docs/server-sdks/reference/python/rest/request-options).

---

## Returns

`Message` — the queued message, including its `id`, `status`, `direction`, and
`number_of_segments`.

## 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"
}
```

## Example

```python {9}
from signalwire.rest import RestClient

client = RestClient(
    project="your-project-id",
    token="your-api-token",
    host="your-space.signalwire.com",
)

message = client.messages.create(
    to="+15551234567",
    from_="+15559876543",
    body="Your order #4821 has shipped.",
    media=["https://example.com/receipts/4821.png"],
    status_callback="https://example.com/sms-status",
)
print(message["id"], message["status"])
```