Changelog

All notable changes to the eCommunicate Omnichannel API. This changelog follows Semantic Versioning.

Released July 2026

• New PLAYED message status for voice notes. When a recipient listens to a voice note (voice/PTT message), the status update webhook now fires with status: "PLAYED" and a playedTime. PLAYED follows READ in the lifecycle and applies only to voice notes. Added to the status enums (latestMessageStatus, eCommValidationMessage) and the v2 MessageResponse gains played / playedTime.
• BSUID on the send request. Each recipient on POST /v2/messages / POST /v2/channels/whatsapp (Omnichannel) and POST /v2/json (Conversations) now accepts customerUserId (the recipient's BSUID). Supply it alongside to (the phone takes precedence, the BSUID rides along as a durable fallback) or on its own to address a recipient that has no phone number. A malformed BSUID is ignored.
• BSUID on the chat participant. The ChatParticipant schema documents userId (BSUID), username, and parentUserId, and the lean v2 ChatParticipantResponse now carries userId and username — fields already returned by the participant and chat endpoints.

Released July 2026

• Incoming message webhooks now carry the customer's alpha username fields. senderUserId (the durable business-scoped user id / BSUID, e.g. ZA.1021033720668862) and username (optional display username) are added to the incoming message payload. The BSUID is stable across phone-number changes and present even when the phone number is withheld; the phone number stays the primary identifier for now. Both are omitted when the provider doesn't supply them.
• Chatbot webhook v2 adds senderUserId / recipientUserId / username. On INCOMING events the customer's BSUID is in senderUserId; on OUTGOING events it is in recipientUserId. See the v2 field reference. Available on the v2 payload only.

Released June 2026

• UserResponse now documents the user's client context and account status. Added clientId, countryTimezone, and popiaComplianceEnabled (inherited from the client), plus resetPasswordEmailSent, emailVerified, tempPasswordValid, and validToken.
• User Management v1 migration guide. The Migrations & Deprecations page now maps every deprecated /SystemUsers/* endpoint to its credential-free /api/v1/users replacement.

Released June 2026

• New credential-free User Management endpoints under /api/v1/users: create a user, update a user, delete a user, get my profile, list users (paginated), change availability, set agent chat limit, change my password, and get my WhatsApp credits. Responses use new credential-free schemas (UserResponse, CreateUserResponse, UpdateUserRequest, CreateUserRequest) that never include password, apiKey, or token fields.
• Creating a user returns a one-time temporary password. A user is created without a caller-supplied password; the response carries a single-use temporaryPassword to share securely, and the user must set their own password on first login.

• All legacy /SystemUsers/* user endpoints are deprecated in favour of their /api/v1/users equivalents (create, update, get current user, paginated list, change availability, update agent chat limit, change password, get WhatsApp credits). They continue to work but expose credential-bearing SystemUser objects and will be removed in a future release.

Released June 2026

• New fields on the v2 MessageResponse: sender and receiver (the message's from/to addresses), ctId (the custom tracking id, when one was supplied on send), fileExtension (extension of attached media), and facebookMessageId (the Facebook provider message id, alongside the existing whatsAppMessageId). All are omitted when null.

• tempId on Send an agent message (v2) is now documented as an optional plain string. Supply a client-generated id only if you want it echoed back to reconcile an optimistic UI message; otherwise omit it. (No longer constrained to UUID format.)

Released June 2026

• Nested chatParticipant object dropped from the v2 chatbot webhook payload. It was redundant — agent identity and conversation lifecycle are already on the flat fields (assignedAgentId, assignedAgentName, lastAssignedAgentId, lastAssignedAgentName, conversationStatus, conversationClosed, …) — and it shipped the full SystemUser (including credential fields) inside chatParticipant.assignedTo. The v2 payload is now the flat fields plus teamId / teamName / routedToAnotherTeam and the quoted-reply fields. No credentials are sent. The corresponding security warning has been removed from the Webhooks guide.
• Why it's safe to drop: the v2 send flow no longer needs the full object — reply with a single call to Send an agent message (v2) using just the chatParticipantId from the payload.

Breaking for receivers that read chatParticipant.*. Switch to the flat assignedAgent* / conversation* fields (same values, same top-level payload).

Released June 2026

• Lean v2 live-chat endpoints under /pl4chat-service/api/v2:
  • GET /api/v2/messages — messages for a participant as a curated MessageResponse (incl. quoted-reply fields).
  • POST /api/v2/messages — single agent send for all channels, routed by a channel field (WHATSAPP/WEB/FACEBOOK).
  • POST /api/v2/messages/media — channel-agnostic media upload returning a mediaUrl to send.
  • POST /api/v2/messages/typing and POST /api/v2/messages/read — typing indicator and mark-conversation-read, keyed by participantId.
  • GET /api/v2/messages/tracking/{trackingNumber} and GET /api/v2/messages/ctid/{ctId} — message lookups returning lean MessageResponse (tenant-scoped).
  • GET /api/v2/chats — paginated chat list selected by a scope filter, returning ChatParticipantResponse.
  • GET /api/v2/chats/{id}, POST /api/v2/chats/{id}/terminate, POST /api/v2/chats/{id}/open — fetch / close / reopen a chat by id (actor resolved from the session).
• Migration guide — new Migrations & Deprecations page mapping each deprecated v1 endpoint to its v2 replacement.

• Marked deprecated (all remain fully functional — no removal date): getMessagesByChatParticipant, sendAgentMessageWhatsapp, sendAgentMessageWithAttachment, sendChatTypingIndicator, markReadByAgent, getChatParticipants and the per-tab lists (getMyParticipants, getTeamParticipants, getUnAssignedParticipants, getClosedParticipants, getMissedParticipants, getMissedAfterHoursParticipants, getMyMissedParticipants), getParticipantsByAssignedTo, terminateChatParticipantChat, and getChatMessagesByTrackingNumber. New integrations should use the v2 endpoints above — see the migration guide.

Released June 2026

• quotedMessageId and quotedText on the v2 chatbot webhook payload — when a customer replies by quoting an earlier message (WhatsApp's reply-to feature), INCOMING events now include the quoted message's WhatsApp id (quotedMessageId) and a text snapshot (quotedText), so receivers can render the reply in context without having stored the original. Both fields are omitted when the incoming message is not a reply/quote.

• Webhooks guide — added an "Incoming message (customer quoting a message)" example to the chatbot conversation payload section, and documented the two new fields in the field reference.

Released June 2026

• International recipient format on WhatsApp sends — the to field on send-message recipients now carries an E.164-style validation pattern (^\+?[1-9][0-9]{6,14}$) and a description requiring the country code plus subscriber number, with an optional leading +. Numbers in local format starting with 0 are explicitly invalid — e.g. South Africa must be +27821234567 or 27821234567, never 0821234567. The rule is country-agnostic: the leading digit after the optional + must be 1–9, so any country code is accepted.
• Send endpoint guidance — the unified send (POST /v2/messages) and Send WhatsApp messages (POST /v2/channels/whatsapp) endpoint descriptions now state the recipient number format rule.

Released June 2026

• "Call-to-action (CTA)" defined as an umbrella term — the Template Management section now states explicitly that CTA is not a single template type but covers any template carrying interactive buttons (quick-reply, static/dynamic URL, phone-number, flow, and OTP), matching how the send examples already group them under the CTA — … heading.
• Renamed the mislabeled create example — the createTemplate example previously listed as "Call to Action" (which contained only quick-reply buttons) is now "Quick-reply Buttons", and its summary notes it is a call-to-action variant. This removes the contradiction of CTA appearing both as the umbrella and as a sibling of the URL/phone/flow button examples.
• Aligned the WhatsApp Lite limitation lists — the unsupported-types lists no longer list "quick-reply buttons" and "call-to-action" as separate items, since quick-reply is one of the call-to-action button variants.

Released May 2026

• Segments and billing section in the SMS Messaging guide — new section explaining how SMS messages over 160 characters are automatically split into 153-character segments, each billed as a separate SMS. Includes a length-to-cost lookup table covering 1–918 GSM 7-bit characters (1–6 segments) and a parallel table for Unicode (UCS-2) covering 1–268 characters (1–4 segments).
• Boundary-crossing warning — guide now flags that a 161-character message costs 2 SMS (not 1), and that a single curly quote, em dash, or emoji forces the entire message onto Unicode encoding (e.g. a 161-character "English" message with one — becomes a 3-SMS Unicode send instead of a 2-SMS GSM send).
• Client-side length calculation guidance — guide reiterates that the platform does not pre-flight cost and clients should measure the message length before sending if they need to predict the SMS charge.

Released May 2026

• chatbotPayloadVersion field on WhatsAppClientWebHook — per-webhook switch between the existing flat chatbot payload (v1, default) and the new enriched payload (v2). Defaults to v1 when omitted; existing integrations are unaffected.
• v2 chatbot webhook payload — strict superset of v1. Adds the nested chatParticipant object (full chat participant record, with the currently assigned agent nested as chatParticipant.assignedTo) plus three flat team fields: teamId, teamName, and routedToAnotherTeam. routedToAnotherTeam is emitted on assignment events and is true when the assignment moved the chat to a different team than its previous assignment. Receivers can render the conversation lifecycle without a follow-up GET /ChatParticipant/{id} call.
• Per-webhook scope — payload version is set independently on the client default and on each per-number override, so different numbers can run on different versions during migration.
• Security guidance for v2 — Webhooks guide now flags that chatParticipant.assignedTo carries credential fields (password, apiKey, loginToken, passwordResetKey, emailVerificationKey, applicationKey). Treat receiving endpoints as a sensitive credential store; TLS-only, restrict log retention, rotate on compromise. Stay on v1 if you only need agent identity (id/name/role).

• POST / PUT /payless4messaging-service/WhatsApp/WhatsAppClientWebHook — request body accepts the optional chatbotPayloadVersion field ("v1" or "v2"). Send "v2" to opt that webhook into the enriched payload; reversible at any time with another PUT.

• Chatbot webhook payload v1 — Webhooks guide now flags v1 as on the deprecation path. The default chatbotPayloadVersion will switch from v1 to v2, and the field itself will be removed once the migration completes. New integrations should set "v2" explicitly to avoid breaking when the default flips.

• Replying from a v2 chatbot webhook — Webhooks guide now explains that the v2 payload carries everything the live-chat send endpoints need, so a real-time reply takes a single API call (no follow-up GET). Added inline links to Send WhatsApp agent reply for text and Send agent reply with attachment for media.

Released May 2026

• searchString query parameter on GET /pl4chat-service/ChatParticipant — case-insensitive substring filter applied to the participant's phone number and full name. Partial matches are supported. Omit to return unfiltered results.
• isOpen query parameter on GET /pl4chat-service/ChatParticipant — tri-state conversation filter. Omit (or send no value) to return all chats. Pass true to return only open conversations (conversationClosed = false), or false to return only closed conversations (conversationClosed = true). The filter combines with searchString so dashboards can drill into "open chats matching +27" in a single call.

• GET /pl4chat-service/ChatParticipant — searchString is now honored on this endpoint (previously the parameter was accepted but ignored, always returning the unfiltered page). Existing integrations that omitted the parameter continue to behave the same.

Released April 2026

• Per-number webhook scope on WhatsAppClientWebHook — webhook configurations now carry an optional whatsAppNumberId. When null the row is the client default (today's behavior, applied to every WhatsApp number under your client). When set to one of your WhatsAppNumbers.id values, the row is a per-number override applied 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 default when none exists.
• whatsAppNumberMsisdn on WhatsAppClientWebHook responses — read-only convenience field that surfaces the MSISDN of the number a per-number override applies to. null for the client default.
• GET /payless4messaging-service/WhatsApp/WhatsAppClientWebHook/list — paginated list of every webhook configuration belonging to the authenticated user's client (default + per-number overrides). Supports page and size query params; the default sorts first, overrides follow ordered by MSISDN.
• Service-layer scope guards — only one default per client and one override per (client, number) pair are allowed; duplicates return 409 Conflict. The whatsAppNumberId supplied on create must belong to the caller's client; cross-tenant ids return 403 Forbidden.
• Architecture section in the Webhooks guide — Mermaid diagram illustrating the end-to-end message flow between Customer, API Service, Chat Service, and your server. Includes a path-to-endpoint reference table covering notification messages from your server to the API Service (/whatsapp-api-service/v2/channels/whatsapp), live chat messages from your server to the Chat Service (/pl4chat-service/Message/sendMessageWhatsapp, /pl4chat-service/Message/sendMessageWithAttachment), and the webhook URLs configured on WhatsAppClientWebHook.
• Webhook create/update example dropdowns — POST and PUT /payless4messaging-service/WhatsApp/WhatsAppClientWebHook request bodies now ship multiple keyed examples (rendered as a dropdown in the API reference) instead of a single inline example. POST covers Client Default (All Webhooks), Per-Number Override, Incoming Messages Only, Status Updates Only, Chatbot — Auto-Stop on Handover, Chatbot — Always On (Incoming Only), and WhatsApp Lite (with Session Status). PUT covers Update All URLs, Disable a Webhook Type (empty-string clearing), and Toggle Chatbot Flags.
• whatsAppNumberId lookup hint — the whatsAppNumberId field description in the create-webhook schema, the Per-Number Override example description, and the Webhooks guide now point to GET /payless4messaging-service/WhatsApp/WhatsAppClientNumbers/getForCurrentLoginUser?searchString=… for fetching the id with a partial-MSISDN search. The guidance is explicit that the value to send is the nested whatsAppNumber.id (the WhatsAppNumbers UUID) on each WhatsAppClientNumberResponse row, not the top-level id (which is the client–number link).

• POST /payless4messaging-service/WhatsApp/WhatsAppClientWebHook — request body accepts an optional whatsAppNumberId to create a per-number override instead of the client default.
• PUT /payless4messaging-service/WhatsApp/WhatsAppClientWebHook — scope is locked once a row exists; whatsAppNumberId on the request body is ignored. To convert a default into an override (or vice-versa), DELETE and recreate.
• GET /payless4messaging-service/WhatsApp/WhatsAppClientWebHook/getForCurrentLoginUser — now returns only the client default (rows where whatsAppNumberId IS NULL). Use the new /list endpoint to also retrieve per-number overrides.

• DELETE /payless4messaging-service/WhatsApp/WhatsAppClientWebHook is now path-based. The endpoint moves from a request-body shape to DELETE /payless4messaging-service/WhatsApp/WhatsAppClientWebHook/{id}. Update integrations that previously sent the configuration in the request body to put the id in the URL instead.

Released April 2026

• chatbotWebhookURL on WhatsAppClientWebHook — new client-configurable webhook URL that emits chatbot conversation events with full chat participant context (chatParticipantId, conversationStatus, conversationClosed, currently and previously assigned agent ids and names). Coexists with incomingMessageURL; both fire independently when a customer message arrives.
• chatbotIncludeOutgoing flag — opt-in boolean (default false) on WhatsAppClientWebHook. When true, also emit OUTGOING events for bot widget replies (text, button, list, media emitted by flow nodes). Template / notification sends remain on statusUpdateURL.
• chatbotStopOnAgentAssignment flag — opt-in boolean (default false). When true, suppress chatbot webhook emit while the chat participant has an assigned agent.
• ECommChatbotWebHook payload — server-generated eventId (UUID) for receiver-side idempotency, direction (INCOMING / OUTGOING), participant context, agent context, and message details (messageId, ctId, messageType, messageText, mediaUrl, sender/receiver MSISDNs).
• Chatbot conversation payload section — added to the Webhooks guide with incoming / outgoing / post-handover example payloads, gating-flag table, coexistence note with incomingMessageURL, and Node.js / Python / Java handler examples.

• POST and PUT /payless4messaging-service/WhatsApp/WhatsAppClientWebHook — request/response examples and schema descriptions updated to include chatbotWebhookURL, chatbotIncludeOutgoing, and chatbotStopOnAgentAssignment.

Released April 2026

• POST /payless4messaging-service/WhatsApp/WhatsAppClientNumbers/registerWLNumber — register a WhatsApp Lite number and link it to the authenticated user's client. Request body accepts number (required) and hostingType (defaults to WHATSAPP_GO). Provider is set to WL and billing model to message. Returns the linked WhatsAppClientNumbers record on 201 Created; returns 400 Bad Request when the number is missing or already registered to the caller's client.
• RegisterWLNumberRequest schema — added to the OpenAPI spec.

• PUT /pl4chat-service/ChatParticipant/terminateChatParticipantChat — request body example now shows the full ChatParticipant payload rather than a partial set of fields. Description now explains the merge semantics: omitting assignedTo clears the agent assignment, and omitting any of the boolean flags (conversationClosed, missedConversation, afterHoursConversation, sendRatingWidget, chatBotConversation) resets them to false. Recommended practice is to fetch the participant first and echo the complete object back with conversationClosed toggled.
• PUT /payless4messaging-service/WhatsApp/SystemUsers — description rewritten: removed the incorrect claim that the endpoint updates assigned WhatsApp numbers (it does not), clarified that reference-typed fields are partial-merge safe, and lists the 14 Java primitive boolean fields that still reset to false if omitted. Notes that the user is looked up by email + client.clientRef and that role is always force-set to "client" server-side.
• PUT /payless4messaging-service/WhatsApp/api/v1/groups/{id} — added an Important callout noting this is a true full-entity save (saveAndFlush with no merge), so omitted fields will be persisted as null. Recommends fetching the group first with the matching GET and sending the complete object back.

Released April 2026

• Pagination on GET /pl4chat-service/ChatParticipant — the default chat participant endpoint now accepts page (zero-based, default 0) and size (default 10) query parameters. Example: GET /pl4chat-service/ChatParticipant?page=0&size=10. Live Chat guide examples (cURL, Node.js, Python, Java) updated to use the new parameters.

Released April 2026

• Chatbot conversation flow guide — three-step walkthrough for chatbot integrations: receive webhook, look up chat participant by sender number, and retrieve full message history including tracking number and mark-as-read alternatives.
• Endpoint selection table — choose from all, assigned, unassigned, closed, missed, or after-hours participant endpoints with searchString filtering.
• Cross-references to chatbot flow — added links from the Conversations guide and the Live Chat API reference to the chatbot conversation flow guide.
• Code examples for chat endpoints — cURL, Node.js, Python, and Java examples for ChatParticipant, getMessagesByChatParticipant, and Message/trackingNumber.

Released January 2026

A major release introducing the unified messaging endpoint, dedicated channel endpoints, and comprehensive platform management capabilities.

• Unified messaging endpoint (POST /v2/messages) — single endpoint that routes to WhatsApp or SMS based on the channel field.
• Dedicated channel endpoints — POST /v2/channels/whatsapp and POST /v2/channels/sms for channel-specific integrations.
• Typing indicator — show a typing bubble before sending messages via WhatsApp.
• Carousel templates — multi-card scrollable template component type.
• Call to Action templates — interactive button templates with conversationState tracking.
• Batch execution control — pause, resume, and cancel batch message jobs.
• Message processing configuration — daily send schedules, throttling, and batch size controls per number.
• Contact management — full CRUD operations for customer contact records.
• Block & blacklist management — block/unblock numbers and manage blacklists via API.
• Ticket management — support tickets with status workflows (OPEN, AWAITING_AGENT, AWAITING_CUSTOMER, RESOLVED, CLOSED).
• Report downloads — export notification, interaction, and MAU reports as XLSX or CSV.

• SMS fallback — now supports custom fallback text and per-message encoding options (unicode field).
• Template management — expanded to 11 template types including authentication, flow, and carousel templates.
• Message status tracking — enhanced delivery reports with detailed failure codes and reasons.
• Error responses — standardized error format with requestId for all endpoints.

Released November 2025

Introduces persistent WhatsApp conversations that stay open beyond the standard 24-hour session window.

• Long-lived conversations — create WhatsApp conversations that persist for days, weeks, or months until explicitly closed.
• Five conversation message types — Text Only, Text + Media, Call to Action, Card, Quick Reply.
• Conversation lifecycle management — create, send messages, check remaining time, and close conversations via API.
• Conversation analytics — track submitted, sent, delivered, read, and failed counts per conversation.
• Quick Reply buttons — conversationState parameter controls whether buttons keep the conversation open (start) or close it (end).
• Conversation listing — list conversations by user or client reference with pagination.

The eCommunicate API uses URL path versioning (/v2/). When breaking changes are introduced, a new version path is created. Previous versions continue to function during the deprecation period.