Send a message | Nexiom Connect

POST/v1/messaging/messages

One endpoint sends on every messaging channel: channel chooses the channel and the fields that go with it. WhatsApp is available today; the WhatsApp fields are below.

Authorization

Bearer token

Authorizationrequiredheader: Send your API key as Bearer YOUR_API_KEY.; Requires whatsapp.send to send on the whatsapp channel. A key with whatsapp.full_access can also send. WhatsApp must be turned on for your organization.

Headers

Authorizationrequired: Bearer YOUR_API_KEY
Content-Typerequired: application/json
Idempotency-Keyrequired: A stable key for this send operation, up to 200 characters. Scoped to your project.

Body parameters

application/json

channelrequiredstring: whatsapp. The channel to send on; it decides the other fields.
fromrequiredstring: Phone number of the connected WhatsApp number to send from, in E.164 format, such as +213555000111. It must be connected in the API key's project.
torequiredstring: Recipient phone number in E.164 format: +, the country code, and 7 to 15 digits, such as +213555123456.
templaterequiredobject: The approved template to send.
template.idrequiredstring: Template ID of an approved template of the sender's WhatsApp Business Account, starting with wat_. The template sets the language and category.
template.variablesoptionalobject: Values for the template's variables. Omit it for a template without variables.
template.variables.headeroptionalobject: Header variable values, keyed by variable number or name, such as { "1": "A-1234" }.
template.variables.bodyoptionalobject: Body variable values, keyed by variable number or name, such as { "1": "Amina", "2": "A-1234" }.

Every variable of the template's header and body needs a non-empty string value of up to 1,024 characters. Keys are the variable's number ("1") for numbered variables, or its name ("first_name") for named ones. See Variables.

Response

application/json200 OK

Example identifiers below are illustrative.

data is the message object, without content. A normal send returns the status accepted: WhatsApp accepted the message, which is not yet delivery. Follow it with Retrieve a message or the WhatsApp webhooks.

When WhatsApp doesn't confirm the message in time, the response is still 200 with the status uncertain: the message may have been sent, and it is never resent automatically. See When a message is uncertain.

Retrying with the same Idempotency-Key and the same body returns the original message as it is now, without sending or charging again. Its status may have moved on.

Errors

Errors carry an error category, a code for WhatsApp-specific cases, a readable message, and a correlationId. A refused request sends nothing and charges nothing, unless it says the message was stored as failed.

Status	`code`	Returned when
`400`	none	The body doesn't match the schema: a missing or unavailable `channel`, an unknown or missing field, or `from` or `to` not in E.164 format. `details` lists the failing fields.
`400`	`INVALID_DATA`	The `Idempotency-Key` header is missing, empty, or longer than 200 characters.
`400`	`whatsapp_template_variable_missing`	A variable of the template has no value, or an empty one.
`400`	`whatsapp_template_variable_unknown`	A value was given for a variable the template doesn't have.
`400`	`whatsapp_template_variable_too_long`	A value is longer than 1,024 characters.
`401`	none	The API key is missing, malformed, revoked, or expired.
`403`	none	The key lacks the `whatsapp.send` permission.
`403`	`FEATURE_NOT_AVAILABLE`	WhatsApp is not turned on for your organization.
`403`	`paid_usage_disabled`	The plan's included messages are used up and paid usage is off.
`404`	`whatsapp_number_not_found`	No number with this phone number is connected in the key's project.
`404`	`whatsapp_sender_removed`	The sender was removed. Connect the number again to send from it.
`404`	`whatsapp_template_not_found`	No template with this ID exists for the sender's WhatsApp Business Account.
`409`	`whatsapp_idempotency_key_reused`	The key was already used for a different message.
`422`	`whatsapp_number_not_ready`	The number is not connected, or WhatsApp is limiting or blocking it. Check the sender's page.
`422`	`whatsapp_template_not_approved`	The template, or its latest edit, is not approved, or it was deleted in WhatsApp.
`422`	`whatsapp_template_not_supported`	The template has content Nexiom Connect can't send yet, such as a media header. The message explains which.
`422`	`whatsapp_message_rejected`	WhatsApp refused the message; `message` includes WhatsApp's reason. The message is stored as `failed`.
`422`	`whatsapp_provider_unavailable`	WhatsApp is busy. The message is stored as `failed`; retry later with a new key.
`429`	`api_rate_limit_per_second_exceeded`	Your organization sent more requests per second than its plan allows.
`429`	`api_key_authentication_rate_limited`	Too many requests with invalid API keys from your network.
`429`	`included_usage_exhausted`	The plan's included messages are used up, and the plan has no paid messages.
`429`	`usage_spend_limit_exceeded`	The message would go past your spending limit.
`429`	`wallet_balance_insufficient`	The wallet cannot cover a message beyond the included ones.
`429`	`service_not_in_plan`	Your plan doesn't include WhatsApp messages.

A 422 stored as failed keeps its idempotency key: retrying with the same key returns that failed message instead of sending again.

curl -X POST "https://api-connect.nxiom.com/api/v1/messaging/messages" \
  -H "Authorization: Bearer $NEXIOM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-A-1234-shipped" \
  -d '{
  "channel": "whatsapp",
  "from": "+213555000111",
  "to": "+213555123456",
  "template": {
    "id": "wat_example",
    "variables": {
      "body": {
        "1": "Amina",
        "2": "A-1234"
      }
    }
  }
}'

Set NEXIOM_API_KEY in your environment.

{
  "message": "Message sent",
  "data": {
    "id": "msg_example",
    "channel": "whatsapp",
    "status": "accepted",
    "sender": "+213555000111",
    "sender_name": "Acme",
    "recipient": "+213555123456",
    "category": "utility",
    "template": {
      "id": "wat_example",
      "name": "order_update",
      "language": "en_US",
      "version": 1
    },
    "is_billable": true,
    "cost": "0.0000",
    "cost_currency": "DZD",
    "failure_code": null,
    "failure_reason": null,
    "created_at": "2026-10-14T09:30:00.000Z",
    "accepted_at": "2026-10-14T09:30:01.000Z",
    "sent_at": null,
    "delivered_at": null,
    "read_at": null,
    "failed_at": null
  }
}

Message accepted by WhatsApp. Keep its id to follow delivery.

Authorization#

Headers#

Body parameters#

Response#

Errors#

Authorization

Headers

Body parameters

Response

Errors