Help center authentication for messaging (EAP)

With this Early Access Program (EAP), the Web Widget automatically uses the identity of end users when they are signed in to the help center. The system shares their name and email with agents (see Data mapping). To use this feature, set up web widget to add messaging to your help center. There is no additional configuration.

Users can also start a Web Widget conversation while signed out. If they sign in to the help center during the conversation, the system updates or merges their previous unauthenticated session with their authenticated profile, allowing them to continue seamlessly as the signed-in user.

For Web Widgets embedded outside the help center, authentication continues to use JWT-based method as before. This new help center authentication option applies only to Web Widgets embedded within the Zendesk help center and does not affect Zendesk Mobile SDKs.

Known issues

Here are a few limitations concerning this early access program. Collection of feedback during this program will help us to determine how best to mitigate these issues.

• AI agents are not yet fully integrated with this feature. If an AI Agent is set to ask users for their name and email when escalating to a human agent, authenticated help center users will be asked to provide this information again. AI agents that are configured to recommend restricted article content to authenticated users are also not yet integrated with this new authentication option. Both of these issues can be mitigated by assigning an external_id to the Zendesk user.
• Multi-brand is not yet supported. The new authentication behavior will currently only function in the account's main brand.
• This feature is not compatible with Advanced encryption.
• Synchronization of an authenticated user's data into Sunshine Conversations only happens during the first time the web widget loads in the help center. This means that additional API-level integration may be necessary in order to keep Sunshine Conversations user data in sync.
• The Voice API call button is not supported.

zendeskId property

The EAP introduces a zendeskId property that links a messaging user to their corresponding core Zendesk user record. Messaging users exist as separate objects but are connected to the main Zendesk user through this identifier.

While an external_id can link help center messaging users across different applications, it is not mandatory. To clarify the authentication status, messaging users now include an authenticated boolean property. Previously, JWT authentication was the sole method to authenticate messaging users, and the absence of an external_id indicated an unauthenticated user. The authenticated property now explicitly signals whether a messaging user has been authenticated.

{
  "user": {
    "id": "67fd2a0f8dda4605934a8abf",
    "zendeskId": "31240610949271",
    "authenticated": "true",
    ...
  }
}

Data mapping

Zendesk messaging uses a different user model than the core Zendesk user records that agents access in Agent Workspace. The core user records are available through the Ticketing API, while messaging users are accessed through the Sunshine Conversations API. Since these two user schemas differ, when the Web Widget links a messaging user to a Zendesk user, only the following user properties are transferred to the messaging user.

Zendesk core user data	Messaging user representation	Agent Workspace UI
id	zendeskId	Not shown
name	profile.givenName profile.surname	Visible in: - Conversation history - User essentials card - User profile view
identities	identities (primary email only)	Visible in: - User essentials card - User profile view
external_id	externalId	Visible in: - User profile view

Example Zendesk user mapping:

{
  "user": {
    "id": 31240610949271,
    "external_id": "01JRTE8SFDV4088CX0T1PJZMVE",
    "name": "Roger Wilco",
    "email": "[email protected]",
  }
}

{
  "identities": [{
    "id": 31240574951063,
    "user_id": 31240610949271,
    "type": "email",
    "value": "[email protected]",
    "primary": true,
    "verified": true,
    "verification_method": "full",
    "verified_at": "2025-04-07T21:42:50Z",
  }, {
    "id": 31240574958359,
    "user_id": 31240610949271,
    "type": "email",
    "value": "[email protected]",
    "primary": false,
    "verified": true,
    "verification_method": "full",
    "verified_at": "2025-04-07T21:42:50Z",
  }]
}

Example messaging user mapping:

{
  "user": {
    "id": "67fd2a0f8dda4605934a8abf",
    "zendeskId": "31240610949271",
    "authenticated": "true",
    "externalId": "01JRTE8SFDV4088CX0T1PJZMVE",
    "profile": {
      "givenName": "Roger",
      "surname": "Wilco"
    },
    "identities": [
      {
        "type": "email",
        "value": "[email protected]",
        "verification": "full"
      }
    ]
  }
}

Manually synchronizing user data

