{"templateId":"openapi_docs","sharedDataIds":{"openAPIDocsStore":"oas-apis/omnichannel.yaml","sidebar":"sidebar-sidebar.yaml__apis_omnichannel"},"props":{"definitionId":"apis/omnichannel.yaml","dynamicMarkdocComponents":[],"baseSlug":"/apis/omnichannel","seo":{"title":"eCommunicate Omnichannel Integration API","siteUrl":"https://docs.ecommunicate.co.za","keywords":["eCommunicate API","WhatsApp Business API","SMS API","omnichannel messaging","WhatsApp templates","messaging platform","South Africa messaging API"],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"itemId":"","disableAutoScroll":true,"metadata":{"type":"openapi","title":"eCommunicate Omnichannel Integration API","description":"# Overview\nThe eCommunicate Omnichannel Integration API lets you send and receive messages across **WhatsApp Cloud**, **WhatsApp Lite**, and **SMS** from a single platform. Use it to send template notifications, handle live customer conversations, manage contacts, track delivery, and download reports.\n\n## Quick start\n\n1. **Get your API key** — call `POST /authenticate/retrieveApiKey` with your email, password, and client reference. No existing key required.\n2. **Send a message** — `POST /v2/messages` with your template and recipient. The response returns a `requestId` for tracking.\n3. **Track delivery** — configure a [webhook](#tag/Webhook-Configuration) or poll `GET /message/status/gstid`.\n\n## Authentication\n\nEvery request requires your **Developer Key** (a UUID) in the `Authorization` header. No `Bearer` prefix — pass the key directly.\n\n```\nAuthorization: a1b2c3d4-e5f6-7890-abcd-ef1234567890\n```\n\n## Platform comparison\n\n| Capability | WhatsApp Cloud | WhatsApp Lite | SMS |\n|---|---|---|---|\n| Template messages | Yes | Yes | — |\n| Session (chat) messages | Yes (24-hour window) | Yes (any time) | — |\n| SMS fallback | Yes | Yes | — |\n| QR code connection | — | Yes | — |\n| Groups | — | Yes | — |\n| Contacts sync | — | Yes | — |\n| Direct SMS | — | — | Yes |\n\n## Messaging rules\n\n- **Notification messages** require `templateName` and `templateId`. Templates must be approved by Meta before use.\n- **Body parameters** — if your template body contains `{{1}}`, `{{2}}`, etc., include a `body` component with matching parameters.\n- **Media templates** require a `header` component specifying the format (`IMAGE`, `VIDEO`, `DOCUMENT`) and a media URL.\n- **Button templates** require a `button` component with the button index and parameter values.\n- **Carousel templates** require a `carousel` component containing a `cards` array, each with its own header, body, and buttons.\n- **Chat messages** (`messageType: CHAT`) can only be sent within the 24-hour customer service window on WhatsApp Cloud. WhatsApp Lite has no window restriction.\n\n## SMS encoding\n\n| Encoding | Flag | Chars per part | Multipart chars | Best for |\n|---|---|---|---|---|\n| GSM 7-bit | `unicode: false` | 160 | 153 | English, basic Latin |\n| Unicode | `unicode: true` | 70 | 67 | Emoji, non-Latin scripts |\n\n## Webhooks\n\nConfigure webhook URLs to receive real-time events:\n- **Incoming messages** (`incomingMessageURL`) — customer messages with text, media, location, buttons, reactions, or contacts.\n- **Status updates** (`statusUpdateURL`) — delivery receipts tracking the lifecycle: `ACCEPTED` → `SENT` → `DELIVERED` → `READ` → `PLAYED` (or `FAILED`).\n- **Session status** (`sessionStatusURL`) — WhatsApp Lite connection state changes.\n- **Platform events** (`eventWebhookURL`) — template approvals/rejections, quality rating changes, user preferences, number migrations.\n- **Chatbot conversations** (`chatbotWebhookURL`) — chatbot conversation events with chat participant context (participant id, conversation status, agent assignment). Optionally include outgoing bot replies and/or stop emitting once a chat is assigned to a human agent.\n\nEach configuration applies at one of two scopes: a **client default** (`whatsAppNumberId` omitted) covering every WhatsApp number under your client, or a **per-number override** (`whatsAppNumberId` set) targeting one specific number. The platform resolves overrides first and falls back to the default at dispatch time.\n\n## WhatsApp account and number health\n\n> **Applies to: WhatsApp Cloud API only.** WhatsApp Lite numbers are not subject to Meta's quality rating system, messaging tiers, or template review process.\n\nMaintaining good account health is critical for reliable message delivery. Meta monitors how recipients interact with your messages and assigns quality ratings that directly affect your sending capacity.\n\n### Summary of proactive steps to prevent your marketing WhatsApp number from being blocked\n\nTake these steps to protect your WhatsApp number's sending ability:\n\n1. **Set up quick replies for opt-out** — Configure a quick reply that allows recipients to indicate they want to stop receiving marketing messages. When you receive an opt-out request, immediately remove the recipient's WhatsApp number from the marketing campaign. The goal is to handle opt-outs before the recipient clicks \"Block\" or reports the message to Meta, which could result in Meta restricting or blocking your WhatsApp number from sending messages.\n\n2. **Monitor the `user_preferences` webhook** — Continuously check the `user_preferences` webhook for changes to the `PREFERENCE` field. Possible values:\n   - `stop` — The WhatsApp user has opted to stop receiving marketing messages from you.\n   - `resume` — The WhatsApp user has opted to resume receiving marketing messages from you.\n\n   When a `stop` preference is received, immediately remove the recipient from all active marketing campaigns. See Meta reference: [user_preferences webhook reference](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/user_preferences).\n\n3. **Monitor the `phone_number_quality_update` webhook** — Track quality updates for your WhatsApp marketing number. You may receive downgrades where `MAX_DAILY_MESSAGES_LIMIT` drops as low as `TIER_50` (a messaging limit of 50 recipients). After a downgrade, quality can recover and upgrade to `TIER_100K` (100,000 recipients) or `TIER_UNLIMITED`. If you receive a downgrade, urgently verify that all recipients who have indicated they do not want to receive WhatsApp messages have been removed from your campaigns. See Meta reference: [phone_number_quality_update webhook reference](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/phone_number_quality_update).\n\n### Quality ratings\n\nEach WhatsApp number has a quality rating based on recipient feedback:\n\n| Rating | Meaning | Impact |\n|---|---|---|\n| **High** | Little to no recipient dissatisfaction | Full sending capacity |\n| **Medium** | Some recipient dissatisfaction detected | Monitor and adjust content |\n| **Low** | High recipient dissatisfaction | Flagged status — limited ability to start new conversations |\n\nWhen a number drops to **Low** quality, it enters a **Flagged** status. If quality improves within 7 days, the status resets to **Connected**. Continued poor quality may result in further restrictions or suspension.\n\nQuality ratings and messaging limits are applied **per phone number**, but policy violations on any number affect the entire WhatsApp Business Account (WABA).\n\n### Messaging limit tiers\n\nYour messaging limit determines how many unique customers you can message within a 24-hour period:\n\n| Tier | Unique customers per 24 hours |\n|---|---|\n| `TIER_1K` | 1,000 |\n| `TIER_10K` | 10,000 |\n| `TIER_100K` | 100,000 |\n\nMeta automatically increases your tier when you consistently send high-quality messages. Conversely, poor quality ratings can reduce your tier.\n\n### Monitoring health\n\nUse the following to monitor your number and template health:\n\n- **Number Health** — `GET /payless4messaging-service/WhatsApp/WhatsAppClientNumbers/getForCurrentLoginUser` returns `qualityRating`, `messagingLimitTier`, and `lastQualityUpdateTime` for each number.\n- **Template health** — `GET /whatsapp-api-service/whatsAppTemplates/getWhatsAppClientTemplates` returns the quality status for each template per number.\n- **Webhooks** — configure an `eventWebhookURL` to receive real-time `phone_number_quality_update` and `message_template_status_update` events.\n- **Meta Business Manager** — check the Phone Number Quality and Template Quality columns directly in the WhatsApp Manager.\n\n### Template quality best practices\n\nMeta reviews every template before approval. To maintain high template quality:\n\n- **Be explicit** — the recipient must have opted in to receive the message.\n- **Be timely** — send shortly after user engagement, not weeks later.\n- **Be relevant** — personalise content, keep it useful, and include a clear call to action.\n- **Use descriptive names** — name templates like `order_confirmation` or `appointment_reminder`, not `template_01`.\n- **Avoid common rejection reasons** — vague content, incorrect language tags, overuse of emojis or excessive promotional tone, and malformed parameters (`{{1}}`, `{{2}}`).\n- **Choose the correct category** — do not mix marketing and utility content in a single template.\n\n### Opt-out compliance for marketing templates\n\nMarketing templates **must** include an opt-out mechanism. This is a Meta policy requirement that directly impacts your account health.\n\n**Requirements:**\n- Include a **quick-reply opt-out button** (e.g. \"Stop promotions\") in your marketing templates, especially for:\n  - The first message of a new campaign\n  - Messages sent after a long gap in marketing communication\n  - Messages sent to inactive or re-engaged users\n- **Honour opt-out requests immediately** across all numbers on your account.\n\n**Recognised opt-out keywords:** When a recipient replies with any of the following words, eCommunicate automatically treats it as an opt-out: `STOP`, `END`, `CANCEL`, `UNSUBSCRIBE`, `QUIT`.\n\n**How eCommunicate handles opt-outs:**\n- When a recipient opts out, eCommunicate **automatically blocks that number** — no further marketing messages will be sent to it.\n- You can query blocked numbers via `GET /payless4messaging-service/WhatsApp/WhatsAppBlockedNumber/getForCurrentLoginUser` to see all opt-out blocks.\n- If a recipient opts back in, remove them from the blocked list to resume messaging.\n\n**Why this matters:**\n- **Reduces block rate** — recipients who can opt out gracefully are far less likely to block or report your number, which is the primary signal Meta uses to downgrade quality ratings.\n- Prevents campaigns from being flagged or paused by Meta.\n- Enables faster messaging limit tier upgrades.\n- Ensures compliance with Meta's messaging policies.\n\n### Account ownership\n\nThe WABA must be owned by the business sending the messages. Do not add unrelated businesses to your Meta Business Portfolio. Violations result in account restriction or suspension.\n\n## Rate limits & pagination\n\nAPI rate limits return `429 Too Many Requests` — implement exponential backoff. All list endpoints use page-based pagination with `page` (zero-based) and `size` parameters. See the [Rate Limits guide](../guides/rate-limits.md) for details.\n\n## Support\n\nContact [support@ecommunicate.co.za](mailto:support@ecommunicate.co.za) for account issues, rate limit increases, or integration help. Always include the `requestId` from API responses when reporting issues.\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"docs.ecommunicate.co.za","port":4000,"ipAddress":"216.73.217.36"},"lang":"default_locale","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"main"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/apis/omnichannel","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}