# eCommunicate Omnichannel Integration API # Overview The 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. ## Quick start 1. **Get your API key** — call `POST /authenticate/retrieveApiKey` with your email, password, and client reference. No existing key required. 2. **Send a message** — `POST /v2/messages` with your template and recipient. The response returns a `requestId` for tracking. 3. **Track delivery** — configure a [webhook](#tag/Webhook-Configuration) or poll `GET /message/status/gstid`. ## Authentication Every request requires your **Developer Key** (a UUID) in the `Authorization` header. No `Bearer` prefix — pass the key directly. ``` Authorization: a1b2c3d4-e5f6-7890-abcd-ef1234567890 ``` ## Platform comparison | Capability | WhatsApp Cloud | WhatsApp Lite | SMS | |---|---|---|---| | Template messages | Yes | Yes | — | | Session (chat) messages | Yes (24-hour window) | Yes (any time) | — | | SMS fallback | Yes | Yes | — | | QR code connection | — | Yes | — | | Groups | — | Yes | — | | Contacts sync | — | Yes | — | | Direct SMS | — | — | Yes | ## Messaging rules - **Notification messages** require `templateName` and `templateId`. Templates must be approved by Meta before use. - **Body parameters** — if your template body contains `{{1}}`, `{{2}}`, etc., include a `body` component with matching parameters. - **Media templates** require a `header` component specifying the format (`IMAGE`, `VIDEO`, `DOCUMENT`) and a media URL. - **Button templates** require a `button` component with the button index and parameter values. - **Carousel templates** require a `carousel` component containing a `cards` array, each with its own header, body, and buttons. - **Chat messages** (`messageType: CHAT`) can only be sent within the 24-hour customer service window on WhatsApp Cloud. WhatsApp Lite has no window restriction. ## SMS encoding | Encoding | Flag | Chars per part | Multipart chars | Best for | |---|---|---|---|---| | GSM 7-bit | `unicode: false` | 160 | 153 | English, basic Latin | | Unicode | `unicode: true` | 70 | 67 | Emoji, non-Latin scripts | ## Webhooks Configure webhook URLs to receive real-time events: - **Incoming messages** (`incomingMessageURL`) — customer messages with text, media, location, buttons, reactions, or contacts. - **Status updates** (`statusUpdateURL`) — delivery receipts tracking the lifecycle: `ACCEPTED` → `SENT` → `DELIVERED` → `READ` → `PLAYED` (or `FAILED`). - **Session status** (`sessionStatusURL`) — WhatsApp Lite connection state changes. - **Platform events** (`eventWebhookURL`) — template approvals/rejections, quality rating changes, user preferences, number migrations. - **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. Each 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. ## WhatsApp account and number health > **Applies to: WhatsApp Cloud API only.** WhatsApp Lite numbers are not subject to Meta's quality rating system, messaging tiers, or template review process. Maintaining 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. ### Summary of proactive steps to prevent your marketing WhatsApp number from being blocked Take these steps to protect your WhatsApp number's sending ability: 1. **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. 2. **Monitor the `user_preferences` webhook** — Continuously check the `user_preferences` webhook for changes to the `PREFERENCE` field. Possible values: - `stop` — The WhatsApp user has opted to stop receiving marketing messages from you. - `resume` — The WhatsApp user has opted to resume receiving marketing messages from you. 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). 3. **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). ### Quality ratings Each WhatsApp number has a quality rating based on recipient feedback: | Rating | Meaning | Impact | |---|---|---| | **High** | Little to no recipient dissatisfaction | Full sending capacity | | **Medium** | Some recipient dissatisfaction detected | Monitor and adjust content | | **Low** | High recipient dissatisfaction | Flagged status — limited ability to start new conversations | When 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. Quality ratings and messaging limits are applied **per phone number**, but policy violations on any number affect the entire WhatsApp Business Account (WABA). ### Messaging limit tiers Your messaging limit determines how many unique customers you can message within a 24-hour period: | Tier | Unique customers per 24 hours | |---|---| | `TIER_1K` | 1,000 | | `TIER_10K` | 10,000 | | `TIER_100K` | 100,000 | Meta automatically increases your tier when you consistently send high-quality messages. Conversely, poor quality ratings can reduce your tier. ### Monitoring health Use the following to monitor your number and template health: - **Number Health** — `GET /payless4messaging-service/WhatsApp/WhatsAppClientNumbers/getForCurrentLoginUser` returns `qualityRating`, `messagingLimitTier`, and `lastQualityUpdateTime` for each number. - **Template health** — `GET /whatsapp-api-service/whatsAppTemplates/getWhatsAppClientTemplates` returns the quality status for each template per number. - **Webhooks** — configure an `eventWebhookURL` to receive real-time `phone_number_quality_update` and `message_template_status_update` events. - **Meta Business Manager** — check the Phone Number Quality and Template Quality columns directly in the WhatsApp Manager. ### Template quality best practices Meta reviews every template before approval. To maintain high template quality: - **Be explicit** — the recipient must have opted in to receive the message. - **Be timely** — send shortly after user engagement, not weeks later. - **Be relevant** — personalise content, keep it useful, and include a clear call to action. - **Use descriptive names** — name templates like `order_confirmation` or `appointment_reminder`, not `template_01`. - **Avoid common rejection reasons** — vague content, incorrect language tags, overuse of emojis or excessive promotional tone, and malformed parameters (`{{1}}`, `{{2}}`). - **Choose the correct category** — do not mix marketing and utility content in a single template. ### Opt-out compliance for marketing templates Marketing templates **must** include an opt-out mechanism. This is a Meta policy requirement that directly impacts your account health. **Requirements:** - Include a **quick-reply opt-out button** (e.g. "Stop promotions") in your marketing templates, especially for: - The first message of a new campaign - Messages sent after a long gap in marketing communication - Messages sent to inactive or re-engaged users - **Honour opt-out requests immediately** across all numbers on your account. **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`. **How eCommunicate handles opt-outs:** - When a recipient opts out, eCommunicate **automatically blocks that number** — no further marketing messages will be sent to it. - You can query blocked numbers via `GET /payless4messaging-service/WhatsApp/WhatsAppBlockedNumber/getForCurrentLoginUser` to see all opt-out blocks. - If a recipient opts back in, remove them from the blocked list to resume messaging. **Why this matters:** - **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. - Prevents campaigns from being flagged or paused by Meta. - Enables faster messaging limit tier upgrades. - Ensures compliance with Meta's messaging policies. ### Account ownership The 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. ## Rate limits & pagination API 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. ## Support Contact [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. Version: 3.0.0 License: Apache 2.0 ## Servers Live — WhatsApp Cloud Server URL ``` https://api.payless4messaging.com ``` Live — WhatsApp Lite Server URL ``` https://api.payless4messages.com ``` ## Security ### apikeyAuth Developer API key provided by eCommunicate. Type: apiKey In: header Name: Authorization ## Download OpenAPI description [eCommunicate Omnichannel Integration API](https://docs.ecommunicate.co.za/_bundle/apis/omnichannel.yaml) ## Client Management Retrieve your client profile, create child client accounts, and configure account-level settings like SMS fallback and POPIA compliance. Child clients inherit the parent's WhatsApp provider but have independent balances and configurations. ### Get my client - [GET /payless4messaging-service/WhatsApp/api/v1/clients/me](https://docs.ecommunicate.co.za/apis/omnichannel/client-management/getmyclient.md): Returns the authenticated caller's own client as a ClientResponse — reference, display name, balances, country, and feature flags, with no credentials. The SMS gateway password is never returned. The client is taken from your authentication context. ### List child clients (v1) - [GET /payless4messaging-service/WhatsApp/api/v1/clients/{clientRef}/children](https://docs.ecommunicate.co.za/apis/omnichannel/client-management/listchildren.md): Returns a paginated list of the child clients belonging to the given parent, as credential-free ClientResponse records. Use searchString to filter by client reference or email. ### Create a child client (v1) - [POST /payless4messaging-service/WhatsApp/api/v1/clients/{clientRef}/children](https://docs.ecommunicate.co.za/apis/omnichannel/client-management/createchild.md): Creates a client under the parent named in the path. Anything the request leaves blank is inherited from the parent — account type, pricing model, country, timezone, and opening balances. ### Configure SMS fallback (v1) - [PUT /payless4messaging-service/WhatsApp/api/v1/clients/{clientRef}/sms-fallback](https://docs.ecommunicate.co.za/apis/omnichannel/client-management/setsmsfallback.md): Configures SMS fallback for the given client. When enabled, an SMS is sent automatically if the recipient is not on WhatsApp or WhatsApp delivery fails. The gateway password is write-only: it is never returned by any endpoint, so leave smsPassword out (or blank) to keep the stored one, and supply it only to change it. ### Set POPIA compliance (v1) - [PUT /payless4messaging-service/WhatsApp/api/v1/clients/me/popia-compliance](https://docs.ecommunicate.co.za/apis/omnichannel/client-management/setpopiacompliance.md): Enables or disables POPIA (Protection of Personal Information Act) compliance for your own account. When enabled, the platform enforces South African data protection requirements on message handling and contact storage. ### Get current client profile (deprecated) - [GET /payless4messaging-service/WhatsApp/Client/getForCurrentLoginUser](https://docs.ecommunicate.co.za/apis/omnichannel/client-management/getcurrentclient.md): Deprecated. Returns the full client record, including the SMS gateway password. Use Get my client (GET /api/v1/clients/me), which returns a ClientResponse carrying no credentials. ### Create a child client (deprecated) - [POST /payless4messaging-service/WhatsApp/Client/createChildClient](https://docs.ecommunicate.co.za/apis/omnichannel/client-management/createchildclient.md): Deprecated. Takes the parent in the request body. Use Create a child client (v1) (POST /api/v1/clients/{clientRef}/children), which takes the parent from the path and returns a ClientResponse. ### Get child clients (deprecated) - [GET /payless4messaging-service/WhatsApp/Client/getChildClient](https://docs.ecommunicate.co.za/apis/omnichannel/client-management/getchildclients.md): Deprecated. Takes the parent as a query parameter and returns full client records. Use List child clients (v1) (GET /api/v1/clients/{clientRef}/children), which takes the parent from the path and returns credential-free ClientResponse records. ### Enable or disable SMS fallback (deprecated) - [POST /payless4messaging-service/WhatsApp/Client/updateClientSMSFallback](https://docs.ecommunicate.co.za/apis/omnichannel/client-management/updatesmsfallback.md): Deprecated. Takes a whole client object, so an omitted smsPassword blanks the stored one. Use Configure SMS fallback (v1) (PUT /api/v1/clients/{clientRef}/sms-fallback), where the password is write-only: leave it out to keep the stored one. ### Update POPIA compliance setting (deprecated) - [POST /payless4messaging-service/WhatsApp/Client/updatePopiaCompliance](https://docs.ecommunicate.co.za/apis/omnichannel/client-management/updatepopiacompliance.md): Deprecated. Accepts a whole client object but only ever updates your own account, whatever client is in the payload. Use Set POPIA compliance (v1) (PUT /api/v1/clients/me/popia-compliance), whose path says so. ## User Management Create, update, and manage system users within your organization. Users can be admins, supervisors, or agents. Manage agent availability for live chat assignment, set concurrent chat limits, and handle password changes. Each user belongs to a client and can be assigned to teams. ### Get my profile - [GET /payless4messaging-service/WhatsApp/api/v1/users/me](https://docs.ecommunicate.co.za/apis/omnichannel/user-management/getme.md): Returns the authenticated caller's own profile as a credential-free UserResponse. ### List your organization's user - [GET /payless4messaging-service/WhatsApp/api/v1/users](https://docs.ecommunicate.co.za/apis/omnichannel/user-management/listclientusers.md): Returns every user in the authenticated client's organization as a lean summary — id, name, email, role, live-chat role, avatar, and availability — with no credentials or secrets. Use this to populate transfer/assignment pickers and agent lists. The client is taken from your authentication context. ### Create a user - [POST /payless4messaging-service/WhatsApp/api/v1/users](https://docs.ecommunicate.co.za/apis/omnichannel/user-management/createuser.md): Create an organization user. Takes no password — a one-time temporary password is generated and returned once in the response; the user must set their own password on first login. The client is taken from clientRef, or your auth context when omitted. ### Update a user - [PUT /payless4messaging-service/WhatsApp/api/v1/users](https://docs.ecommunicate.co.za/apis/omnichannel/user-management/updateuser.md): Update an organization user's profile, identified by id. Carries no credentials and returns a credential-free UserResponse. ### Delete a user - [DELETE /payless4messaging-service/WhatsApp/api/v1/users/{id}](https://docs.ecommunicate.co.za/apis/omnichannel/user-management/deleteuser.md): Soft-deletes an organization user, identified by id: the user is disabled, signed out, and removed from any teams, but the record is retained. Carries no credentials. ### List users (paginated) - [GET /payless4messaging-service/WhatsApp/api/v1/users/page](https://docs.ecommunicate.co.za/apis/omnichannel/user-management/getuserspage.md): Retrieve a paginated list of a client's users as credential-free UserResponse records. ### Change availability - [PUT /payless4messaging-service/WhatsApp/api/v1/users/availability](https://docs.ecommunicate.co.za/apis/omnichannel/user-management/changeavailability.md): Toggle the authenticated agent's online/offline status; returns a credential-free UserResponse. ### Set agent chat limit - [PUT /payless4messaging-service/WhatsApp/api/v1/users/agent-chat-limit](https://docs.ecommunicate.co.za/apis/omnichannel/user-management/setagentchatlimit.md): Set the maximum number of concurrent chats an agent can handle for the given client. ### Change my password - [POST /payless4messaging-service/WhatsApp/api/v1/users/me/password/change](https://docs.ecommunicate.co.za/apis/omnichannel/user-management/changemypassword.md): Change the authenticated caller's own password. Requires old password, new password, and confirmation. ### Get my WhatsApp credits - [GET /payless4messaging-service/WhatsApp/api/v1/users/me/credits](https://docs.ecommunicate.co.za/apis/omnichannel/user-management/getmycredits.md): Retrieve the WhatsApp credit balance for the authenticated caller. ### Create a system user (deprecated) - [POST /payless4messaging-service/WhatsApp/SystemUsers](https://docs.ecommunicate.co.za/apis/omnichannel/user-management/createsystemuser.md): Deprecated. Accepts and returns credential-bearing SystemUser fields. Use Create a user (POST /api/v1/users), which takes no password and returns a one-time temporary password instead. ### Update a system user (deprecated) - [PUT /payless4messaging-service/WhatsApp/SystemUsers](https://docs.ecommunicate.co.za/apis/omnichannel/user-management/updatesystemuser.md): Deprecated. Accepts and returns credential-bearing SystemUser fields. Use Update a user (PUT /api/v1/users), which is identified by id, carries no credentials, and returns a UserResponse. ### Get current logged-in user (deprecated) - [GET /payless4messaging-service/WhatsApp/SystemUsers/getCurrentLoginSystemUser](https://docs.ecommunicate.co.za/apis/omnichannel/user-management/getcurrentuser.md): Deprecated. Returns credential-bearing SystemUser fields. Use Get my profile (GET /api/v1/users/me), which returns a credential-free UserResponse. ### Get all users in your organization (supervisor-only) (deprecated) - [GET /payless4messaging-service/WhatsApp/SystemUsers/getCurrentClientUsers](https://docs.ecommunicate.co.za/apis/omnichannel/user-management/getclientusers.md): Supervisor-only. Returns the full SystemUser records for the client (including credential-bearing fields), so it is restricted to callers with the supervisor role and returns 403 otherwise. For agent-facing user lists use List your organization's users, which returns a lean, credential-free UserSummary[]. ### Get users for a specific client (paginated) (deprecated) - [GET /payless4messaging-service/WhatsApp/SystemUsers/getUsersForClient](https://docs.ecommunicate.co.za/apis/omnichannel/user-management/getusersforclient.md): Deprecated. Returns credential-bearing SystemUser records. Use List users (paginated) (GET /api/v1/users/page), which returns credential-free UserResponse records. ### Change agent availability status (deprecated) - [PUT /payless4messaging-service/WhatsApp/SystemUsers/changeAvailableStatus](https://docs.ecommunicate.co.za/apis/omnichannel/user-management/changeavailabilitystatus.md): Deprecated. Returns credential-bearing SystemUser fields. Use Change availability (PUT /api/v1/users/availability), which returns a credential-free UserResponse. ### Update agent chat limit (deprecated) - [PUT /payless4messaging-service/WhatsApp/SystemUsers/updateAgentChatLimit](https://docs.ecommunicate.co.za/apis/omnichannel/user-management/updateagentchatlimit.md): Deprecated. Use Set agent chat limit (PUT /api/v1/users/agent-chat-limit). Behaviour is identical. ### Change password (deprecated) - [POST /payless4messaging-service/WhatsApp/SystemUsers/changePassword](https://docs.ecommunicate.co.za/apis/omnichannel/user-management/changepassword.md): Deprecated. Use Change my password (POST /api/v1/users/me/password/change). Behaviour is identical. ### Get WhatsApp credits for current user (deprecated) - [GET /payless4messaging-service/WhatsApp/SystemUsers/getWhatsAppCreditsForCurrentLoginUser](https://docs.ecommunicate.co.za/apis/omnichannel/user-management/getwhatsappcreditsforcurrentloginuser.md): Deprecated. Use Get my WhatsApp credits (GET /api/v1/users/me/credits). Behaviour is identical. ## API Key Management Retrieve, rotate, or bootstrap your Developer API key. Use the credential-based `retrieveApiKey` endpoint to obtain your key without needing an existing one — ideal for first-time setup. The API key is a UUID used in the `Authorization` header for all API requests. Generating a new key immediately invalidates the previous key — update all integrations before regenerating. ### Retrieve API key with credentials - [POST /payless4messaging-service/WhatsApp/authenticate/retrieveApiKey](https://docs.ecommunicate.co.za/apis/omnichannel/api-key-management/retrieveapikey.md): Retrieve your Developer API key by authenticating with your account credentials. This is the recommended first step for new integrations — it does not require an existing API key. Send your account email, password, and client reference to receive your API key. Use the returned key in the Authorization header for all subsequent API requests. ### Generate a new API key - [POST /payless4messaging-service/WhatsApp/SystemUsers/generateAPIKey](https://docs.ecommunicate.co.za/apis/omnichannel/api-key-management/generateapikey.md): Generates a new Developer API key. Warning: This invalidates the previous key immediately. All integrations using the old key will stop working. ## Team Management Organize agents into teams for live chat routing. Create teams, assign supervisors, add or remove members, and query team composition. Teams control how incoming conversations are distributed across agents and enable supervisor oversight of agent activity. ### Create a team - [POST /pl4chat-service/team/add](https://docs.ecommunicate.co.za/apis/omnichannel/team-management/createteam.md): Create a new team for organizing agents. Specify the team name, supervisor, and client reference. ### Update a team - [POST /pl4chat-service/team/update](https://docs.ecommunicate.co.za/apis/omnichannel/team-management/updateteam.md): Update a team's name, supervisor, or other properties. ### Remove a team - [POST /pl4chat-service/team/remove](https://docs.ecommunicate.co.za/apis/omnichannel/team-management/removeteam.md): Permanently delete a team. Members are unassigned but their user accounts are not affected. ### Get all teams for a client - [GET /pl4chat-service/team/list/{clientRef}](https://docs.ecommunicate.co.za/apis/omnichannel/team-management/getteams.md): Retrieve all teams for a client reference. ### Get team by ID - [GET /pl4chat-service/team/{id}](https://docs.ecommunicate.co.za/apis/omnichannel/team-management/getteambyid.md): Retrieve a single team's details by its UUID. ### Get team members - [GET /pl4chat-service/team/members/{teamId}](https://docs.ecommunicate.co.za/apis/omnichannel/team-management/getteammembers.md): Retrieve all members assigned to a specific team. ### Get available members (not yet in team) - [GET /pl4chat-service/team/free-members/{clientRef}/{teamId}](https://docs.ecommunicate.co.za/apis/omnichannel/team-management/getfreemembersforteam.md): List users who are not currently assigned to the specified team. Useful for populating an 'add member' interface. ### Add member to team - [POST /pl4chat-service/team/add-member](https://docs.ecommunicate.co.za/apis/omnichannel/team-management/addteammember.md): Assign a user to a team. ### Remove member from team - [POST /pl4chat-service/team/remove-member](https://docs.ecommunicate.co.za/apis/omnichannel/team-management/removeteammember.md): Remove a user from a team without deleting their account. ### Get team names - [GET /pl4chat-service/team/names/{clientRef}](https://docs.ecommunicate.co.za/apis/omnichannel/team-management/getteamnames.md): Retrieve a lightweight list of team names for a client. Useful for populating dropdown selectors. ### Get all supervisors - [GET /pl4chat-service/team/supervisors/{clientRef}](https://docs.ecommunicate.co.za/apis/omnichannel/team-management/getsupervisors.md): Retrieve all users with the supervisor role for a client. ### Get all agents - [GET /pl4chat-service/team/agents/{clientRef}](https://docs.ecommunicate.co.za/apis/omnichannel/team-management/getagents.md): Retrieve all users with the agent role for a client. ## Balance & Billing Check your current WhatsApp messaging costs, SMS credit balance, and balance transaction history. Use these endpoints to monitor spend, verify credit availability before campaigns, and audit billing records. ### Get message costs - [GET /payless4messaging-service/WhatsApp/Billing/getCostForCurrentLoginUser](https://docs.ecommunicate.co.za/apis/omnichannel/balance-and-billing/getbillingcosts.md): Retrieve the current messaging cost configuration for your account, including per-message rates by channel and message type. ### Check SMS balance - [GET /whatsapp-api-service/SMSBalance/getClientBalance](https://docs.ecommunicate.co.za/apis/omnichannel/balance-and-billing/getsmsbalance.md): Check your current SMS credit balance. Use this before sending SMS campaigns to verify sufficient credits are available. ### Get balance history - [GET /payless4messaging-service/WhatsApp/WhatsAppClientBalanceHistory/getForCurrentClient](https://docs.ecommunicate.co.za/apis/omnichannel/balance-and-billing/getbalancehistory.md): Retrieve a paginated history of balance transactions including top-ups, message costs, and adjustments. ## Messaging Send messages through WhatsApp or SMS. The unified endpoint (`POST /v2/messages`) routes based on the `channel` field, or use dedicated channel endpoints for WhatsApp and SMS separately. Supports template notifications, session (chat) messages, media attachments, and SMS fallback. All send operations are asynchronous — a `202 Accepted` response means the message is queued for processing. ### Send message (Unified endpoint) - [POST /whatsapp-api-service/v2/messages](https://docs.ecommunicate.co.za/apis/omnichannel/messaging/sendunifiedmessage.md): The primary messaging endpoint — routes to WhatsApp or SMS based on the channel field in the request body. Set channel to WHATSAPP for template notifications and session messages, or SMS for direct SMS delivery. This is an asynchronous endpoint. A 202 Accepted response means the message is queued for processing, not yet delivered. Track delivery via webhooks or the message status endpoints. WhatsApp notification messages require an approved template (templateName + templateId). Chat messages (messageType: CHAT) can be sent within the 24-hour customer service window. SMS messages are sent immediately through the configured SMS gateway. Recipient numbers (to) must be in international format — country code plus subscriber number, with an optional leading + (e.g. +27821234567 or 27821234567 for South Africa). Local-format numbers starting with 0 (e.g. 0821234567) are not valid. ### Send WhatsApp messages - [POST /whatsapp-api-service/v2/channels/whatsapp](https://docs.ecommunicate.co.za/apis/omnichannel/messaging/sendwhatsapp.md): Send WhatsApp template notifications and session (chat) messages directly to the WhatsApp channel. Use this endpoint when you only need WhatsApp delivery without the unified routing layer. Template messages (messageType: NOTIFICATION) require an approved template with templateName and templateId. Include body, header, or button components as needed for parameter substitution. Session messages (messageType: CHAT) support text and media attachments. On WhatsApp Cloud, these can only be sent within the 24-hour customer service window after the customer last messaged you. On WhatsApp Lite, session messages can be sent at any time. Recipient numbers (to) must be in international format — country code plus subscriber number, with an optional leading + (e.g. +27821234567 or 27821234567 for South Africa). Local-format numbers starting with 0 (e.g. 0821234567) are not valid. This is an asynchronous endpoint — 202 Accepted means queued, not delivered. ### Send SMS message - [POST /whatsapp-api-service/v2/channels/sms](https://docs.ecommunicate.co.za/apis/omnichannel/messaging/sendsms.md): Send SMS messages directly through the SMS gateway. Each message in the messages array specifies a recipient, text content, and optional tracking ID (ctId). Set unicode: true for messages containing emoji or non-Latin characters. This is an asynchronous endpoint — 202 Accepted means queued, not delivered. ## WhatsApp Number Management View the WhatsApp numbers assigned to your account. Each number has its own provider configuration, quality rating, and messaging tier. Use these endpoints to list numbers with pagination or retrieve all numbers at once. ### Get your WhatsApp numbers - [GET /payless4messaging-service/WhatsApp/WhatsAppClientNumbers/getForCurrentLoginUser](https://docs.ecommunicate.co.za/apis/omnichannel/whatsapp-number-management/getclientnumbers.md): Retrieve a paginated list of WhatsApp numbers assigned to your account. Each number includes its provider type (Cloud or Lite), quality rating, messaging tier, and connection status. ### Get all your WhatsApp numbers (unpaginated) - [GET /payless4messaging-service/WhatsApp/WhatsAppClientNumbers/getAllForCurrentLoginUser](https://docs.ecommunicate.co.za/apis/omnichannel/whatsapp-number-management/getallclientnumbers.md): Returns all WhatsApp numbers assigned to your account in a single response without pagination. Useful for populating dropdown selectors or syncing your local number list. For large accounts, prefer the paginated endpoint. ### Register a WhatsApp Lite (WL) number - [POST /payless4messaging-service/WhatsApp/WhatsAppClientNumbers/registerWLNumber](https://docs.ecommunicate.co.za/apis/omnichannel/whatsapp-number-management/registerwlnumber.md): Register a WhatsApp Lite number and assign it to the authenticated user's client. The provider is set to WL and the billing model to message. If hostingType is omitted, it defaults to WHATSAPP_GO. If the number already exists but is not linked to your client, it will be reused and linked. Attempting to register a number that is already assigned to your client returns an error. ## Template Management Create, update, delete, and query WhatsApp message templates (WhatsApp Cloud API). Templates must be submitted to Meta for approval before use. Supports 11 template types including text-only, media header, carousel, call-to-action, authentication, and flow templates. Use `searchString` to filter by name, category, language, or status. **Call-to-action (CTA) is an umbrella term, not a single template type.** It covers any template carrying interactive buttons — **quick-reply**, **static/dynamic URL**, **phone-number**, **flow**, and **OTP** buttons — used alone or mixed in one template. The send examples group all of these under the `CTA — …` heading for this reason. **WhatsApp Lite limitation:** WhatsApp Lite only supports **text** and **media** templates. Interactive template types (call-to-action buttons, carousel, authentication, flow) are not supported on WhatsApp Lite. **Marketing templates (Cloud API):** Meta requires that marketing templates include an opt-out mechanism (e.g. a quick-reply "Stop" button). Including an opt-out button significantly reduces your block rate — recipients who can unsubscribe gracefully are far less likely to block your number. Templates without an opt-out option risk rejection or may negatively impact your number's quality rating. See the [Account & Number Health](#section/overview/WhatsApp-account-and-number-health) section for full details. ### Create a WhatsApp template - [POST /whatsapp-api-service/whatsAppTemplates/createTemplate](https://docs.ecommunicate.co.za/apis/omnichannel/template-management/createtemplate.md): Submit a new WhatsApp message template for Meta approval. The template is validated locally and forwarded to Meta's template review process. Approval typically takes minutes but can take up to 24 hours. Supports 11 template types — see the request examples for each type. The response includes the template ID and initial status (pending). Marketing templates (Cloud API): If your template category is MARKETING, you should include a quick-reply opt-out button (e.g. "Stop promotions") as part of your template components. This is a Meta policy requirement — marketing templates without an opt-out mechanism risk rejection and can negatively impact your number's quality rating and messaging limits. Including an opt-out button reduces your block rate, which is the primary factor Meta uses to assess number quality. WhatsApp Lite: Only text and media template types are supported. Interactive components (call-to-action buttons, carousel, authentication, flow) are not available on WhatsApp Lite. ### Update a template - [PUT /whatsapp-api-service/whatsAppTemplates/updateTemplate](https://docs.ecommunicate.co.za/apis/omnichannel/template-management/updatetemplate.md): Update components of an existing template. The templateRequest field must contain the stringified JSON of the new template structure. Important: This endpoint performs a full entity save. You must include all fields in the request body. Any omitted fields will be set to null. ### Delete a template - [DELETE /whatsapp-api-service/whatsAppTemplates/deleteTemplate/{templateId}](https://docs.ecommunicate.co.za/apis/omnichannel/template-management/deletetemplate.md): Permanently delete a WhatsApp template by its ID. This removes the template from both eCommunicate and Meta. Deleted templates cannot be recovered — create a new template if needed. ### Get template approval status - [GET /whatsapp-api-service/whatsAppTemplates/approvalRequest](https://docs.ecommunicate.co.za/apis/omnichannel/template-management/gettemplatestatus.md): Check the current approval status of a template. Returns the template details including status (pending, approved, rejected), rejection reason (if applicable), and the full template structure. ### Get client templates (paginated) - [GET /whatsapp-api-service/whatsAppTemplates/getWhatsAppClientTemplates](https://docs.ecommunicate.co.za/apis/omnichannel/template-management/getclienttemplates.md): Retrieve a paginated list of all WhatsApp templates for your account. Use searchString to filter by template name, category, language code, or approval status. Results are sorted by sortField (default requestedDate) in the specified direction. ## Resend Messages Retry delivery of failed WhatsApp messages. Resend individual messages by ID or bulk-resend all failed messages matching a date range, template, and status filter. Useful for recovering from transient delivery failures or provider outages. ### Resend selected messages - [POST /payless4messaging-service/WhatsApp/WhatsAppSendReceiveMessages/resendSelectedMessages](https://docs.ecommunicate.co.za/apis/omnichannel/resend-messages/resendselectedmessages.md): Resend specific failed messages by their IDs. ### Resend all failed messages - [POST /payless4messaging-service/WhatsApp/WhatsAppSendReceiveMessages/resendAllMessages](https://docs.ecommunicate.co.za/apis/omnichannel/resend-messages/resendallmessages.md): Resend all failed messages matching the given filters (date range, template, status). ## Live Chat Manage real-time customer conversations through agent queues. View unassigned, assigned, team, closed, and missed conversations. Send text and media replies to customers, show typing indicators, and mark messages as read. Supports pagination and search across all queue types. For retrieving conversation history, see the [Chatbot conversation flow](/guides/live-chat#chatbot-conversation-flow) guide — it covers receiving webhooks, looking up chat participants, and fetching messages. ### List chats (v2) - [GET /pl4chat-service/api/v2/chats](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/listchatsv2.md): Paginated chat list for the authenticated agent, selected by scope. The agent and client are resolved from your API key / session. Returns a lean ChatParticipantResponse page and replaces the deprecated Get chat participants. ### Get a chat (v2) - [GET /pl4chat-service/api/v2/chats/{id}](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/getchatv2.md): Fetch a single chat as a lean ChatParticipantResponse. Tenant-checked. ### Terminate a chat (v2) - [POST /pl4chat-service/api/v2/chats/{id}/terminate](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/terminatechatv2.md): Close the conversation (and trigger the rating widget if configured). Takes only the chat id — the closing agent is resolved from your API key / session. Replaces toggling conversationClosed on the deprecated Terminate or reopen a chat conversation. ### Reopen a chat (v2) - [POST /pl4chat-service/api/v2/chats/{id}/open](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/openchatv2.md): Reopen a previously closed conversation and assign it to the calling agent (resolved from your API key / session). Replaces toggling conversationClosed=false on the deprecated Terminate or reopen a chat conversation. ### Get global system tracking numbers - [GET /pl4chat-service/ChatParticipant/system/tickets](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/getsystemticketnumbersbydate.md): Retrieve global system tracking numbers (gstn) from chat participants created within the specified date range. The client is resolved from the authenticated user's API key or session. ### Get messages by tracking number (v2) - [GET /pl4chat-service/api/v2/messages/tracking/{trackingNumber}](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/getmessagesbytrackingnumberv2.md): Retrieve the conversation history for a tracking number (GSTN or CTN) as lean MessageResponse objects, scoped to your client. Replaces the deprecated Get chat messages by tracking number. ### Get a message by ctId (v2) - [GET /pl4chat-service/api/v2/messages/ctid/{ctId}](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/getmessagebyctidv2.md): Look up a single message by its custom tracking id (ctId) as a lean MessageResponse. Tenant-checked — returns 404 if the message does not belong to your client. ### Get messages for a chat participant (v2) - [GET /pl4chat-service/api/v2/messages](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/getmessagesv2.md): Retrieve the messages for a chat participant as a lean, curated payload (MessageResponse) — only the fields a live-chat UI needs, plus the quoted-reply context (quotedExternalMessageId, quotedText). The agent is resolved from your API key / session and the participant is tenant-checked. Replaces the deprecated Get messages by chat participant. ### Send an agent message (v2) - [POST /pl4chat-service/api/v2/messages](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/sendmessagev2.md): Send an agent reply on any channel through a single endpoint. The target channel is set via the channel field (WHATSAPP, WEB, or FACEBOOK) and routing is handled server-side — replacing the per-channel v1 send endpoints. For a text message set text; for media, first upload the file via Upload media for an agent message and send the returned mediaUrl (the content type defaults to MEDIA when a mediaUrl is present). The agent is resolved from your API key / session and the participant is tenant-checked. ### Upload media for an agent message (v2) - [POST /pl4chat-service/api/v2/messages/media](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/uploadmediav2.md): Upload a media file and receive a hosted mediaUrl (plus the detected mediaType) to attach to a Send an agent message call. Channel-agnostic — the same uploaded URL can be sent on WhatsApp, web, or Facebook. ### Send typing indicator (v2) - [POST /pl4chat-service/api/v2/messages/typing](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/sendtypingindicatorv2.md): Show a typing indicator to the customer. The sender/recipient are resolved from the participant — you only pass participantId (and optionally the last inbound messageId, which the server otherwise looks up). Replaces the deprecated Send typing indicator (Chat). ### Mark a conversation as read (v2) - [POST /pl4chat-service/api/v2/messages/read](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/markasreadv2.md): Mark the participant's conversation as read — clears the unread badge and sends a read receipt to the customer. Pass participantId (and optionally the last inbound messageId, which the server otherwise looks up). ### Get chat participants (deprecated) - [GET /pl4chat-service/ChatParticipant](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/getchatparticipants.md): Deprecated. Use List chats (v2), which returns a lean ChatParticipantResponse and selects the list with a scope filter (my / team / unassigned / closed / missed / open / all). This endpoint returns the full internal entity and is retained only for existing integrations. Retrieve chat participant details for the authenticated user's client. Returns participant profile information, assignment status, and conversation metadata. Use searchString to filter by phone number or full name, and isOpen to filter by conversation state. ### Get chat messages by tracking number (deprecated) - [GET /pl4chat-service/Message/trackingNumber/{trackingNumber}](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/getchatmessagesbytrackingnumber.md): Deprecated. Use Get messages by tracking number (v2), which returns the lean MessageResponse. Retained for existing integrations. Retrieve the full conversation history for a chat participant matching the given tracking number (GSTN or CTN). ### Get messages by chat participant (deprecated) - [GET /pl4chat-service/Message/getMessagesByChatParticipant](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/getmessagesbychatparticipant.md): Deprecated. Use Get messages for a chat participant (v2) instead, which returns a leaner curated payload (MessageResponse) and includes the quoted-reply context. This endpoint returns the full internal message entity and is retained only for existing integrations. Retrieve all messages for a specific chat participant. Accepts participant ID or web session ID. ### Get unassigned conversations (deprecated) - [GET /pl4chat-service/ChatParticipant/getUnAssignedParticipants](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/getunassignedparticipants.md): Deprecated. Use List chats (v2) with scope=unassigned. Retained for existing integrations. ### Get my assigned conversations (deprecated) - [GET /pl4chat-service/ChatParticipant/getMyParticipants](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/getmyparticipants.md): Deprecated. Use List chats (v2) with scope=my. Retained for existing integrations. ### Get team conversations (deprecated) - [GET /pl4chat-service/ChatParticipant/getTeamParticipants](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/getteamparticipants.md): Deprecated. Use List chats (v2) with scope=team. Retained for existing integrations. ### Get closed conversations (deprecated) - [GET /pl4chat-service/ChatParticipant/getClosedParticipants](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/getclosedparticipants.md): Deprecated. Use List chats (v2) with scope=closed. Retained for existing integrations. Retrieve conversations that have been terminated by an agent. Results are paginated and can be filtered by search string and client reference. ### Get missed conversations (deprecated) - [GET /pl4chat-service/ChatParticipant/getMissedParticipants](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/getmissedparticipants.md): Deprecated. Use List chats (v2) with scope=missed-agent. Retained for existing integrations. Retrieve conversations where the customer disconnected before an agent could respond. Includes pagination and search. ### Get after-hours missed conversations (deprecated) - [GET /pl4chat-service/ChatParticipant/getMissedAfterHoursParticipants](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/getmissedafterhoursparticipants.md): Deprecated. Use List chats (v2) with scope=missed-after-hours. Retained for existing integrations. ### Get my missed conversations (deprecated) - [GET /pl4chat-service/ChatParticipant/getMyMissedParticipants](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/getmymissedparticipants.md): Deprecated. Use List chats (v2) with scope=my-missed. Retained for existing integrations. ### Get conversations assigned to a specific agent (deprecated) - [GET /pl4chat-service/ChatParticipant/getChatParticipantsByAssignedTo](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/getparticipantsbyassignedto.md): Deprecated. Use List chats (v2) with scope=my. v2 resolves the agent from your API key / session, so it returns your assigned chats — you can no longer query an arbitrary agent by id. Retained for existing integrations. Retrieve all active conversations assigned to a specific agent by their user ID. ### Terminate or reopen a chat conversation (deprecated) - [PUT /pl4chat-service/ChatParticipant/terminateChatParticipantChat](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/terminatechatparticipantchat.md): Deprecated. Use Terminate a chat (v2) or Reopen a chat (v2) — they take only the chat id (the actor is resolved from your API key / session) and avoid the full-object merge pitfalls below. Retained for existing integrations. Terminates or reopens a chat by toggling the conversationClosed field on the ChatParticipant object. Set conversationClosed to true to terminate the chat (triggers the rating widget if configured), or set it to false to reopen a previously closed chat. Important — send the full object. The safest approach is to fetch the participant with GET /pl4chat-service/ChatParticipant and send the complete object back with conversationClosed toggled. The endpoint merges non-null string and object fields (so most omitted fields are preserved), but two categories behave differently and can silently reset state: - assignedTo — if omitted or null, the agent assignment is cleared. - Boolean flags — conversationClosed, missedConversation, afterHoursConversation, sendRatingWidget, and chatBotConversation are always copied from the request. Omitting any of them resets it to false. Note that when terminating with sendRatingWidget=true, the server also moves assignedTo to lastAssignedAgent, sets expectingRating=true, and triggers the rating widget. ### Send WhatsApp agent reply (deprecated) - [POST /pl4chat-service/Message/sendMessageWhatsapp](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/sendagentmessagewhatsapp.md): Deprecated. Use the unified Send an agent message (v2) with channel: WHATSAPP — one endpoint covers all channels, takes a lean request, and returns a lean MessageResponse. This endpoint takes the full internal message entity and is retained only for existing integrations. Send a WhatsApp message from an agent to a customer (routes via WhatsApp API). ### Send agent reply with attachment (deprecated) - [POST /pl4chat-service/Message/sendMessageWithAttachment](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/sendagentmessagewithattachment.md): Deprecated. Upload media via Upload media for an agent message (v2) then send the returned mediaUrl with Send an agent message (v2). The two-step flow is channel-agnostic and replaces this WhatsApp-oriented multipart endpoint, which is retained only for existing integrations. Send a message with a file attachment (image, document, video) from an agent. ### Send typing indicator (Chat) (deprecated) - [POST /pl4chat-service/Message/sendTypingIndicator](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/sendchattypingindicator.md): Deprecated. Use Send typing indicator (v2), which resolves sender/recipient from the participant (you pass only participantId). Retained only for existing integrations. Show a typing indicator to the customer from the chat agent. ### Mark message as read by agent (deprecated) - [POST /pl4chat-service/Message/markReadByAgent](https://docs.ecommunicate.co.za/apis/omnichannel/live-chat/markreadbyagent.md): Deprecated. Use Mark a conversation as read (v2), which clears the unread badge and sends the read receipt for the participant in one call. Retained for existing integrations. Mark a specific message as read by the agent (sends read receipt to customer). ## Tickets Manage support tickets created from live chat conversations. Search and filter tickets by date range, status, agent, rating, and ticket number. Update ticket status through the lifecycle: `OPEN` → `AWAITING_AGENT` → `AWAITING_CUSTOMER` → `RESOLVED` → `CLOSED`. Retrieve ticket details by ticket number, chat participant, or customer WhatsApp number. ### Get tickets by client ref - [GET /pl4chat-service/ticket/client/{clientRef}](https://docs.ecommunicate.co.za/apis/omnichannel/tickets/getticketsbyclientref.md): Retrieve all tickets for a given client reference, including rating information. ### Get ticket by ticket number - [GET /pl4chat-service/ticket/by-ticket-number](https://docs.ecommunicate.co.za/apis/omnichannel/tickets/getticketbyticketnumber.md): Retrieve a single ticket by its ticket number. ### Search tickets with filters - [GET /pl4chat-service/ticket/search](https://docs.ecommunicate.co.za/apis/omnichannel/tickets/filterticketsbycriteria.md): Search and filter tickets with pagination. Supports filtering by date range, WhatsApp number, rating, ticket number, agent, client ref, and status. ### Update ticket status - [PUT /pl4chat-service/ticket/{ticketId}/status](https://docs.ecommunicate.co.za/apis/omnichannel/tickets/updateticketstatus.md): Update the status of an existing ticket. ### Get tickets by customer and client WhatsApp numbers - [GET /pl4chat-service/ticket/getTicketEmailEntitiesByCustomerWhatsappNumberAndClientWhatsappNumber](https://docs.ecommunicate.co.za/apis/omnichannel/tickets/getticketsbycustomerandclientwhatsappnumber.md): Retrieve all ticket entities matching both the customer's and the client's WhatsApp numbers. ### Get ticket by chat participant ID - [GET /pl4chat-service/ticket/getTicketEntityByChatParticipantId](https://docs.ecommunicate.co.za/apis/omnichannel/tickets/getticketbychatparticipantid.md): Retrieve the ticket entity associated with a specific chat participant. ### Get tickets by customer WhatsApp number and client ref - [GET /pl4chat-service/ticket/getTicketEmailEntitiesByCustomerWhatsappNumberAndClientRef](https://docs.ecommunicate.co.za/apis/omnichannel/tickets/getticketsbycustomerwhatsappnumberandclientref.md): Retrieve all ticket entities matching a customer's WhatsApp number and client reference (case-insensitive). ### Get opened and closed tickets - [GET /pl4chat-service/ticket/getOpenedAndClosedTickets/{clientRef}](https://docs.ecommunicate.co.za/apis/omnichannel/tickets/getopenedandclosedtickets.md): Retrieve all tickets for a client within a date range, including both opened and closed tickets. ## Contacts Manage your customer contact database. Create, update, and delete contact records with phone numbers, names, and metadata. Contacts are used for recipient management and can be queried with pagination. ### Get all contacts - [GET /payless4messaging-service/WhatsApp/contacts](https://docs.ecommunicate.co.za/apis/omnichannel/contacts/getcontacts_inbox.md): Retrieve a paginated list of customer contacts stored in your account. ### Create a contact - [POST /payless4messaging-service/WhatsApp/contacts](https://docs.ecommunicate.co.za/apis/omnichannel/contacts/createcontact.md): Add a new customer contact with phone number and name. The contact is associated with the authenticated client. ### Update a contact - [PUT /payless4messaging-service/WhatsApp/contacts/{id}](https://docs.ecommunicate.co.za/apis/omnichannel/contacts/updatecontact.md): Currently only the fullName field can be updated. ### Delete a contact - [DELETE /payless4messaging-service/WhatsApp/contacts/{id}](https://docs.ecommunicate.co.za/apis/omnichannel/contacts/deletecontact.md): Permanently delete a contact by its ID. ## Analytics Retrieve aggregated delivery statistics for notification and interaction messages. Analytics include submitted, sent, delivered, read, and failed counts, filtered by date range. Use these endpoints to monitor messaging performance and identify delivery issues. ### Get notification analytics - [GET /payless4messaging-service/WhatsApp/WhatsAppAnalytics/getNotificationAnalyticsForCurrentLoginUser](https://docs.ecommunicate.co.za/apis/omnichannel/analytics/getnotificationanalytics.md): Retrieve aggregated delivery statistics for notification (template) messages within a date range. Returns counts for submitted, sent, delivered, read, and failed messages. ### Get interaction analytics - [GET /payless4messaging-service/WhatsApp/WhatsAppAnalytics/getInteractionAnalyticsForCurrentLoginUser](https://docs.ecommunicate.co.za/apis/omnichannel/analytics/getinteractionanalytics.md): Aggregated delivery stats for interaction (session) messages. ## Message Reports Query message delivery status, filter message history, view template replies, and retrieve message timelines. Use `gstId` (system tracking ID) or `ctId` (your custom tracking ID) to look up individual messages. Paginated endpoints support date range filtering and phone number search. ### Get message status by GSTID - [GET /whatsapp-api-service/message/status/gstid](https://docs.ecommunicate.co.za/apis/omnichannel/message-reports/getstatusbygstid.md): Look up the current delivery status of a single message using its Global System Tracking ID (GSTID). Returns the latest status, timestamps for each lifecycle stage, and failure details if applicable. ### Get message statuses by CTID - [GET /whatsapp-api-service/message/status/ctid](https://docs.ecommunicate.co.za/apis/omnichannel/message-reports/getstatusbyctid.md): Look up delivery statuses for all messages matching your custom tracking ID (CTID) within a date range. Useful when you assigned the same ctId to a batch of messages and want to check their collective delivery status. ### Get filtered WhatsApp messages - [GET /payless4messaging-service/WhatsApp/WhatsAppSendReceiveMessages/filter](https://docs.ecommunicate.co.za/apis/omnichannel/message-reports/getfilteredmessages.md): Retrieve a paginated, filterable list of all sent and received WhatsApp messages. Filter by date range, template name, message type, and phone number. Use this for message history, delivery auditing, and debugging. ### Get template replies - [GET /payless4messaging-service/WhatsApp/WhatsAppSendReceiveMessages/reply](https://docs.ecommunicate.co.za/apis/omnichannel/message-reports/getincomingreplies.md): Retrieve incoming customer replies to your template messages. Filter by date range, phone number, and template name. Useful for tracking customer engagement with specific campaigns. ### Get message timeline - [GET /payless4messaging-service/WhatsApp/WhatsAppSendReceiveMessages/timeline](https://docs.ecommunicate.co.za/apis/omnichannel/message-reports/getmessagetimeline.md): Paginated timeline of successful WhatsApp messages filtered by date range and phone numbers. ### Get message audit report - [GET /payless4messaging-service/WhatsApp/WhatsAppSendReceiveMessages/getMessageAuditReport](https://docs.ecommunicate.co.za/apis/omnichannel/message-reports/getmessageauditreport.md): Retrieve a paginated audit report of WhatsApp conversations. Includes conversation category, cost, and message counts. Filter by client reference, conversation category, and date range. ## SMS Reports Retrieve paginated SMS message history including both sent and received messages. Filter by direction (inbound/outbound), sending mode, and search string. Results include message content, delivery status, cost, and timestamps. ### Get SMS messages - [GET /whatsapp-api-service/SMSSendReceiveMessages/getSMSSendReceiveMessagesForCurrentLoginUser](https://docs.ecommunicate.co.za/apis/omnichannel/sms-reports/getsmsmessages.md): Retrieve a paginated list of sent and received SMS messages. Filter by direction, sending mode, and search string. ## Report Downloads Export message reports as downloadable Excel (XLSX) or CSV files. Available reports include notification delivery reports, interaction reports, and Monthly Active User (MAU) summary and detail reports. Reports can be filtered by date range and optionally emailed directly. ### Download notification report (XLSX) - [GET /payless4messaging-service/WhatsApp/Excel/getXlsxReportFor/notification-report.xlsx](https://docs.ecommunicate.co.za/apis/omnichannel/report-downloads/downloadnotificationreportxlsx.md): Download a notification (template) message report as an Excel spreadsheet. Filter by date range, search string, template name, and delivery status. ### Download notification report (CSV) - [GET /payless4messaging-service/WhatsApp/Excel/getCsvReportFor/notification-report.csv](https://docs.ecommunicate.co.za/apis/omnichannel/report-downloads/downloadnotificationreportcsv.md): Download a notification (template) message report as a CSV file. Filter by date range, search string, template name, and delivery status. ### Email notification report - [POST /payless4messaging-service/WhatsApp/Excel/sendXlsxReportByEmail/notification-report.xlsx](https://docs.ecommunicate.co.za/apis/omnichannel/report-downloads/emailnotificationreport.md): Generate a notification report and send it as an XLSX email attachment to the specified email address. Filter by date range, search string, template name, and delivery status. ### Download interaction report (XLSX) - [GET /payless4messaging-service/WhatsApp/Excel/getXlsReportFor/interaction-report.xlsx](https://docs.ecommunicate.co.za/apis/omnichannel/report-downloads/downloadinteractionreport.md): Download an interaction (session) message report as an Excel spreadsheet. Filter by date range and search string. ### Download MAU summary report - [GET /payless4messaging-service/WhatsApp/Excel/getXlsReportFor/summary-mau-report.xlsx](https://docs.ecommunicate.co.za/apis/omnichannel/report-downloads/downloadmausummaryreport.md): Download a Monthly Active Users (MAU) summary report as an Excel spreadsheet. Shows conversation counts and costs aggregated by month. ### Download client MAU summary report - [GET /payless4messaging-service/WhatsApp/Excel/getXlsReportFor/client-summary-mau-report.xlsx](https://docs.ecommunicate.co.za/apis/omnichannel/report-downloads/downloadclientmausummaryreport.md): Download a Monthly Active Users (MAU) summary report for a specific client as an Excel spreadsheet. Optionally filter by client reference. ### Download detailed MAU report - [GET /payless4messaging-service/WhatsApp/Excel/getXlsReportFor/detailed-mau-report.xlsx](https://docs.ecommunicate.co.za/apis/omnichannel/report-downloads/downloaddetailedmaureport.md): Download a detailed Monthly Active Users (MAU) report as an Excel spreadsheet. Includes per-conversation breakdown with costs. Optionally filter by client reference and WhatsApp number. ### Download message audit report (XLSX) - [GET /payless4messaging-service/WhatsApp/WhatsAppSendReceiveMessages/downloadMessageAuditReport](https://docs.ecommunicate.co.za/apis/omnichannel/report-downloads/downloadmessageauditreport.md): Download the message audit report as an Excel spreadsheet. Includes conversation category, cost, and message counts for the specified date range. ## Webhook Configuration Register, update, and manage webhook URLs that receive real-time notifications. You can configure separate URLs for incoming messages, delivery status updates, session status changes (WhatsApp Lite), and platform events (template approvals, quality changes, user preferences). ### Create webhook configuration - [POST /payless4messaging-service/WhatsApp/WhatsAppClientWebHook](https://docs.ecommunicate.co.za/apis/omnichannel/webhook-configuration/createwebhook.md): Register webhook URLs to receive: - Incoming Messages — customer messages to your number. - Status Updates — delivery receipts (sent, delivered, read, failed). - Session Status — connection status changes (WhatsApp Lite only). - Event - user preferences, template status changes, and quality updates. - Chatbot Conversations — chatbot conversation events with chat participant context. Two flags control behavior: chatbotIncludeOutgoing (also emit bot replies, default false) and chatbotStopOnAgentAssignment (stop emitting once a human agent is assigned, default false). Coexists with incomingMessageURL — both fire independently. ### Scope Each configuration applies at one of two scopes, controlled by the optional whatsAppNumberId field: - Client default (whatsAppNumberId omitted) — applies to every WhatsApp number under your client that doesn't have an override. - Per-number override (whatsAppNumberId set) — applies only to events tied to that specific number. At dispatch time the platform looks up an override for the event's WhatsApp number first, and falls back to the client default when no override exists. Only one default per client and one override per (client, number) pair are allowed; duplicates return 409 Conflict. Number ids must be linked to your client; cross-tenant ids return 403 Forbidden. ### Update webhook configuration - [PUT /payless4messaging-service/WhatsApp/WhatsAppClientWebHook](https://docs.ecommunicate.co.za/apis/omnichannel/webhook-configuration/updatewebhook.md): Update an existing webhook configuration. Include the id of the row to update. Set any URL to an empty string ("") to disable that webhook type while keeping others active. Scope is locked once a configuration has been created — whatsAppNumberId on the request body is ignored. To convert a client default into a per-number override (or vice-versa), DELETE the existing row and POST a new one. ### Delete webhook configuration - [DELETE /payless4messaging-service/WhatsApp/WhatsAppClientWebHook/{id}](https://docs.ecommunicate.co.za/apis/omnichannel/webhook-configuration/deletewebhook.md): Delete a single configuration by id. Removing an override re-exposes that number to the client default; removing the client default leaves any per-number overrides in place but stops events for numbers without an override. ### Get default webhook configuration - [GET /payless4messaging-service/WhatsApp/WhatsAppClientWebHook/getForCurrentLoginUser](https://docs.ecommunicate.co.za/apis/omnichannel/webhook-configuration/getwebhook.md): Returns the client default webhook configuration for the authenticated user. Returns an empty body when no default has been created. Use the /list endpoint to also retrieve per-number overrides. ### List all webhook configurations - [GET /payless4messaging-service/WhatsApp/WhatsAppClientWebHook/list](https://docs.ecommunicate.co.za/apis/omnichannel/webhook-configuration/listwebhooks.md): Returns a paginated list of every webhook configuration belonging to the authenticated user's client — the client default (if set) and every per-number override. The client default sorts first; overrides follow, ordered by MSISDN. ## Message Processing Config Configure per-number message processing settings including throughput limits, throttle delays, batch sizes, and daily send schedules. Use these settings to control when and how fast messages are sent, balancing throughput with connection stability. WhatsApp Lite numbers support additional fine-grained controls for delay and batch windowing. ### Get all message processing configs - [GET /payless4messaging-service/WhatsApp/api/configs](https://docs.ecommunicate.co.za/apis/omnichannel/message-processing-config/getmessageprocessingconfigs.md): Retrieve message processing configurations for all WhatsApp numbers. Each config includes throughput limits, throttle delays, and daily send schedules. ### Create message processing config - [POST /payless4messaging-service/WhatsApp/api/configs](https://docs.ecommunicate.co.za/apis/omnichannel/message-processing-config/createmessageprocessingconfig.md): Configure batch send schedules and throttling for a WhatsApp number. The dailySchedules map defines when messages can be sent for each day of the week. Note: The minMsgDelaySeconds, and maxMsgDelaySeconds, batchSize, minBatchDelayMinutes, maxBatchDelayMinutes, batchSuccessLimit fields apply to WhatsApp Lite only. Cloud API rate limiting is managed by Meta. ### Get config by client number - [GET /payless4messaging-service/WhatsApp/api/configs/{clientNumber}](https://docs.ecommunicate.co.za/apis/omnichannel/message-processing-config/getmessageprocessingconfigbynumber.md): Retrieve the message processing configuration for a specific WhatsApp number. ### Update config by client number - [PUT /payless4messaging-service/WhatsApp/api/configs/{clientNumber}](https://docs.ecommunicate.co.za/apis/omnichannel/message-processing-config/updatemessageprocessingconfig.md): Update the message processing configuration for a specific WhatsApp number. This is a full replacement -- include all fields in the request body. ### Delete config by client number - [DELETE /payless4messaging-service/WhatsApp/api/configs/{clientNumber}](https://docs.ecommunicate.co.za/apis/omnichannel/message-processing-config/deletemessageprocessingconfig.md): Delete the message processing configuration for a specific WhatsApp number, reverting to default platform settings. ## Block & Blacklist Manage blocked and blacklisted phone numbers. **Blocked numbers** are system-managed — numbers automatically blocked due to delivery failures or user opt-outs. **Blacklisted numbers** are client-managed — numbers you explicitly add to prevent sending. Blacklist entries can be added individually or uploaded in bulk via CSV. ### Get blocked numbers - [GET /payless4messaging-service/WhatsApp/WhatsAppBlockedNumber/getForCurrentLoginUser](https://docs.ecommunicate.co.za/apis/omnichannel/block-and-blacklist/getblockednumbers.md): Numbers blocked by the system (e.g. due to delivery failures or user opt-out). ### Unblock a number - [DELETE /payless4messaging-service/WhatsApp/WhatsAppBlockedNumber/unblockNumber/{whatsAppBlockedNumber}](https://docs.ecommunicate.co.za/apis/omnichannel/block-and-blacklist/unblocknumber.md): Remove a number from the blocked list, allowing messages to be sent to it again. ### Get blacklisted numbers - [GET /payless4messaging-service/WhatsApp/WhatsAppBlacklistNumber/getForCurrentLoginUser](https://docs.ecommunicate.co.za/apis/omnichannel/block-and-blacklist/getblacklistednumbers.md): Numbers manually blacklisted by the client. Messages will not be sent to these numbers. ### Blacklist a number - [POST /payless4messaging-service/WhatsApp/WhatsAppBlacklistNumber](https://docs.ecommunicate.co.za/apis/omnichannel/block-and-blacklist/blacklistnumber.md): Add a phone number to the blacklist. No messages will be sent to this number. ### Blacklist numbers from file - [POST /payless4messaging-service/WhatsApp/WhatsAppBlacklistNumber/upload](https://docs.ecommunicate.co.za/apis/omnichannel/block-and-blacklist/blacklistnumbersupload.md): Upload a CSV or text file containing phone numbers to blacklist in bulk. ### Remove from blacklist - [DELETE /payless4messaging-service/WhatsApp/WhatsAppBlacklistNumber/{id}](https://docs.ecommunicate.co.za/apis/omnichannel/block-and-blacklist/removefromblacklist.md): Remove a phone number from the client-managed blacklist by its record ID. ## Batches Control the execution of batch message jobs. Pause a running batch to temporarily halt sending, resume a paused batch to continue, or cancel a batch to stop it permanently. Batch jobs are created automatically when sending to multiple recipients. ### Control batch execution - [POST /payless4messaging-service/WhatsApp/api/batches/control](https://docs.ecommunicate.co.za/apis/omnichannel/batches/controlbatch.md): Pause, resume, or cancel batch message execution. Scope Resolution (Priority Order): 1. batchId provided → applies to that batch only. 2. senderId provided → applies to all active batches for that sender. 3. Neither → applies to all active batches for the authenticated client. Rules: - Batches can only be paused/resumed while ACTIVE or PAUSED. - CANCELLED batches cannot be resumed. - Batch messages are retained for 7 days. After that, the batch cannot be resumed. ## (WhatsApp Lite) Connection Connect and manage WhatsApp Lite sessions. Establish a connection by scanning a QR code (via WebSocket stream or static image) or by entering a pairing code. Monitor session status, configure webhooks for the number, and log out when needed. WhatsApp Lite requires an active phone connection — if the phone goes offline, the session disconnects. ### WebSocket Connection (QR Stream) - [GET /](https://docs.ecommunicate.co.za/apis/omnichannel/(whatsapp-lite)-connection/connectwebsocket.md): Protocol: WSS (WebSocket Secure) Establish a WebSocket connection to receive real-time QR code updates. Incoming Message Format (Regex): /userId=(.+?), sessionStatus=(.+?), status=(.+?)(?:, qrCode=(.+?))?(?:\))/ States: - newQrCode — qrCode contains Base64 image. - success — Phone connected. - timeout — QR code expired. ### Initialize session - [POST /whatsapp-api-service/api/whatsapp-go/session/connect](https://docs.ecommunicate.co.za/apis/omnichannel/(whatsapp-lite)-connection/connectsession.md): Initializes a WhatsApp session. After calling this, connect to the WebSocket to receive the QR code. ### Set webhook (WhatsApp Lite) - [POST /whatsapp-api-service/api/whatsapp-go/session/webhook](https://docs.ecommunicate.co.za/apis/omnichannel/(whatsapp-lite)-connection/setlitewebhook.md): Register a webhook URL to receive incoming messages and events for a WhatsApp Lite number. ### Get QR code (static) - [GET /whatsapp-api-service/api/whatsapp-go/session/qr](https://docs.ecommunicate.co.za/apis/omnichannel/(whatsapp-lite)-connection/getqrcode.md): Retrieve the current QR code as a Base64 string if WebSocket method is not used. ### Request pairing code - [POST /whatsapp-api-service/api/whatsapp-go/session/pairing-code](https://docs.ecommunicate.co.za/apis/omnichannel/(whatsapp-lite)-connection/requestpairingcode.md): Generates an 8-character linking code for the "Link with phone number" option. ### Get session status - [GET /whatsapp-api-service/api/whatsapp-go/session/status](https://docs.ecommunicate.co.za/apis/omnichannel/(whatsapp-lite)-connection/getsessionstatus.md): Check the current connection status of a WhatsApp Lite session. Returns whether the number is connected, disconnected, or requires a QR scan. ### Logout session - [POST /whatsapp-api-service/api/whatsapp-go/session/logout](https://docs.ecommunicate.co.za/apis/omnichannel/(whatsapp-lite)-connection/logoutsession.md): Logs the number out of WhatsApp Web/Multi-device session. ## (WhatsApp Lite) Groups Create and manage WhatsApp groups on WhatsApp Lite numbers. Add participants, send group messages, retrieve message history, and generate invite links. Groups are only available on WhatsApp Lite — WhatsApp Cloud does not support group management via API. ### Get all groups - [GET /payless4messaging-service/WhatsApp/api/v1/groups](https://docs.ecommunicate.co.za/apis/omnichannel/(whatsapp-lite)-groups/getgroups.md): Retrieve all WhatsApp groups for the authenticated WhatsApp Lite account. ### Create a group - [POST /payless4messaging-service/WhatsApp/api/v1/groups](https://docs.ecommunicate.co.za/apis/omnichannel/(whatsapp-lite)-groups/creategroup.md): Create a new WhatsApp group with a name, description, and initial participants. ### Get group by ID - [GET /payless4messaging-service/WhatsApp/api/v1/groups/{id}](https://docs.ecommunicate.co.za/apis/omnichannel/(whatsapp-lite)-groups/getgroup.md): Retrieve details of a specific WhatsApp group by its UUID. ### Update group - [PUT /payless4messaging-service/WhatsApp/api/v1/groups/{id}](https://docs.ecommunicate.co.za/apis/omnichannel/(whatsapp-lite)-groups/updategroup.md): Update a WhatsApp group's name, description, or participant list. Important: This endpoint performs a full entity save. You must include all fields in the request body. Any omitted fields will be set to null. Fetch the group with GET /payless4messaging-service/WhatsApp/api/v1/groups/{id} first and send the complete object back with your changes applied. ### Delete group - [DELETE /payless4messaging-service/WhatsApp/api/v1/groups/{id}](https://docs.ecommunicate.co.za/apis/omnichannel/(whatsapp-lite)-groups/deletegroup.md): Leave and remove a WhatsApp group. ### Send group message - [POST /payless4messaging-service/WhatsApp/api/v1/groups/messages](https://docs.ecommunicate.co.za/apis/omnichannel/(whatsapp-lite)-groups/sendgroupmessage.md): Send a text or media message to a WhatsApp group. ### Get group messages - [GET /payless4messaging-service/WhatsApp/api/v1/groups/{groupId}/messages](https://docs.ecommunicate.co.za/apis/omnichannel/(whatsapp-lite)-groups/getgroupmessages.md): Retrieve the message history for a specific WhatsApp group with pagination. ### Get group invite link - [GET /payless4messaging-service/WhatsApp/api/v1/groups/{groupJID}/invite-link](https://docs.ecommunicate.co.za/apis/omnichannel/(whatsapp-lite)-groups/getgroupinvitelink.md): Generate or retrieve the invite link for a WhatsApp group. Share this link to allow others to join the group. ## (WhatsApp Lite) Contacts Retrieve contacts synced from the phone connected to a WhatsApp Lite session. Returns the contact list stored on the device. Only available for WhatsApp Lite numbers with an active session. ### Get contacts - [GET /whatsapp-api-service/api/whatsapp-go/session/contacts](https://docs.ecommunicate.co.za/apis/omnichannel/(whatsapp-lite)-contacts/getcontacts.md): Retrieve contacts synced from the connected phone.