Send a WhatsApp message

POSThttps://api.norreach.app/v1/messages

POST /messages with channel: "whatsapp" sends one WhatsApp message to a saved contact, from your workspace's WhatsApp business number. Asks for a new email, SMS or WhatsApp message to a SAVED contact — never a free-typed address, so every message goes to someone the workspace holds a record (and a lawful basis) for. It is an API send: it waits in Approvals when the workspace (or campaign_id's campaign) approves before sending, or when the key lacks approvals:decide; approve: true (with approvals:decide) approves it in the same request. When it goes out the engine runs the full send gate again (suppression, do-not-contact, lawful basis, quiet hours, sending window). Up front: blocked → 422 send_blocked with reason; the API's hourly cap (500 messages per workspace) → 429 send_cap_reached. Optional: sender_id (an id from GET /senders), send_at (schedule it, up to 30 days ahead; cancel with POST /messages/{id}/cancel) and, for email, html. WhatsApp outside the 24-hour window needs an approved template. Poll the result with GET /messages/{id}, or subscribe to the message.* webhook events.

⚠ messages:sendRole must allow: inbox.replyIdempotency-Key requiredSupports dry_runReaches peopleOperation id: send_message

POST/messages

curl -X POST "https://api.norreach.app/v1/messages" \
  -H "Authorization: Bearer $NORREACH_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "contact_id": "7d1c3b2a-5e4f-4a1b-9c8d-0e1f2a3b4c5d",
  "channel": "whatsapp",
  "template": {
    "name": "follow_up",
    "language": "sv",
    "params": [
      "Maja"
    ]
  }
}'

Send a message

{
  "object": "send_request",
  "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "kind": "message",
  "channel": "email",
  "contact_id": "7d1c3b2a-5e4f-4a1b-9c8d-0e1f2a3b4c5d",
  "status": "awaiting_approval",
  "approval_key": "rule_send:5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "note": "It waits in Approvals until someone says yes."
}

Channel rules

The 24-hour window

Free text can only be sent within 24 hours of the contact's last WhatsApp message to you; outside it, send an approved template (GET /templates lists them with their review state — only APPROVED ones send; params fill its variables in order, one per variable). Free text outside the window answers 422 send_blocked (whatsapp_window_closed); scheduled free text that would go out after the window closes answers whatsapp_window_closes.

Who it's from

Your workspace's verified WhatsApp business number. With several, sender_id (an id from GET /senders of kind whatsapp_number) picks one; a reply inside the window should come from the number the contact wrote to, which is the default.

Quiet hours

WhatsApp messages wait for daytime where the contact is, like texts.

Contacts only

contact_id is a saved contact — there is no field for a typed-in address or number. The contact's own email or phone is used, and only if they have a recorded lawful basis and aren't on your suppression or do-not-contact lists.

Approvals and following it

Every message is an API send: it waits in Approvals when the workspace approves before sending or the key lacks approvals:decide; with approvals:decide, approve: true approves it in the same request. Poll GET /messages/{id} with the answer's id, or subscribe to the message.* webhook events.

Scheduling

Add send_at (RFC 3339 with a zone, in the future, at most 30 days ahead) and nothing goes out before then. The send checks still run at that time, so quiet hours or your sending window can move it to the next allowed moment. It can be approved before then; until it goes out, POST /messages/{id}/cancel stops it.

Many at once

To send to many contacts, use POST /messages/batch: up to 100 items in one request, each with its own result.

More examples

Free text, inside the 24-hour window

JSON

{
  "contact_id": "7d1c3b2a-5e4f-4a1b-9c8d-0e1f2a3b4c5d",
  "channel": "whatsapp",
  "text": "Thanks Maja — Thursday at 10 works."
}

Authorizations

Authorizationstringheaderrequired

Bearer authentication: send Authorization: Bearer <key>, with an API key or an OAuth access token. The key needs the scope messages:send. API keys and scopes

Query parameters

dry_runbooleanquery

Run every check and return what would happen, changing nothing.

Headers

Idempotency-Keystringheaderrequired

Any unique string (≤ 255). The same key with the same request returns the first answer for 24 hours.

Body

application/json

contact_idstring (uuid)required

