Migrations & Deprecations

This page collects API migrations. Most map a deprecated endpoint to its replacement; some are data-model migrations — new fields you should adopt now for a change arriving on an external timeline, with no endpoint to swap. The alpha usernames (BSUID) migration below is the latter kind.

Deprecated endpoints are still live — they are marked deprecated in the reference (struck through in the nav) but continue to work, so existing integrations keep running. Unless a removal date is stated, there is none yet; migrate at your own pace. New integrations should use the latest endpoints from the start. Each deprecated operation's description links to its replacement.

WhatsApp is rolling out alpha usernames. Each customer now has a durable, business-scoped user id (BSUID, e.g. ZA.1021033720668862) that is stable for your business even if the customer changes their phone number, and that is present on inbound events even when the phone number is withheld. Customers may also set an optional username (display only).

This is a forward-looking, adopt-now migration, not an endpoint deprecation: the phone number remains the primary identifier today, nothing is being removed on our side, and the timeline is driven by Meta. Store the BSUID now so you're ready as phone numbers become optional.

• Persist the BSUID as your durable customer key. On incoming and chatbot webhooks it arrives as senderUserId / recipientUserId, with the optional display username alongside. Key your CRM / customer records on it rather than the phone number, which may change or be withheld.
• Address sends by BSUID where you have it. Send recipients accept customerUserId (the BSUID) in addition to to. Supply both (the phone takes precedence, the BSUID rides along as a fallback), or customerUserId alone to reach a recipient with no phone number.
• Read the BSUID on chat participants. The lean ChatParticipantResponse carries userId (the customer BSUID) and username, so live-chat surfaces can match a customer even when the number is absent.

The live-chat API has moved to a leaner v2 surface. The v2 endpoints return curated payloads (only the fields a chat UI needs), unify sending across channels, and add quoted-reply context.

• Lean payloads. v1 returned the full internal entity; v2 returns curated DTOs (MessageResponse, ChatParticipantResponse) with null fields omitted.
• One send endpoint for every channel. Instead of per-channel send operations, a single Send an agent message (v2) routes by a channel field (WHATSAPP, WEB, FACEBOOK).
• Media is a two-step, channel-agnostic flow. Upload once, then send the returned mediaUrl on any channel.
• Quoted replies. MessageResponse carries quotedExternalMessageId and quotedText for messages that reply to/quote an earlier message.
• Scoped chat lists. A single list endpoint selects the view with a scope filter rather than separate per-tab operations.
• Identity from context. The agent is resolved from your API key / session — you no longer send agent or participant objects in the request body.

There is also a new Get a message by ctId (v2) lookup (lean, tenant-checked), and Get a chat (v2) to fetch a single chat.

The v2 chatbot webhook payload no longer ships the nested chatParticipant object (it was redundant and carried SystemUser credentials). Read agent identity and lifecycle from the flat fields (assignedAgentId, assignedAgentName, conversationStatus, conversationClosed, …) and reply with a single Send an agent message (v2) call using the payload's chatParticipantId.

User endpoints have moved to a v1 surface under /api/v1/users. The v1 endpoints return a credential-free UserResponse — never password, apiKey, or token fields — and user creation no longer accepts a caller-supplied password.

• Credential-free responses. v1 endpoints return UserResponse / CreateUserResponse DTOs with null fields omitted, instead of the credential-bearing SystemUser entity.
• No caller-supplied password on create. Create a user generates a single-use temporaryPassword, returned once in the response; the user sets their own password on first login.
• Update by id. Update a user identifies the target by id in the body and carries no credentials.
• Identity from context. The "my" endpoints (profile, password, credits) resolve the user from your API key / session — you no longer pass a user object.

Beyond identity and live-chat fields, UserResponse carries the user's client context and account status: clientId, clientRef, countryTimezone, and popiaComplianceEnabled (inherited from the client), plus resetPasswordEmailSent, emailVerified, tempPasswordValid, and validToken.