Sending messages, statuses and groups

Messages

curl -s -X POST -H "Authorization: Bearer omk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"whatsapp","to":"+24177000000","text":"Hello!",
       "mediaUrl":"https://example.com/photo.jpg","mediaType":"image",
       "idempotencyKey":"order-1234-confirmation"}' \
  https://app.omni-manager.com/api/v1/shops/SHOP_ID/messages

Every field but channel and to is optional; either text or mediaUrl is required (422 EMPTY_MESSAGE otherwise). to must be E.164 (+CCxxxxxxxxx). At most one mediaUrl per call — this endpoint's contract is one attachment, always. Repeating a call with the same idempotencyKey returns the original message (200, header X-Idempotent-Replay: true) and never sends twice.

A successful call is 202 with the queued message and the policy verdict that let it through:

{ "id": "…", "status": "queued", "statusUrl": "/api/v1/messages/…",
  "policy": {
    "recipientClass": "known",     // "known" | "cold" | "declared" | "group"
    "warmupDay": 12,
    "caps": { "perDay": 100, "perHour": 16, "coldPerDay": 10, "declaredPerDay": 50 },
    "usage": { "today": 3, "lastHour": 1, "coldToday": 0, "declaredToday": 0 }
  } }

Poll GET /messages/{id} for the terminal state: sent, failed (delivery error — BOT_RESTARTED, WHATSAPP_SESSION_LOST, BOT_SERVICE_UNREACHABLE, or WHATSAPP_NOT_CONNECTED once a message has waited too long for a session that never came back), or rejected (RECIPIENT_NOT_ON_WHATSAPP) — a message never stays queued forever.

Statuses

Body: { caption?, mediaUrl?, mediaType? } ("image" or "video"; either caption or mediaUrl required, caption capped at ~700 characters, one attachment). Subject to its own daily cap, statusesPerDay, distinct from the message caps above — 429 STATUSES_DAILY_CAP_REACHED once spent.

Groups

Each item is { id, name, participantCount, isAdmin, announce, canSend }. canSend is exactly isAdmin — not !announce || isAdmin — because opt-out cannot work per-member inside a group and mere membership is not evidence of consent to broadcast; administering the group is the only signal available, so it is required to send to ANY group, not only "announce" ones. Filter with ?canSend=true, ?minParticipants=50, ?q=name substring.

Sending to a group is the same POST …/messages above with a group JID as to; recipientClass in the policy verdict is then "group", and the group-specific caps in the anti-ban policy article apply instead of the 1:1 ones.

Consented contacts

A tenant can declare that a number is not a stranger, moving it from the cold bucket to declared (its own, usually larger, daily budget — see Messaging & the anti-ban policy).

POST is always a batch, even of one: { "contacts": [{ "phone": "+241…", "note"?, "expiresAt"? }] }. Capped at a batch size and at a genuinely-new-declarations-per-day ceiling (both server-side, not tenant-governed); exceeding either returns 429 DECLARE_BATCH_TOO_LARGE / 429 DECLARE_DAILY_CAP_REACHED without touching the ones that would have fit. A declaration made through this route always records source: "api". DELETE takes { "phone": "+241…" } and revokes (revokedAt set), never hard-deletes — the audit trail stays.

A number that replies STOP / ARRÊT / DÉSABONNER / UNSUBSCRIBE opts out regardless of whether it was ever declared — the next send to it fails 422 RECIPIENT_OPTED_OUT until it writes in again.