Question
This is the flow of my messaging conversation:
- A message from an end-user is integrated to the messaging channel.
- A Sunshine Conversations user and conversation are created, or the system finds an existing user and a conversation.
- Sunshine Conversations passes a message to a bot, or if no bot is enabled, directly to Zendesk.
- A bot passes the message to Zendesk.
- Zendesk receives an inbound webhook with user and message data.
- Zendesk verifies the following:
- A matching
externalId
is present for user matching. - A session is created if one doesn't already exist for the conversation.
- A ticket already exists without a Closed status, with the Sunshine Conversations
conversationId
anduserId
.- If there is an existing ticket not in Closed status, new messages are threaded into the existing ticket.
- If there is no existing open ticket, a new ticket is created.
- If there is no matching ticket or user, a new Zendesk user and ticket are created.
- In Agent Workspace, the chat session populates the conversation.
- A matching
During this flow, I noticed two users are created. What is the difference between these two users?
Answer
The difference between a user in Zendesk and a user in Sunshine Conversations
In any Sunshine Conversations channel, or when a user interacts with messaging, a Sunshine Conversations user is associated with them on the backend, with a primary identifier named ID
. This value is reflected in the Sunshine Conversations v2 API.
In Zendesk, the ID
differs from userId
. When using the v1 Sunshine Conversations API, this user value is appUserId
. Zendesk assigns the userId
on user creation. This value appears within the URL of the user profile and is also available with the User API.
The impact of end-user authentication on user objects
For Sunshine Conversations, if the user is authenticated, an externalId
is associated with the user in Sunshine Conversations, in addition to their appUserId
.
If the user is unauthenticated, Zendesk can temporarily keep track of them using the storage of their browser session. Associate the returning user with the same Sunshine Conversations appUserId
as long as the user visits a page of the same domain in the same browser and doesn't delete their local storage. There is no way to track the user across various browsers if the user doesn't authenticate.
For more information about how to authenticate users based on the customer’s configuration, see these articles:
- Authenticating end users in Messaging
- Authenticating end users with Sunshine Conversations (for non-Messaging customers)
The same will apply for Zendesk Support; only the authenticated user will have an external_id
value linked to their Zendesk user.
External identifiers
The externalId
is a unique identifier for the user. Use a value from your existing user database, such as your website username or an existing ID from your authentication system. The externalId
for a Sunshine Conversations user is set at user creation, or with the authentication method mentioned above. For Sunshine Conversations, the externalId
links a user to the same conversation across multiple devices.
Individual clients may also have an externalId
value. A client externalId
does not impact or overwrite the externalId
of the Sunshine Conversations user.
In Support, the external_id is a unique identifier from another system, which maps Support to third-party integrations. Like the userId
, this attribute is available within the API, and null
by default. Set this value with SSO or update it with the API.
Once a Sunshine Conversations user sends a message to Zendesk, the external_id
value on a Zendesk user is used to map incoming conversations with messaging and the Sunshine Conversations externalId
.
A Sunshine Conversations user with the Sunshine Conversations V2 API will look like this:
{
"user": {
"signedUpAt": "2021-04-07T18:50:14.148Z",
"hasPaymentInfo": false,
"identities": [],
"id": "c7d20a8aace3bcb1a61c5fb8",
"externalId": "NewExternalId",
"profile": {
"surname": "Lawrence",
"givenName": "Corwin",
"locale": "en-US"
},
"metadata": {}
}
}
The V1 API reflects something similar to this:
{
"appUser": {
"surname": "Lawrence",
"givenName": "Corwin",
"signedUpAt": "2021-04-07T18:50:14.148Z",
"hasPaymentInfo": false,
"identities": [],
"_id": "c7d20a8aace3bcb1a61c5fb8",
"userId": "NewExternalId",
"conversationStarted": true,
"clients": {...
And a linked user reflects the below:
{
"users": [
{
"id": 15594370384155,
"url": "https://z3ncorwinlawrenceaw.zendesk.com/api/v2/users/15594370384155.json",
"name": "Web User NewExternalId",
"email": "corwin@corwin.com",
"created_at": "2023-05-19T14:17:30Z",
"updated_at": "2023-06-22T19:44:49Z",
"time_zone": "America/New_York",
"iana_time_zone": "America/New_York",
"phone": null,
"shared_phone_number": null,
"photo": null,
"locale_id": 1,
"locale": "en-US",
"organization_id": null,
"role": "end-user",
"verified": true,
"external_id": "NewExternalId",
"tags": []...
If this same Sunshine Conversations user sends a new message, that message is mapped to the Zendesk user shown in the third call, based on the matching externalId
.
For more information, see these articles: