Introduction to users

A user in Zendesk messaging refers to an end user on your platform, or a customer (or prospective customer) of your business. The following are all examples of what we refer to as a user in messaging:

• a visitor to your web site
• the holder of an SMS number
• a user of your mobile app
• a user of a social media or messaging app (like Facebook Messenger, WhatsApp, etc)

Note: In Zendesk messaging, the term "user" does not include agents or admins of your business.

Messaging users vs Support users

The messaging platform defines its own user model separate from a user object in Support. The two types of users form a link when a messaging user escalates a ticket to the Agent Workspace, or when a messaging user has authenticated by way of the Web Widget embedded in a Zendesk help center. However, the two user models have separate schemas and different means of access and management.

The Support user is the canonical user record that appears in the Agent Workspace and in Admin Center. It is the main user model that is shared across various Zendesk products such as Support and Guide. The ticketing platform is also based on this type of user, and the requester of a ticket will be of this type.

Messaging users, on the other hand, are exclusively used by the social and native messaging products. These user records are typically only used under the hood and are accessed and managed using the messaging platform APIs. A messaging user participates in one or more messaging conversations with your business. This type of user cannot be viewed directly by agents or admins in the Agent Workspace, and will not appear in search results.

Retrieving messaging users

When receiving messages and other messaging events, the user object will typically be included in events generated by the user's actions. To fetch the user directly, they can be referenced by either their Zendesk-assigned user id, or their business-assigned externalId. For example, given the following messaging user:

{
  "id": "cbec0073faeda4dfcd21d0f1",
  "externalId": "my-test-user",
  "signedUpAt": "2025-04-08T18:16:41.962Z",
  "hasPaymentInfo": false,
  "identities": [],
  "profile": {},
  "metadata": {},
  "authenticated": true
}

The two calls to Get User below would return the same user object:

curl -X GET https://{subdomain}.zendesk.com/sc/v2/apps/{appId}/users/cbec0073faeda4dfcd21d0f1

curl -X GET https://{subdomain}.zendesk.com/sc/v2/apps/{appId}/users/my-test-user

Note: Not all users will have an assigned externalId, but all users will have an automatically generated id. See unauthenticated users and authenticated users below for more details.

User relationships

