> This page is for APIs.

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

# messaging.send

GET /

Send an outbound message

Reference: https://signalwire.com/docs/apis/relay/server/messaging/messaging-send

## AsyncAPI Specification

```yaml
asyncapi: 2.6.0
info:
  title: messaging.send
  version: subpackage_messagingSend.messaging.send
  description: Send an outbound message
channels:
  /:
    description: Send an outbound message
    publish:
      operationId: subpackage_messagingSend.messaging.send-publish
      summary: Server messages
      message:
        oneOf:
          - $ref: >-
              #/components/messages/subpackage_messagingSend.messaging.send-server-0-onMessagingSendStateEvent
          - $ref: >-
              #/components/messages/subpackage_messagingSend.messaging.send-server-1-onMessagingSendResponse
    subscribe:
      operationId: subpackage_messagingSend.messaging.send-subscribe
      summary: messaging.send
      message:
        name: messagingSend
        title: messaging.send
        payload:
          $ref: '#/components/schemas/messaging.send_messagingSendRequest'
servers:
  production:
    url: wss://relay.signalwire.com/
    protocol: wss
    x-default: true
components:
  messages:
    subpackage_messagingSend.messaging.send-server-0-onMessagingSendStateEvent:
      name: onMessagingSendStateEvent
      title: messaging.state
      payload:
        $ref: '#/components/schemas/messaging.send_stateEvent'
    subpackage_messagingSend.messaging.send-server-1-onMessagingSendResponse:
      name: onMessagingSendResponse
      title: messaging.send response
      payload:
        $ref: '#/components/schemas/messaging.send_messagingSendResponse'
  schemas:
    ChannelsMessagingSendMessagesStateEventJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsMessagingSendMessagesStateEventJsonrpc
    ChannelsMessagingSendMessagesStateEventMethod:
      type: string
      enum:
        - signalwire.event
      description: Always `signalwire.event`.
      title: ChannelsMessagingSendMessagesStateEventMethod
    ChannelsMessagingSendMessagesStateEventParamsEventType:
      type: string
      enum:
        - messaging.state
      description: The event type — identifies which event this is.
      title: ChannelsMessagingSendMessagesStateEventParamsEventType
    Messaging.MessageDirection:
      type: string
      enum:
        - inbound
        - outbound
      title: Messaging.MessageDirection
    MessagingStateEventDataTag:
      oneOf:
        - type: string
        - description: Any type
      description: >-
        Your label for the message, echoed back so you can correlate this state
        update with the message you sent. `null` when you did not set one.
      title: MessagingStateEventDataTag
    MessagingStateEventDataBody:
      oneOf:
        - type: string
        - description: Any type
      description: The text of the message. `null` for a media-only message.
      title: MessagingStateEventDataBody
    Messaging.MessageState:
      type: string
      enum:
        - queued
        - initiated
        - sent
        - delivered
        - undelivered
        - failed
        - read
      title: Messaging.MessageState
    Messaging.StateEventData:
      type: object
      properties:
        message_id:
          type: string
          description: >-
            The ID of the message, matching the one returned by
            `messaging.send`.
        context:
          type: string
          description: The context the message belongs to.
        direction:
          $ref: '#/components/schemas/Messaging.MessageDirection'
          description: The direction of the message, `inbound` or `outbound`.
        tag:
          $ref: '#/components/schemas/MessagingStateEventDataTag'
          description: >-
            Your label for the message, echoed back so you can correlate this
            state update with the message you sent. `null` when you did not set
            one.
        tags:
          type: array
          items:
            type: string
          description: >-
            Reserved and currently unused — always an empty array. Use `tag` to
            label a message.
        from_number:
          type: string
          description: >-
            The sender, as given in `messaging.send`: an E.164 phone number, a
            short code, a `whatsapp:`-prefixed WhatsApp business number, or an
            RCS agent ID.
        to_number:
          type: string
          description: The recipient's phone number, in E.164 format.
        body:
          $ref: '#/components/schemas/MessagingStateEventDataBody'
          description: The text of the message. `null` for a media-only message.
        media:
          type: array
          items:
            type: string
          description: >-
            Any media URLs included with the message. An empty array for
            text-only messages.
        segments:
          type: integer
          description: How many SMS segments the message was split into.
        message_state:
          $ref: '#/components/schemas/Messaging.MessageState'
          description: >-
            The message's new delivery state. `read` is reported for RCS
            messages only.
        reason:
          type: string
          description: >-
            Why the message ended up in this state. Included only when it is
            `undelivered` or `failed`.
        error_code:
          type: string
          description: >-
            A machine-readable error code describing the failure, such as

            `unrouteable_message`, `insufficient_balance_to_send_message`,

            `carrier_violation`, or `unknown_destination_handset`. Included only
            when an

            error occurred.
        error_message:
          type: string
          description: >-
            A description of the error. Same text as `reason`. Included only
            when an error occurred.
      required:
        - message_id
        - context
        - direction
        - tag
        - tags
        - from_number
        - to_number
        - body
        - media
        - segments
        - message_state
      title: Messaging.StateEventData
    ChannelsMessagingSendMessagesStateEventParams:
      type: object
      properties:
        event_type:
          $ref: >-
            #/components/schemas/ChannelsMessagingSendMessagesStateEventParamsEventType
          description: The event type — identifies which event this is.
        context:
          type: string
          description: The context the message belongs to.
        timestamp:
          type: number
          format: double
          description: >-
            When the event was emitted, as a Unix timestamp in seconds. Always
            present.
        project_id:
          type: string
          description: Your project ID. Always present.
        space_id:
          type: string
          description: Your space ID. Always present.
        params:
          $ref: '#/components/schemas/Messaging.StateEventData'
          description: The event-specific payload.
      required:
        - event_type
        - context
        - timestamp
        - project_id
        - space_id
        - params
      description: The event envelope.
      title: ChannelsMessagingSendMessagesStateEventParams
    messaging.send_stateEvent:
      type: object
      properties:
        jsonrpc:
          $ref: '#/components/schemas/ChannelsMessagingSendMessagesStateEventJsonrpc'
          description: JSON-RPC version. Always `2.0`.
        id:
          type: string
          description: >-
            Event id — a unique UUID generated for each event. Events are
            notifications: you do not reply to them.
        method:
          $ref: '#/components/schemas/ChannelsMessagingSendMessagesStateEventMethod'
          description: Always `signalwire.event`.
        params:
          $ref: '#/components/schemas/ChannelsMessagingSendMessagesStateEventParams'
          description: The event envelope.
      required:
        - jsonrpc
        - id
        - method
        - params
      description: >-
        Fires each time a message's delivery state changes. Match `message_id`
        to the

        one you got from `messaging.send` and read `message_state` to see where
        the

        message is in its journey. An SMS or MMS stops at `delivered`,
        `undelivered`,

        or `failed`. An RCS message can also report `read`, including after

        `delivered`. A WhatsApp message gets no updates after `sent`.
      title: messaging.send_stateEvent
    ChannelsMessagingSendMessagesMessagingSendResponseJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsMessagingSendMessagesMessagingSendResponseJsonrpc
    Messaging.SendResult:
      type: object
      properties:
        code:
          type: string
          description: >-
            Result code as a string. `"200"` means success; anything else is an
            error.
        message:
          type: string
          description: A human-readable explanation of the result.
        message_id:
          type: string
          description: >-
            The ID of the accepted message, present on success only. Use it to
            match up later state events.
        data:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: >-
            Present on a `"400"` result: the validation errors, as a map of
            field name to the

            list of error messages for that field.
      required:
        - code
        - message
      description: >-
        The result of a `messaging.send` request: a `code`/`message` outcome
        plus, on success, the accepted `message_id`.
      title: Messaging.SendResult
    JsonRpcErrorCode0:
      type: string
      enum:
        - '-32000'
      title: JsonRpcErrorCode0
    JsonRpcErrorCode1:
      type: string
      enum:
        - '-32001'
      title: JsonRpcErrorCode1
    JsonRpcErrorCode2:
      type: string
      enum:
        - '-32002'
      title: JsonRpcErrorCode2
    JsonRpcErrorCode3:
      type: string
      enum:
        - '-32003'
      title: JsonRpcErrorCode3
    JsonRpcErrorCode4:
      type: string
      enum:
        - '-32004'
      title: JsonRpcErrorCode4
    JsonRpcErrorCode5:
      type: string
      enum:
        - '-32005'
      title: JsonRpcErrorCode5
    JsonRpcErrorCode6:
      type: string
      enum:
        - '-32600'
      title: JsonRpcErrorCode6
    JsonRpcErrorCode7:
      type: string
      enum:
        - '-32601'
      title: JsonRpcErrorCode7
    JsonRpcErrorCode8:
      type: string
      enum:
        - '-32602'
      title: JsonRpcErrorCode8
    JsonRpcErrorCode9:
      type: string
      enum:
        - '-32603'
      title: JsonRpcErrorCode9
    JsonRpcErrorCode10:
      type: string
      enum:
        - '-32700'
      title: JsonRpcErrorCode10
    JsonRpcErrorCode:
      oneOf:
        - $ref: '#/components/schemas/JsonRpcErrorCode0'
        - $ref: '#/components/schemas/JsonRpcErrorCode1'
        - $ref: '#/components/schemas/JsonRpcErrorCode2'
        - $ref: '#/components/schemas/JsonRpcErrorCode3'
        - $ref: '#/components/schemas/JsonRpcErrorCode4'
        - $ref: '#/components/schemas/JsonRpcErrorCode5'
        - $ref: '#/components/schemas/JsonRpcErrorCode6'
        - $ref: '#/components/schemas/JsonRpcErrorCode7'
        - $ref: '#/components/schemas/JsonRpcErrorCode8'
        - $ref: '#/components/schemas/JsonRpcErrorCode9'
        - $ref: '#/components/schemas/JsonRpcErrorCode10'
      title: JsonRpcErrorCode
    JsonRpcError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/JsonRpcErrorCode'
          description: >-
            The error code — a negative integer identifying the failure. See
            `JsonRpcErrorCode` for the full list of values and meanings.
        message:
          type: string
          description: A human-readable description of what went wrong.
        original_request:
          type: object
          additionalProperties:
            description: Any type
          description: >-
            An echo of the request that failed — the full JSON-RPC frame you
            sent

            (`jsonrpc`, `id`, `method`, `params`). Always present.
        requester_nodeid:
          type: string
          description: >-
            The node that sent the failed request. Present only on some routing
            errors.
        requester_identity:
          type: string
          description: >-
            The identity of the requester. Present only on some routing errors;
            same value as `requester_nodeid`.
        responder_nodeid:
          type: string
          description: >-
            The node that was handling the request. Present only on some routing
            errors.
        responder_identity:
          type: string
          description: >-
            The identity of the responder. Present only on some routing errors;
            same value as `responder_nodeid`.
        last_hop_timeout:
          type: boolean
          description: >-
            `true` when the request timed out on its final hop inside
            SignalWire. Present only on some timeout errors.
      required:
        - code
        - message
        - original_request
      description: >-
        A JSON-RPC 2.0 error object, delivered on the `error` field of a
        `JsonRpcResponse` when

        a request fails at the protocol level (bad version, authentication,
        scope, params, or

        your project's connection limit). It replaces `result` — a frame carries
        one or the other, never both.
      title: JsonRpcError
    messaging.send_messagingSendResponse:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsMessagingSendMessagesMessagingSendResponseJsonrpc
          description: JSON-RPC version. Always `2.0`.
        id:
          type: string
          description: The id of the request this responds to.
        result:
          $ref: '#/components/schemas/Messaging.SendResult'
          description: The method result. Present when the request succeeded.
        error:
          $ref: '#/components/schemas/JsonRpcError'
          description: >-
            Present instead of `result` when the request failed at the protocol
            level.
      required:
        - jsonrpc
        - id
      description: >-
        A JSON-RPC response frame correlated to a request by `id`. On success
        the frame carries

        `result` (the method result). If the request fails at the protocol level
        — an

        incompatible version, failed authentication, insufficient scope, invalid
        params, or your

        project's connection limit — the frame carries `error` instead of
        `result`. Many

        method-level failures (for example most Calling failures) are reported
        the other way: a

        normal `result` whose own `code` is not `"200"`. Each method documents
        which form its

        failures take.


        An `error` returned for `signalwire.connect` is followed by the service
        closing the

        WebSocket; open a new connection to try again. The same happens when

        `signalwire.reauthenticate` sends credentials that are rejected, except
        for a

        Subscriber Access Token. Errors on any other request leave the
        connection open.
      title: messaging.send_messagingSendResponse
    ChannelsMessagingSendMessagesMessagingSendRequestJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsMessagingSendMessagesMessagingSendRequestJsonrpc
    ChannelsMessagingSendMessagesMessagingSendRequestMethod:
      type: string
      enum:
        - messaging.send
      description: The name of the JSON-RPC method being invoked.
      title: ChannelsMessagingSendMessagesMessagingSendRequestMethod
    MessagingSendParamsBody:
      oneOf:
        - type: string
        - type: object
          additionalProperties:
            description: Any type
        - type: array
          items:
            description: Any type
      description: >-
        The text of the message. Include `body`, `media`, or both — at least one
        is

        required — unless you are sending a WhatsApp template message
        (`template_id`),

        in which case `body` must be omitted. For WhatsApp media and interactive

        messages (`message_type`), `body` may instead be a JSON object or array

        describing the content.
      title: MessagingSendParamsBody
    Messaging.WhatsAppMessageType:
      type: string
      enum:
        - whatsapp_media_text
        - whatsapp_media_contacts
        - whatsapp_media_audio
        - whatsapp_media_document
        - whatsapp_media_image
        - whatsapp_media_sticker
        - whatsapp_media_video
        - whatsapp_media_reaction
        - whatsapp_media_location
        - whatsapp_interactive_cta
        - whatsapp_interactive_flow
        - whatsapp_interactive_list
        - whatsapp_interactive_location_request_message
        - whatsapp_interactive_reply_button
      title: Messaging.WhatsAppMessageType
    MessagingSendParamsHeaderTemplateParameters:
      oneOf:
        - type: object
          additionalProperties:
            description: Any type
        - type: array
          items:
            description: Any type
        - type: string
      description: >-
        Values for the variables in your WhatsApp template's **header**,
        supplied

        alongside `template_id`. The shape follows the template: an object keyed
        by

        parameter name for a named template, an array of values for a positional

        template, or a media/document URL string for a media header.
      title: MessagingSendParamsHeaderTemplateParameters
    MessagingSendParamsBodyTemplateParameters:
      oneOf:
        - type: object
          additionalProperties:
            description: Any type
        - type: array
          items:
            description: Any type
        - type: string
      description: |-
        Values for the variables in your WhatsApp template's **body**, supplied
        alongside `template_id`. An object keyed by parameter name for a named
        template, or an array of values for a positional template.
      title: MessagingSendParamsBodyTemplateParameters
    MessagingSendParamsButtonTemplateParameters:
      oneOf:
        - type: object
          additionalProperties:
            description: Any type
        - type: array
          items:
            description: Any type
        - type: string
      description: >-
        Values for your WhatsApp template's **button** variables, supplied
        alongside

        `template_id`. The shape follows the template's button definition.
      title: MessagingSendParamsButtonTemplateParameters
    Messaging.SendParams:
      type: object
      properties:
        context:
          type: string
          maxLength: 250
          description: >-
            The context that delivery and reply events for this message are sent
            to. Defaults to `default`. Up to 250 characters.
        tag:
          type: string
          description: >-
            A single tag string stored with the message, useful for
            searching/filtering

            in the dashboard. Echoed back in the `messaging.state` event.
        tags:
          type: array
          items:
            type: string
          description: >-
            Accepted for compatibility but not stored — `messaging.state` events
            always

            report an empty `tags` array. Use `tag` to label a message. Up to 20
            strings.
        to_number:
          type: string
          description: >-
            The recipient's phone number, in E.164 format (for example,
            `+15551231234`).
        from_number:
          type: string
          description: >-
            The sender, which also picks the channel. One of:


            - A phone number on your project, in E.164 format, to send SMS or
            MMS.

            - A 5–6 digit short code on your project, to send SMS or MMS.

            - Your registered WhatsApp business number, prefixed with
            `whatsapp:` (for
              example, `whatsapp:+15551230001`), to send over WhatsApp.
            - The ID of your RCS agent, to send over RCS. The agent must be in
            review,
              launching, or launched, and RCS must be enabled for your space.

            A verified caller ID can't be used as the sender.
        body:
          $ref: '#/components/schemas/MessagingSendParamsBody'
          description: >-
            The text of the message. Include `body`, `media`, or both — at least
            one is

            required — unless you are sending a WhatsApp template message
            (`template_id`),

            in which case `body` must be omitted. For WhatsApp media and
            interactive

            messages (`message_type`), `body` may instead be a JSON object or
            array

            describing the content.
        media:
          type: array
          items:
            type: string
          description: >-
            One or more media URLs to send as an MMS. You must include `body`,
            `media`,

            or both — at least one is required. Each URL must be HTTP or HTTPS.
            Up to

            8 URLs; defaults to an empty array. Not supported when sending from
            an RCS

            agent.
        status_callback:
          type: string
          format: uri
          description: >-
            HTTP or HTTPS URL that SignalWire POSTs per-message delivery-status
            updates to.
        send_as_mms:
          type: boolean
          description: >-
            Force the message to be sent as MMS even when it has no media
            attached.
        message_type:
          $ref: '#/components/schemas/Messaging.WhatsAppMessageType'
          description: >-
            For a WhatsApp media or interactive message, the kind of WhatsApp
            message to

            send. Required when sending from a WhatsApp number unless you supply
            a

            `template_id` instead. Leave unset for SMS, MMS, and RCS.
        template_id:
          type: string
          description: >-
            The ID of a pre-approved WhatsApp message template. Supplying this
            sends a

            template message; when set, `body` must be omitted. Required for a
            WhatsApp

            send when you do not supply a `message_type`. Ignored for SMS/MMS.
        header_template_parameters:
          $ref: '#/components/schemas/MessagingSendParamsHeaderTemplateParameters'
          description: >-
            Values for the variables in your WhatsApp template's **header**,
            supplied

            alongside `template_id`. The shape follows the template: an object
            keyed by

            parameter name for a named template, an array of values for a
            positional

            template, or a media/document URL string for a media header.
        body_template_parameters:
          $ref: '#/components/schemas/MessagingSendParamsBodyTemplateParameters'
          description: >-
            Values for the variables in your WhatsApp template's **body**,
            supplied

            alongside `template_id`. An object keyed by parameter name for a
            named

            template, or an array of values for a positional template.
        button_template_parameters:
          $ref: '#/components/schemas/MessagingSendParamsButtonTemplateParameters'
          description: >-
            Values for your WhatsApp template's **button** variables, supplied
            alongside

            `template_id`. The shape follows the template's button definition.
      required:
        - to_number
        - from_number
      title: Messaging.SendParams
    messaging.send_messagingSendRequest:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsMessagingSendMessagesMessagingSendRequestJsonrpc
          description: JSON-RPC version. Always `2.0`.
        id:
          type: string
          description: Request id, echoed on the correlated response.
        method:
          $ref: >-
            #/components/schemas/ChannelsMessagingSendMessagesMessagingSendRequestMethod
          description: The name of the JSON-RPC method being invoked.
        params:
          $ref: '#/components/schemas/Messaging.SendParams'
          description: The method's input parameters.
      required:
        - jsonrpc
        - id
        - method
        - params
      description: >-
        A JSON-RPC request frame. `Method` is the method name; `Params` is the
        method's input.
      title: messaging.send_messagingSendRequest

```