Technical reference

Send a message (HTTP)

Page updated: 2026-04-03

Summary

Outbound sends are executed by a linked WhatsApp device you select via deviceId. This is WAPing’s platform API — not Meta’s template submission or BSP-hosted Cloud API path.

Canonical reference: Hostnames, path prefixes, JSON field names, and changelog are maintained on docs.waping.app. Examples below are illustrative — align your integration with the live OpenAPI/reference there.

Connection model: WAPing links WhatsApp through a QR session (similar in concept to WhatsApp Web). This is not Meta’s WhatsApp Business Cloud API product, and you do not complete Meta BSP / Cloud API onboarding inside WAPing for this path.

Purpose

Describe the minimum fields for a text send and how retries interact with idempotency.

Core fields

deviceId — which QR-linked session sends the message.
to — recipient in E.164 (e.g. +15551234567).
type + payload — text, media, or structured payloads as supported by the canonical reference.

Workflow

1) Validate session

Ensure the device is connected in the dashboard or via API; disconnected sessions return session errors (see Errors).

2) Send with idempotency

Use a stable Idempotency-Key per logical message. Retries must reuse the same key and body.

3) Observe delivery

Track delivery and read states via message log and webhook events (see Webhooks).

Request example

Text message (illustrative)

POST /v1/messages HTTP/1.1
Authorization: Bearer {WAPING_API_KEY{'}'}
Content-Type: application/json
Idempotency-Key: 2a1b3c4d-5e6f-7890-abcd-ef1234567890

{
  "deviceId": "dev_123",
  "to": "+15551234567",
  "type": "text",
  "text": { "body": "Your order #12345 is confirmed." }
}

Response example

200 OK

{
  "id": "msg_abc123",
  "status": "queued",
  "deviceId": "dev_123"
}

Errors

400 — validation (bad E.164, missing fields, unsupported payload for device state).
409 — idempotency conflict (same key, different body).
429 — rate limited — see Rate limits.
4xx session — SESSION_DISCONNECTED or similar when QR session is not usable.

Limits

Monthly outbound message quotas and per-plan caps apply before WhatsApp-level constraints. See Pricing and your workspace usage.

Caveats

Delivery is subject to WhatsApp and recipient policy; WAPing surfaces states in logs and webhooks — do not assume instant delivery.
Do not map Meta Cloud API “template” concepts directly; use WAPing’s documented payload types.
Media size and MIME restrictions follow WhatsApp client rules — confirm in the canonical reference.