When a messaging conversation is escalated to an agent, a ticket and Support user will automatically be created at this time (if they don't exist already) which refer back to the messaging objects that created them. For more information about how messaging tickets are mapped to new or existing Support users, see Setting up user authentication for messaging.

To determine if a Support user has an associated messaging user, use the List Identities API and look for an identity of type messaging. The value field of the messaging identity will contain the user's messaging id. The example below shows the identities of a Support user which refers to a messaging user with id cbec0073faeda4dfcd21d0f1:

{
  "identities": [
    {
      "url": "https://{subdomain}.zendesk.com/api/v2/users/000000000000000/identities/000000000000001.json",
      "id": 000000000000001,
      "user_id": 000000000000000,
      "type": "messaging",
      "value": "cbec0073faeda4dfcd21d0f1",
      "verified": true,
      "primary": true,
      "created_at": "2023-11-17T13:52:31Z",
      "updated_at": "2024-02-19T18:18:47Z"
    },
    {
      "url": "https://{subdomain}.zendesk.com/api/v2/users/000000000000000/identities/000000000000002.json",
      "id": 000000000000002,
      "user_id": 000000000000000,
      "type": "email",
      "value": "[email protected]",
      "verified": false,
      "primary": true,
      "created_at": "2024-02-19T18:18:47Z",
      "updated_at": "2024-02-19T18:18:47Z",
      "undeliverable_count": 0,
      "deliverable_state": "deliverable"
    }
  ],
  "next_page": null,
  "previous_page": null,
  "count": 2
}

Unauthenticated users

When a user is referred to as "unauthenticated" in messaging, it means that the user has not been assigned an external ID, and they have also not been authenticated by way of a Zendesk help center. When a user is seen for the first time on a messaging channel, they are unauthenticated by default. This includes users from social messaging channels, one of the Zendesk Embeddables, or SMS. Unauthenticated users have most of the same capabilities as authenticated users in terms of their ability to send and receive messages. However, these users have not proven their identity to the business and should be treated more carefully when handling sensitive tasks and information.

Unauthenticated users may still have profile information such as a name or unverified email address. For example, this information may have been captured by an AI agent using form message. For users on social messaging channels such as Instagram or Viber, this information may be automatically populated based on their social messaging profile. Keep in mind, however, that this only proves that the user has supplied these values to the social channel provider when setting up their account. It in no way guarantees that they are the same person that controls the account with that email address or name in your business' system of record.

Authenticated users

The authenticated property of a user can be true or false, indicating their state of authentication. Authentication can happen in two ways:

• The user has been explicitly identified with an external ID through messaging authentication or similar means, or
• They have been authenticated by way of the Web Widget embedded in a Zendesk help center

The authentication property of a user is read-only and cannot be set directly. It is true if and only if either of the conditions above have been met.

The external ID is a key part of authentication in messaging, and it is used to link a user's identity across the boundary between your own applications and Zendesk. All messaging users who have been assigned an external ID are authenticated, however not all authenticated users have an external ID. If a mesaging user has been authenticated through the help center, they might lack an external ID, but they will include a zendeskId property that links them to the corresponding Support user that performed the help center login.

The external ID of a user would typically refer to their id in your business' canonical system of record. See Selecting the external id to use in JWTs issued to users for examples of good and bad choices for your external ids.

Assigning an external ID to your messaging users informs Zendesk that the user has proven their identity by some external means. The most likely scenario for this when the user is interacting with one of Zendesk's native messaging SDKs or Web Widget, embedded inside of your application. For example, when a user logs into your business' web site, you might want to carry forward their authenticated state into the Zendesk Web Widget, so that agents know who they are. By leveraging your business' existing authentication mechanism in your application or website, the user can seamlessly continue their conversations on a different authenticated device. Users will be able to switch between different domains, browsers, and devices, while still maintaining their conversation history.

For users on third-party messaging channels, there is no out-of-the-box authentication flow for them to prove their identity and gain an external ID. Social messaging users will therefore rarely be considered as authenticated. However, when using outbound messaging it's possible to assign external IDs to customers on social messaging channels as part of sending them an outbound message. See Outbound messaging with the create client API for more information on how this can be done.

Key differences

The key difference between an unauthenticated user and an authenticated user is how the embeddables gain access to the user's profile and conversation history. An authenticated user must be provisioned a signed JWT credential with scope user in order for the SDK to properly initialize on behalf of the user. This credential must be generated by your business and supplied to the SDK each time the SDK is loaded in your mobile app or web site. Unauthenticated users, on the other hand, do not require a JWT credential to access; instead, the SDKs authenticate using a sessionToken mechanism, explained below.

Note: Session tokens and user-scoped JWTs only apply to usage of the Zendesk SDKs and Web Widget, and cannot be used with the public API. Both unauthenticated and authenticated users can be accessed from your backend using app or integration scoped credentials.

See API authentication for more information on how to use server-to-server credentials.

In contrast to signed JWTs which must be generated by your business, session tokens are managed automatically by Zendesk behind the scenes. When an unauthenticated user is created for the first time, a session token will be provisioned for them automatically, which is then stored in the calling device's durable storage. The session token will be reused for all further communications, allowing the user's state to persist across app restarts and page reloads.

In general, it is not necessary to know how session token-based authentication works, but the concept of a session is important to understand how a user can gain access to their conversation history on a different browser or mobile device. For more information on how unauthenticated users can be moved between different channels and devices, see the channel transfer guide.

Next steps

• See user lifecycle for more information on how and when users are created or deleted by the system.
• Merging users explains various cases where two users can be merged together, and how the merge process works.
• Learn more about Authenticating users in your application using the Zendesk SDKs and Web Widget.
• Learn more about Authenticating users in the help center with the Web Widget.