When an end user first authenticates with the Web Widget through the help center, the messaging user is populated with the corresponding Zendesk user’s name, email, and external_id, as described in Data mapping. However, Zendesk user properties can be changed manually through the Agent Workspace or the Ticketing API. For example, the properties can change when an agent updates a user’s primary email address. Messaging users can also be modified through the Sunshine Conversations API. These changes may cause the Zendesk user and its linked messaging user to become out of sync.

To address this, a synchronize user action is available to update the messaging user data. By providing a zendeskId, the API locates both the Zendesk user and messaging user associated with that id and updates the messaging user with the Zendesk user’s current name, email, and external_id.

Use caution when synchronizing, as external_ids and email addresses must remain unique within an account. To maintain this uniqueness, other messaging users may be modified to resolve conflicts. Specifically:

• The synchronize user API may merge two messaging users if a Zendesk user’s external_id matches a different messaging user. In this case, the synchronization will combine those messaging users.
• The API will not merge two messaging users that correspond to different Zendesk users through zendeskId. However, it may transfer email addresses or external_ids between messaging users to reflect changes in ownership on the Zendesk user side.

Linking users across application boundaries

End user identities can span multiple applications by assigning a unique external_id to each user. When users sign into the help center through single sign-on (SSO), you can assign an external_id by including it as an additional SAML assertion or as a custom attribute in OIDC. The custom SSO option also supports the external_id claim. Alternatively, you can assign an external_id directly to a user using the Users API.

When embedding messaging through the Web Widget or Mobile SDK within your own application, separate from the Zendesk help center, your application manages user authentication independently. In this case, JWT-based authentication bridges your user’s authentication state into the embedded messaging experience. If the external_id in the messaging JWT matches the external_id assigned to the corresponding core Zendesk user, Zendesk unifies the user’s identity across platforms. This enables end users to access the same conversation history whether they interact through the help center or through an embedded widget or SDK within your application.

It's important to note that the messaging user will only be synchronized with the Zendesk user's external_id, name and email address the first time the user logs in to the help center, and the web widget loads. It is therefore ideal to set the external_id on the Zendesk user as soon as possible, such as during user creation or as part of single sign-on. If a messaging user logs in to the help center before the associated Zendesk user has had an external_id assigned, then this synchronization window is missed. The messaging user will have a zendeskId, name, and email, but they will not have the externalId that is necessary for linking the user's experience across applications. If this user then tries to access messaging from a Mobile SDK or Web Widget embedded inside of your own application where you have JWT-based authentication set up, Sunshine Conversations will either create a separate user record, or the authentication will fail with an email conflict error.

To correct this problem, you first need to assign the external_id to the Zendesk user via the Update Users API. You can then re-synchronize that Zendesk user into Sunshine Conversations using the Synchronize User API.

Custom Web Widget initialization behavior

The Web Widget offers JavaScript APIs which allow you to customize some of the widget's behavior. You can use these APIs to programmatically open the widget, for example. You might also want the Web Widget to only load on your help center for authenticated users.

It is possible to provide your own Web Widget initialization code by modifying your help center theme, however when you are leveraging help center authentication for messaging as part of this EAP, the Widget must be initialized in a different way. With this EAP, the Web Widget exposes a new useSessionAuth method, which can be used as follows:

1. Ensure that automatic Web Widget loading is disabled in Admin Center. Go to Channels > Messaging > Web Widget > Installation and uncheck the option "Automatically embed Web Widget in your help center".
2. Under the code box, click the Copy code icon. The code should start with <script id="ze-snippet" ...
3. Now you'll have to initialize the widget by modifying the code of your help center theme. Visit Knowledge admin > Customize design > Customize > Edit code.
4. Find header.hbs in the templates folder and add the code below. Be sure to replace the first script tag with the code you copied in step 2.

{{#if signed_in}}
  <script id="ze-snippet" ...script tag from your installation page></script>
  <script>
      zE("messenger", "useSessionAuth");
  </script>
{{/if}}

Note that you should only initialize the Web Widget using useSessionAuth when the user is logged in to the help center. This is why the script tags are contained inside of #if signed_in tags. If you wish to have the widget load for both authenticated and unauthenticated users, you can do so like this:

<script id="ze-snippet" ...script tag from your installation page></script>

{{#if signed_in}}
  <script>
      zE("messenger", "useSessionAuth");
  </script>
{{/if}}

You can find more information about customizing help center JavaScript behaviors in the Help center JavaScript cookbook.