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 can be related for users that have escalated a ticket to the Agent Workspace. However, the two user models have separate schemas and different means of accessing and managing them.

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 simply means that the user has not been assigned an external ID. 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 be assigned profile information such as a name and unverified email address. 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

An "authenticated" user is a user that your business has explicitly identified with an externalId through messaging authentication or similar means. The externalId 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.

By assigning an external ID to your messaging users, this informs Zendesk that the user has proven their identity by some external means. The most likely scenario for authenticating users is when using one of Zendesk's native messaging SDKs or Web Widget. 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 transfer to another 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 how to authenticate your users on the Zendesk SDKs and Web Widget.