{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Migrations & Deprecations","description":"Complete developer documentation for the eCommunicate Omnichannel platform. WhatsApp Cloud, WhatsApp Lite, SMS, Live Chat, and Conversations APIs. Send messages, manage templates, configure webhooks, and build customer engagement at scale.","siteUrl":"https://docs.ecommunicate.co.za","keywords":["eCommunicate API","WhatsApp Business API","SMS API","omnichannel messaging","WhatsApp templates","messaging platform","South Africa messaging API"],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"migrations--deprecations","__idx":0},"children":["Migrations & Deprecations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page collects API migrations. Most map a deprecated endpoint to its replacement; some are"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["data-model migrations"]}," — new fields you should adopt now for a change arriving on an external"," ","timeline, with no endpoint to swap. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#alpha-usernames-bsuid"},"children":["alpha usernames (BSUID)"]}," migration"," ","below is the latter kind."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"deprecation-policy","__idx":1},"children":["Deprecation policy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deprecated endpoints are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["still live"]}," — they are marked ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"alpha-usernames-bsuid","__idx":2},"children":["Alpha usernames (BSUID)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["WhatsApp is rolling out ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["alpha usernames"]},". Each customer now has a durable, business-scoped user"," ","id (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["BSUID"]},", e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ZA.1021033720668862"]},") that is stable for your business even if the customer"," ","changes their phone number, and that is present on inbound events ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["even when the phone number is"," ","withheld"]},". Customers may also set an optional ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["username"]}," (display only)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is a forward-looking, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-to-change","__idx":3},"children":["What to change"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Persist the BSUID as your durable customer key."]}," On incoming and chatbot webhooks it arrives as"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["senderUserId"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipientUserId"]},", with the optional display ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["username"]}," alongside. Key your CRM /"," ","customer records on it rather than the phone number, which may change or be withheld."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Address sends by BSUID where you have it."]}," Send recipients accept ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerUserId"]}," (the BSUID)"," ","in addition to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to"]},". Supply both (the phone takes precedence, the BSUID rides along as a fallback),"," ","or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerUserId"]}," alone to reach a recipient with no phone number."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Read the BSUID on chat participants."]}," The lean ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ChatParticipantResponse"]}," carries ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userId"]}," (the"," ","customer BSUID) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["username"]},", so live-chat surfaces can match a customer even when the number is"," ","absent."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"where-the-fields-appear","__idx":4},"children":["Where the fields appear"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Surface"},"children":["Surface"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fields"},"children":["Fields"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Reference"},"children":["Reference"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Incoming & chatbot webhooks"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["senderUserId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipientUserId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["username"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/webhooks#webhook-payload-schemas"},"children":["Webhooks guide"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send recipients"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerUserId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/whatsapp-messaging"},"children":["WhatsApp Messaging"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/conversations"},"children":["Conversations"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Chat participants"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["username"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/live-chat#chat-participants"},"children":["Live Chat guide"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"`userId` on agents means something different"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On the customer-facing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ChatParticipant"]}," / send surfaces, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userId"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerUserId"]}," is the customer"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["BSUID"]},". The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userId"]}," on a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SystemUser"]}," (agent) is your own external agent identifier — unrelated."," ","Don't conflate the two."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"live-chat-v2","__idx":5},"children":["Live Chat v2"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The live-chat API has moved to a leaner ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["v2"]}," surface. The v2 endpoints return curated payloads"," ","(only the fields a chat UI needs), unify sending across channels, and add quoted-reply context."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-changed","__idx":6},"children":["What changed"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Lean payloads."]}," v1 returned the full internal entity; v2 returns curated DTOs"," ","(",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MessageResponse"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ChatParticipantResponse"]},") with null fields omitted."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["One send endpoint for every channel."]}," Instead of per-channel send operations, a single"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/sendmessagev2"},"children":["Send an agent message (v2)"]}," ","routes by a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel"]}," field (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WHATSAPP"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WEB"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FACEBOOK"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Media is a two-step, channel-agnostic flow."]}," Upload once, then send the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mediaUrl"]}," on"," ","any channel."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Quoted replies."]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MessageResponse"]}," carries ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quotedExternalMessageId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quotedText"]}," for"," ","messages that reply to/quote an earlier message."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Scoped chat lists."]}," A single list endpoint selects the view with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope"]}," filter rather than"," ","separate per-tab operations."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity from context."]}," The agent is resolved from your API key / session — you no longer send"," ","agent or participant objects in the request body."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"endpoint-mapping","__idx":7},"children":["Endpoint mapping"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Deprecated (v1)"},"children":["Deprecated (v1)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Replacement (v2)"},"children":["Replacement (v2)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/getmessagesbychatparticipant"},"children":["Get messages by chat participant"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/getmessagesv2"},"children":["Get messages for a chat participant (v2)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Lean ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MessageResponse"]},", includes quoted-reply fields"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/sendagentmessagewhatsapp"},"children":["Send WhatsApp agent reply"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/sendmessagev2"},"children":["Send an agent message (v2)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel: WHATSAPP"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/sendagentmessagewithattachment"},"children":["Send agent reply with attachment"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/uploadmediav2"},"children":["Upload media"]}," → ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/sendmessagev2"},"children":["Send an agent message (v2)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Upload once, send the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mediaUrl"]}," (content type defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MEDIA"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/sendchattypingindicator"},"children":["Send typing indicator (Chat)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/sendtypingindicatorv2"},"children":["Send typing indicator (v2)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pass only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participantId"]},"; sender/recipient resolved server-side"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/markreadbyagent"},"children":["Mark message as read by agent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/markasreadv2"},"children":["Mark a conversation as read (v2)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Clears the unread badge and sends the read receipt in one call"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/getchatparticipants"},"children":["Get chat participants"]}," and the per-tab lists (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["getMyParticipants"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["getTeamParticipants"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["getUnAssignedParticipants"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["getClosedParticipants"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["getMissedParticipants"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["getMissedAfterHoursParticipants"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["getMyMissedParticipants"]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/listchatsv2"},"children":["List chats (v2)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pick the tab with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["my"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["team"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unassigned"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["closed"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["missed-agent"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["missed-after-hours"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["my-missed"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["open"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["all"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/getparticipantsbyassignedto"},"children":["Get conversations assigned to a specific agent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/listchatsv2"},"children":["List chats (v2)"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope=my"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["v2 uses the agent from your API key — returns ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["your"]}," assigned chats; arbitrary-agent lookup is not carried forward"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/terminatechatparticipantchat"},"children":["Terminate or reopen a chat conversation"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/terminatechatv2"},"children":["Terminate a chat (v2)"]}," / ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/openchatv2"},"children":["Reopen a chat (v2)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pass only the chat id; no full-object merge"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/getchatmessagesbytrackingnumber"},"children":["Get chat messages by tracking number"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/getmessagesbytrackingnumberv2"},"children":["Get messages by tracking number (v2)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Lean ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MessageResponse"]},", scoped to your client"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is also a new ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/getmessagebyctidv2"},"children":["Get a message by ctId (v2)"]}," ","lookup (lean, tenant-checked), and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/getchatv2"},"children":["Get a chat (v2)"]}," ","to fetch a single chat."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"chatbot-webhook-v2","__idx":8},"children":["Chatbot webhook v2"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v2"]}," chatbot webhook payload no longer ships the nested ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chatParticipant"]}," object (it was"," ","redundant and carried ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SystemUser"]}," credentials). Read agent identity and lifecycle from the flat"," ","fields (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["assignedAgentId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["assignedAgentName"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conversationStatus"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conversationClosed"]},", …) and"," ","reply with a single ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/live-chat/sendmessagev2"},"children":["Send an agent message (v2)"]}," ","call using the payload's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chatParticipantId"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"user-management-v1","__idx":9},"children":["User Management v1"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["User endpoints have moved to a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["v1"]}," surface under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v1/users"]},". The v1 endpoints return a"," ","credential-free ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UserResponse"]}]}," ","— never password, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiKey"]},", or token fields — and user creation no longer accepts a"," ","caller-supplied password."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-changed-in-v1","__idx":10},"children":["What changed in v1"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Credential-free responses."]}," v1 endpoints return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UserResponse"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CreateUserResponse"]}," DTOs"," ","with null fields omitted, instead of the credential-bearing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SystemUser"]}," entity."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["No caller-supplied password on create."]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/createuser"},"children":["Create a user"]}," ","generates a single-use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["temporaryPassword"]},", returned once in the response; the user sets their"," ","own password on first login."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},"."]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/updateuser"},"children":["Update a user"]}," ","identifies the target by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," in the body and carries no credentials."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity from context."]}," The \"my\" endpoints (profile, password, credits) resolve the user from"," ","your API key / session — you no longer pass a user object."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"endpoint-mapping-user-management","__idx":11},"children":["Endpoint mapping (User Management)"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Deprecated (legacy)"},"children":["Deprecated (legacy)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Replacement (v1)"},"children":["Replacement (v1)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/createsystemuser"},"children":["Create a system user"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/createuser"},"children":["Create a user"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Takes no password; returns a one-time ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["temporaryPassword"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/updatesystemuser"},"children":["Update a system user"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/updateuser"},"children":["Update a user"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identified by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},"; credential-free; returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UserResponse"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/getcurrentuser"},"children":["Get current logged-in user"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/getme"},"children":["Get my profile"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Credential-free ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UserResponse"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/getclientusers"},"children":["Get current client users"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/listclientusers"},"children":["List client users"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Credential-free ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UserResponse"]}," records"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/getusersforclient"},"children":["Get users for a client"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/getuserspage"},"children":["List users (paginated)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Paginated, credential-free ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UserResponse"]}," records"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/changeavailabilitystatus"},"children":["Change available status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/changeavailability"},"children":["Change availability"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Credential-free ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UserResponse"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/updateagentchatlimit"},"children":["Update agent chat limit"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/setagentchatlimit"},"children":["Set agent chat limit"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Behaviour identical"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/changepassword"},"children":["Change password"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/changemypassword"},"children":["Change my password"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Behaviour identical"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/getwhatsappcreditsforcurrentloginuser"},"children":["Get WhatsApp credits for current user"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ecommunicate-api-docs.redocly.app/apis/omnichannel/user-management/getmycredits"},"children":["Get my WhatsApp credits"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Behaviour identical"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"userresponse-fields","__idx":12},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UserResponse"]}," fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Beyond identity and live-chat fields, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UserResponse"]}," carries the user's client context and account"," ","status: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientRef"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["countryTimezone"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["popiaComplianceEnabled"]}," (inherited from"," ","the client), plus ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["resetPasswordEmailSent"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["emailVerified"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tempPasswordValid"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validToken"]},"."]}]},"headings":[{"value":"Migrations & Deprecations","id":"migrations--deprecations","depth":1},{"value":"Deprecation policy","id":"deprecation-policy","depth":2},{"value":"Alpha usernames (BSUID)","id":"alpha-usernames-bsuid","depth":2},{"value":"What to change","id":"what-to-change","depth":3},{"value":"Where the fields appear","id":"where-the-fields-appear","depth":3},{"value":"Live Chat v2","id":"live-chat-v2","depth":2},{"value":"What changed","id":"what-changed","depth":3},{"value":"Endpoint mapping","id":"endpoint-mapping","depth":3},{"value":"Chatbot webhook v2","id":"chatbot-webhook-v2","depth":3},{"value":"User Management v1","id":"user-management-v1","depth":2},{"value":"What changed in v1","id":"what-changed-in-v1","depth":3},{"value":"Endpoint mapping (User Management)","id":"endpoint-mapping-user-management","depth":3},{"value":"UserResponse fields","id":"userresponse-fields","depth":3}],"frontmatter":{"title":"Migrations & Deprecations","description":"Versioned migrations and deprecation mappings across the eCommunicate API. Migrate at your own pace.","seo":{"title":"Migrations & Deprecations"}},"lastModified":"2026-07-16T09:46:36.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/migrations","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}