--- title: "Send a message" method: POST path: "/api/messaging/messages" tags: ["Messages"] --- # Send a message `POST /api/messaging/messages` 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. #### 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). ## Request body - union — 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. - MessageCreateMessageRequest — Request body for sending a new SMS or MMS message. - `to` string, required — Destination phone number in E.164 format (`+` followed by 5-17 digits). Also accepts passthrough numbers like `988`/`+988`. - `from` string, required — 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` string — Message body text. Required if `media` is not provided. Subject to provider-specific character limits. - `media` string[] — Array of HTTP or HTTPS URLs for media attachments. Presence of media makes the message MMS. Maximum 8 items. - `send_as_mms` boolean — Force the message to be sent as MMS even when no media attachments are provided. - `status_callback` string, uri — A valid URL to receive message status callback events at each state change. See the [Message status callback](/docs/apis/rest/messages/webhooks/message-status-callback) webhook for the payload your URL will receive. - `custom_variables` object — 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. - union — A WhatsApp content message. The `message_type` field determines the shape of `body`. - object — Send a plain text WhatsApp message. Allowed only within the 24-hour customer service window. - `to` string, required — Recipient phone number in E.164 format. - `from` string, required — Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. - `status_callback` string, uri — A valid URL to receive message status callback events at each state change. - `custom_variables` object — Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. - `message_type` 'whatsapp_media_text', required - `body` string, required — The message text. - object — Send an image message, with an optional caption. - `to` string, required — Recipient phone number in E.164 format. - `from` string, required — Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. - `status_callback` string, uri — A valid URL to receive message status callback events at each state change. - `custom_variables` object — Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. - `message_type` 'whatsapp_media_image', required - `body` MessageWhatsAppImageBody, required — Body for an image message. Provide either `link` or `id` (not both). - `link` string, uri — A public HTTP/HTTPS URL to the image. - `id` string — The ID of media previously uploaded to WhatsApp. Mutually exclusive with `link`. - `caption` string — Optional caption shown with the image. - object — Send an audio message. - `to` string, required — Recipient phone number in E.164 format. - `from` string, required — Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. - `status_callback` string, uri — A valid URL to receive message status callback events at each state change. - `custom_variables` object — Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. - `message_type` 'whatsapp_media_audio', required - `body` MessageWhatsAppAudioBody, required — Body for an audio message. Provide either `link` or `id` (not both). Captions are not supported. - `link` string, uri — A public HTTP/HTTPS URL to the audio file. - `id` string — The ID of media previously uploaded to WhatsApp. Mutually exclusive with `link`. - object — Send a video message, with an optional caption. - `to` string, required — Recipient phone number in E.164 format. - `from` string, required — Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. - `status_callback` string, uri — A valid URL to receive message status callback events at each state change. - `custom_variables` object — Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. - `message_type` 'whatsapp_media_video', required - `body` MessageWhatsAppVideoBody, required — Body for a video message. Provide either `link` or `id` (not both). - `link` string, uri — A public HTTP/HTTPS URL to the video. - `id` string — The ID of media previously uploaded to WhatsApp. Mutually exclusive with `link`. - `caption` string — Optional caption shown with the video. - object — Send a document message, with an optional filename and caption. - `to` string, required — Recipient phone number in E.164 format. - `from` string, required — Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. - `status_callback` string, uri — A valid URL to receive message status callback events at each state change. - `custom_variables` object — Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. - `message_type` 'whatsapp_media_document', required - `body` MessageWhatsAppDocumentBody, required — Body for a document message. Provide either `link` or `id` (not both). - `link` string, uri — A public HTTP/HTTPS URL to the document. - `id` string — The ID of media previously uploaded to WhatsApp. Mutually exclusive with `link`. - `caption` string — Optional caption shown with the document. - `filename` string — Optional filename shown to the recipient. Maximum 240 characters. - object — Send a sticker message. Captions are not supported. - `to` string, required — Recipient phone number in E.164 format. - `from` string, required — Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. - `status_callback` string, uri — A valid URL to receive message status callback events at each state change. - `custom_variables` object — Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. - `message_type` 'whatsapp_media_sticker', required - `body` MessageWhatsAppStickerBody, required — Body for a sticker message. Provide either `link` or `id` (not both). Captions are not supported. - `link` string, uri — A public HTTP/HTTPS URL to the sticker file. Meta requires `.webp` format. - `id` string — The ID of media previously uploaded to WhatsApp. Mutually exclusive with `link`. - object — Share a location. - `to` string, required — Recipient phone number in E.164 format. - `from` string, required — Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. - `status_callback` string, uri — A valid URL to receive message status callback events at each state change. - `custom_variables` object — Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. - `message_type` 'whatsapp_media_location', required - `body` MessageWhatsAppLocationBody, required — Body for a location message. All fields are required. - `latitude` number, double, required — Latitude, between -90 and 90. - `longitude` number, double, required — Longitude, between -180 and 180. - `name` string, required — The name of the location. - `address` string, required — The address of the location. - object — Share one or more contact cards. - `to` string, required — Recipient phone number in E.164 format. - `from` string, required — Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. - `status_callback` string, uri — A valid URL to receive message status callback events at each state change. - `custom_variables` object — Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. - `message_type` 'whatsapp_media_contacts', required - `body` MessageWhatsAppContact[], required — One or more contacts to share. - `name` MessageWhatsAppContactName, required — The name fields of a shared contact. - `formatted_name` string, required — The contact's full formatted name. Required. - object — React to a message with an emoji. - `to` string, required — Recipient phone number in E.164 format. - `from` string, required — Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. - `status_callback` string, uri — A valid URL to receive message status callback events at each state change. - `custom_variables` object — Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. - `message_type` 'whatsapp_media_reaction', required - `body` MessageWhatsAppReactionBody, required — Body for a reaction message. - `message_id` string, required — The ID of the message being reacted to. - `emoji` string, required — The emoji to react with. - object — Send a call-to-action URL interactive message. The `body.type` is `cta_url` and `action` carries the button's display text and URL. - `to` string, required — Recipient phone number in E.164 format. - `from` string, required — Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. - `status_callback` string, uri — A valid URL to receive message status callback events at each state change. - `custom_variables` object — Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. - `message_type` 'whatsapp_interactive_cta', required - `body` MessageWhatsAppInteractiveBody, required — 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. - `type` string, required — The interactive type, e.g. `button`, `list`, `cta_url`, `location_request_message`, or `flow`. - `action` object, required — The interactive action. Its contents depend on `type` (for example, a `buttons` array, list `sections`, or Flow parameters). - `header` object — Optional header object. - `body` object — Optional body object, e.g. `{ "text": "How can we help?" }`. - `footer` object — Optional footer object. - object — Send a list interactive message (up to 10 items). - `to` string, required — Recipient phone number in E.164 format. - `from` string, required — Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. - `status_callback` string, uri — A valid URL to receive message status callback events at each state change. - `custom_variables` object — Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. - `message_type` 'whatsapp_interactive_list', required - `body` MessageWhatsAppInteractiveBody, required — 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. - `type` string, required — The interactive type, e.g. `button`, `list`, `cta_url`, `location_request_message`, or `flow`. - `action` object, required — The interactive action. Its contents depend on `type` (for example, a `buttons` array, list `sections`, or Flow parameters). - `header` object — Optional header object. - `body` object — Optional body object, e.g. `{ "text": "How can we help?" }`. - `footer` object — Optional footer object. - object — 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. - `to` string, required — Recipient phone number in E.164 format. - `from` string, required — Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. - `status_callback` string, uri — A valid URL to receive message status callback events at each state change. - `custom_variables` object — Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. - `message_type` 'whatsapp_interactive_reply_button', required - `body` MessageWhatsAppInteractiveBody, required — 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. - `type` string, required — The interactive type, e.g. `button`, `list`, `cta_url`, `location_request_message`, or `flow`. - `action` object, required — The interactive action. Its contents depend on `type` (for example, a `buttons` array, list `sections`, or Flow parameters). - `header` object — Optional header object. - `body` object — Optional body object, e.g. `{ "text": "How can we help?" }`. - `footer` object — Optional footer object. - object — Request the customer's location. - `to` string, required — Recipient phone number in E.164 format. - `from` string, required — Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. - `status_callback` string, uri — A valid URL to receive message status callback events at each state change. - `custom_variables` object — Your own key/value string pairs to attach to the message. Delivered as `custom_variables` in status callbacks when `status_callback` is set. - `message_type` 'whatsapp_interactive_location_request_message', required - `body` MessageWhatsAppInteractiveBody, required — 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. - `type` string, required — The interactive type, e.g. `button`, `list`, `cta_url`, `location_request_message`, or `flow`. - `action` object, required — The interactive action. Its contents depend on `type` (for example, a `buttons` array, list `sections`, or Flow parameters). - `header` object — Optional header object. - `body` object — Optional body object, e.g. `{ "text": "How can we help?" }`. - `footer` object — Optional footer object. - MessageWhatsAppTemplateMessageRequest — 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`. - `to` string, required — Recipient phone number in E.164 format. - `from` string, required — Your WhatsApp business number, prefixed with `whatsapp:`. The prefix is what routes the message over WhatsApp instead of SMS/MMS. - `status_callback` string, uri — A valid URL to receive message status callback events at each state change. - `custom_variables` object — 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` string, required — The template to send, by SignalWire template ID or Meta template ID. The template must be `approved`. - `header_template_parameters` union — 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. - string[] - object - string - `body_template_parameters` union — Values for the placeholders in the template body. An array for positional parameters or an object for named parameters. - string[] - object - `button_template_parameters` string[] — Values for URL-button placeholders. Positional only (an array); named parameters are not supported for buttons. ## Response `201` Response returned when a message is successfully created and queued for delivery. - MessageMessage — A message record. Returned by the create and update endpoints. - `id` string, uuid, required — Universal Unique Identifier. - `from` string, required — The source phone number. - `to` string, required — The destination phone number. - `body` string, required — The message body text. Returns an empty string when the message has been redacted. - `status` 'queued' | 'initiated' | 'sent' | 'delivered' | 'undelivered' | 'failed' | 'read', required — Delivery state of a message. - `direction` 'inbound' | 'outbound', required — The direction of a message. - `kind` 'sms' | 'mms' | 'whatsapp', required — The kind of message. - `media` string[], required — Array of URLs for any media attachments on the message. Empty for SMS. - `number_of_segments` integer, required — Number of segments the message body was split into for delivery. - `error_code` string, nullable, required — Provider-specific error code if delivery failed. Null when no error occurred. - `error_message` string, nullable, required — Human-readable error message if delivery failed. Null when no error occurred. - `created_at` string, date-time, required — Date and time when the message was created. - `project_id` string, uuid, required — Universal Unique Identifier. - `status_callback_url` string, uri, nullable, required — Callback URL configured to receive message status events. Null if no callback was configured. - `message_uri` string, required — Relative URL for retrieving the message via the `/api/messaging/logs` endpoint. ## Other responses - `400` — The request is invalid. - `401` — Access is unauthorized. - `422` — The request contains invalid parameters. See errors for details. - `500` — An internal server error occurred. --- [API](https://skmtc.net/signalwire/apis/signalwire-rest-api.md) · [All operations](https://skmtc.net/signalwire/apis/signalwire-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/signalwire/signalwire-rest-api/versions/05c5164b85c7/schema)