An id (UUID).

channelenumrequired

One of:emailsmswhatsapp

textstring

The message (required unless template or html).

templateobject

WhatsApp only: an approved template (required outside the 24-hour window).

Show child attributes

template.namestringrequired

An approved WhatsApp template of this workspace (GET /templates).

template.languagestring

Its language code, e.g. sv or en_US (default: the template's own).

template.paramsstring[]

Values for the template's variables, in order.

sender_idstring

Send from this sender: an id from GET /senders — one of the workspace's own connected senders for the channel (an email inbox or domain sender address; for SMS a number that can text — voice-only numbers can't; for WhatsApp the workspace's business number). Default: the workspace's usual sender for the channel.

send_atstring

Schedule it: an RFC 3339 time with a zone (e.g. 2026-11-20T09:00:00+01:00), in the future and at most 30 days ahead. Nothing goes out before it; the send checks still apply at that time, so quiet hours or your sending window can move it to the next allowed moment. It can be approved before then, and cancelled until it goes out (POST /messages/{id}/cancel).

campaign_idstring (uuid)

Send under this campaign's settings (approval mode, sending window).

approveboolean

Approve it now as the key's creator (needs approvals:decide).

Response

202application/json— Send a message

object"send_request"required

idstring (uuid) | nullrequired

The request's id — poll GET /messages/{id} or GET /calls/{id} with it.

kindenumrequired

One of:messagecall

channelstringrequired

contact_idstring (uuid)required

An id (UUID).

statusenumrequired

awaiting_approval = it waits in Approvals; queued = approved, it goes out within a minute through the send checks; scheduled = approved, it goes out at scheduled_for through the send checks.

One of:awaiting_approvalqueuedscheduleddry_run

approval_keystring | nullrequired

The Approvals key (approve it with POST /approvals/{key}/approve).

notestringrequired

wouldobject

Dry run: what would happen.

Show child attributes

would.statusenumrequired

One of:awaiting_approvalqueuedscheduled

scheduled_forstring | null

Messages: not before this time (UTC) — send_at, normalized. Quiet hours and the sending window can move it later.

sender_idstring | null

Messages: the sender asked for (null = the workspace's default for the channel).

Errors

Errors are application/problem+json with a stable code.

Status	Code	Meaning
400	`bad_request`	The request couldn't be read.
400	`unknown_field`	The request has a field this operation doesn't know.
400	`idempotency_key_required`	This operation needs an Idempotency-Key header.
401	`unauthorized`	A valid API key is required.
403	`insufficient_scope`	This API key doesn't have the scope this operation needs.
403	`feature_not_enabled`	The API isn't switched on for this workspace.
403	`role_forbidden`	The key's creator's role can't do this.
404	`not_found`	That doesn't exist.
409	`idempotency_in_progress`	A request with this Idempotency-Key is still running.
409	`outreach_paused`	Outreach is paused for this workspace.
409	`no_sender`	A channel this needs has no connected sender.
413	`too_large`	The request body is too large.
422	`validation_failed`	The request has invalid fields.
422	`idempotency_mismatch`	This Idempotency-Key was used with a different request.
422	`send_blocked`	This can't be sent to this person.
429	`rate_limited`	Too many requests. Slow down and try again.
429	`send_cap_reached`	The workspace's sending limit for now is reached.
500	`server_error`	Something went wrong on our side.
503	`unavailable`	The API isn't available right now. Try again shortly.

POST/messages

curl -X POST "https://api.norreach.app/v1/messages" \
  -H "Authorization: Bearer $NORREACH_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "contact_id": "7d1c3b2a-5e4f-4a1b-9c8d-0e1f2a3b4c5d",
  "channel": "whatsapp",
  "template": {
    "name": "follow_up",
    "language": "sv",
    "params": [
      "Maja"
    ]
  }
}'

Send a message

{
  "object": "send_request",
  "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "kind": "message",
  "channel": "email",
  "contact_id": "7d1c3b2a-5e4f-4a1b-9c8d-0e1f2a3b4c5d",
  "status": "awaiting_approval",
  "approval_key": "rule_send:5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "note": "It waits in Approvals until someone says yes."
}