feat(docs): add suggested_email to the customer object and update_customer - #1692
Merged
Conversation
mdojwa
force-pushed
the
EUEE-1740-suggested-email
branch
2 times, most recently
from
August 27, 2026 10:08
d4e230b to
4d1ab61
Compare
…tomer EUEE-1740. `suggested_email` holds an email address captured for a customer without their confirmation - the widget can propose one, and an agent accepts or dismisses it. It never keys identity merging and never counts towards a segment, including the built-in lead segments, although a customer holding only a suggestion is still returned by the customer list. The field exists in 3.6 and 3.7 only, following `phone_number` and `address`. The two versions differ on one point: 3.7 models it as a nullable string, so an empty value clears a suggestion, while 3.6 collapses an empty value to "field not sent" - and since the empty value then counts as no update at all, a 3.6 `update_customer` request carrying nothing else fails validation. That is the same split that already applies to `name`, `email`, `phone_number` and `address`, so the field joins the "Allows to clear the values of..." sentence on the 3.7 pages, and the 3.6 tables spell out that clearing needs 3.7. Both APIs get read and write coverage: the Customer data structure, `get_customer`, `update_customer` and the `customer_updated` push. Customer Chat API additionally documents `customer.suggested_email` on `login`, which accepts it the way it already accepts `phone_number`; on that method an omitted field means "leave it alone" and only an explicit empty value clears a suggestion. The Agent Chat API push sample uses the acceptance shape - a confirmed `email` together with an empty `suggested_email` - because a delta carrying a valid `email` and a non-empty suggestion cannot occur: the backend applies `email` first and then drops the suggestion. The Customer Data Platform spec under src/configs/redoc is deliberately left alone: the documentation team syncs it from the monorepo spec.
mdojwa
force-pushed
the
EUEE-1740-suggested-email
branch
from
August 28, 2026 06:58
4d1ab61 to
92783b4
Compare
The v3.7 Agent Chat API Customer table lost both fields at some point - the page looks like it was branched before they landed in 3.6 and was never caught up. Both are real in 3.7: services/agent-api/parsers/3.7/objects.go carries PhoneNumber and Omnichannel on UserCustomer, and both lc-sdk-go and lc-sdk-js declare them on the agent Customer in their v3.7 branches. Restored in the positions they hold in the 3.6 table.
customer-api has accepted `phone_number` on `update_customer` since 3.6
(services/customer-api/parsers/3.{6,7}/methods/update_customer.go, validated as
E.164), and both SDKs expose it on the customer side - lc-sdk-go's
customer.UpdateCustomer takes it and lc-sdk-js declares it on the customer
CustomerParameters, on v3.6 and v3.7 alike. Only the docs were missing it, on
all four pages: Web and RTM, both versions.
Placed after `avatar`, the position it holds on the agent pages.
This was referenced Aug 28, 2026
Merged
Merged
Merged
mdojwa
marked this pull request as ready for review
August 29, 2026 15:58
There was a problem hiding this comment.
🟡 Changes recommended
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Documents suggested_email across Agent and Customer Chat APIs for v3.6/v3.7.
Changes:
- Adds field, update, retrieval, login, push, and changelog documentation.
- Documents version-specific clearing behavior.
- Restores missing
phone_numberandomnichannelfields.
File summaries
| File | Description |
|---|---|
src/pages/messaging/customer-chat-api/v3.7/rtm-reference/index.mdx |
Updates v3.7 RTM methods. |
src/pages/messaging/customer-chat-api/v3.7/rtm-pushes/index.mdx |
Explains cleared suggestions. |
src/pages/messaging/customer-chat-api/v3.7/index.mdx |
Updates v3.7 Web methods. |
src/pages/messaging/customer-chat-api/v3.7/data-structures/index.mdx |
Adds the customer field. |
src/pages/messaging/customer-chat-api/rtm-reference/index.mdx |
Updates v3.6 RTM methods. |
src/pages/messaging/customer-chat-api/rtm-pushes/index.mdx |
Documents push semantics. |
src/pages/messaging/customer-chat-api/index.mdx |
Updates v3.6 Web methods. |
src/pages/messaging/customer-chat-api/data-structures/index.mdx |
Adds the v3.6 field. |
src/pages/messaging/customer-chat-api/changelog/index.mdx |
Records Customer API changes. |
src/pages/messaging/agent-chat-api/v3.7/rtm-reference/index.mdx |
Updates v3.7 RTM methods. |
src/pages/messaging/agent-chat-api/v3.7/rtm-pushes/index.mdx |
Adds acceptance push example. |
src/pages/messaging/agent-chat-api/v3.7/index.mdx |
Updates v3.7 Web methods. |
src/pages/messaging/agent-chat-api/v3.7/data-structures/index.mdx |
Adds and restores customer fields. |
src/pages/messaging/agent-chat-api/rtm-reference/index.mdx |
Updates v3.6 RTM methods. |
src/pages/messaging/agent-chat-api/rtm-pushes/index.mdx |
Adds suggestion-clearing semantics. |
src/pages/messaging/agent-chat-api/index.mdx |
Updates v3.6 Web methods. |
src/pages/messaging/agent-chat-api/data-structures/index.mdx |
Adds the v3.6 field. |
src/pages/messaging/agent-chat-api/changelog/index.mdx |
Records Agent API changes. |
payloads/messaging/v3.7/customer-chat-api/users/customer.json |
Adds the field to fixture. |
payloads/messaging/v3.7/agent-chat-api/users/customer.json |
Adds the field to fixture. |
payloads/messaging/v3.6/customer-chat-api/users/customer.json |
Adds the field to fixture. |
payloads/messaging/v3.6/agent-chat-api/users/customer.json |
Adds the field to fixture. |
Review details
- Files reviewed: 22/22 changed files
- Comments generated: 5
- Review effort level: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
suggested_email is stored as sent, like every other customer field: the confirmed email does not hold a suggestion back, and the address format is not checked on the way in - matching email, which documents neither.
The field is new in 3.6, so it is modelled as a nullable string there as well - it never had the frozen plain-string shape that stops email and phone_number from being cleared in that version.
oliwiapolec
reviewed
Sep 7, 2026
Co-authored-by: oliwiapolec <54406259+oliwiapolec@users.noreply.github.com>
oliwiapolec
approved these changes
Sep 8, 2026
|
🎉 This PR is included in version 2.104.0 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR information
What does this PR do?
Documents a new public field,
suggested_email: an email address captured for a customer without their confirmation. The widget can propose one; an agent accepts it (setsemail, clears the suggestion) or dismisses it. It never keys identity merging and never counts towards a segment, including the built-in lead segments — though a customer holding only a suggestion is still returned by the customer list. It is independent ofemail: both can be set at once, and only an explicit accept or dismiss removes the suggestion.Backend PR chain: https://github.com/livechat/api/pull/6203 and the ten PRs stacked on it. This PR should merge together with them, not before.
Where the field shows up
get_customer(Web + RTM)update_customer(Web + RTM)loginrequest (RTM)customer.suggested_emailcustomer_updatedpushVersions: 3.6 and 3.7, with one real difference
The field exists in 3.6 and 3.7 only, following
phone_numberandaddress.Both versions model it as a nullable string, so an empty value clears a suggestion in either — the field therefore joins the existing "Allows to clear the values of…" sentence on the 3.7 pages, and the 3.6 tables say plainly that an empty value clears it.
This is not the usual 3.6/3.7 split.
name,email,phone_numberandaddresscannot be cleared in 3.6 because their shapes were frozen when that version shipped;suggested_emailis new in 3.6, so nothing depended on it collapsing an empty value into an absent one, and an agent or widget on 3.6 can dismiss a suggestion.On
loginan omitted field means "leave it alone", never "clear it" — only an explicit empty value dismisses.Not in this PR
src/configs/redoc/customer-data-platform-api/spec.ymlis untouched — the documentation team syncs it from the monorepo CDP spec, which gains the field in https://github.com/livechat/api/pull/6342.Type of change
Deploy preview
The deploy preview link will appear in the checks section below once the build is complete.
Also fixed here, in separate commits
phone_numberandomnichannelon the v3.7 Agent Customer table — the page looks branched from before they landed in 3.6 and never caught up. Both are real in 3.7 (agent-api/parsers/3.7/objects.go, and both SDKs on theirv3.7branches). Restored in their 3.6 positions.phone_numberon the customerupdate_customer—customer-apihas accepted it since 3.6 (validated as E.164) and both SDKs expose it; only the docs were missing it, on all four pages.Pre-existing drift noticed, deliberately not fixed
The Customer SDK
updateCustomerreference lists onlyname,emailandsessionFields. That page documents the chat-widget SDK, a different package fromlc-sdk-js— out of scope here.