Clients and devices

As explained in key concepts, an individual user object may be linked to several clients and devices, representing their presence on different messaging channels. These data models serve an important function in the dispatching and delivery of messages and push notifications. Additionally, clients and devices store information collected about the user which can be important when providing them with support. For example, devices of type web will include the user's current URL, which can be instrumental in diagnosing a problem they may be experiencing.

Client and device metadata

Devices and clients have a number of fields to store information collected about the user. For users on third-party messaging channels, the client object holds this info, whereas for users on the Zendesk embeddables, this responsibility is delegated to the device model instead since users can have multiple separate devices. A high level summary of each type of object is provided below. For the full expected schema for each of these data models, see the List Clients and List Devices API response definitions.

Note: Client and device metadata is not updated in realtime. Rather, it is periodically updated as the user continues interacting with messaging. Metadata is typically updated when the user sends messages or interacts with other messaging elements such as postback buttons, forms, and quick replies within a conversation. For example, this means that a user's device.info.currentUrl on the Web Widget will only represent the page they were on when they last sent a message from that device, not necessarily the page they are on at the current moment.

Third-party channel client objects

For clients that model the user's presence on a third-party channel, there are a number of useful fields stored for reference. Some of the most important ones are explained below:

• The externalId field contains the id of the user on the third-party channel. For example, the user’s phone number for Twilio, or their page-scoped user ID for Facebook Messenger. This field is used to bridge the user's identity in Zendesk with their identity on the third-party channel.
• The integrationId field represents the integration that the client is associated with. For example, if your business has multiple WhatsApp numbers representing different geographical regions where you offer service, each phone number would have an associated integration, and the integrationId of the client would tell you which number the user reached out to.
• The info object includes some curated profile information that Zendesk considers to be useful. Each messaging channel exposes a different set of information in their API, so the supported data in this object varies per platform. However, since this is a curated object, the key names are selected by Zendesk and are often reused across channels.
  • Typically the info object would include information such as the user's preferred language or avatar url on the channel.
• The raw object is an uncurated list of data, and includes all data that Zendesk was able to gather from the channel. This means that the raw object will often contain more information than info, however the data format is not standardized across channels. The keys in this object will match the nomenclature used by the channel's API, and keys will therefore not typically be shared by clients of different types.

Note: The combination of integrationId and externalId will always uniquely identify a single user within your Zendesk account. If the same integrationId + externalId pair is linked to a second user, this generates a conflict which is either resolved by a client theft or a user merge. You can learn more about these interactions in Channel transfer.

While it's possible for the same integrationId + externalId to exist simultaneously on two clients within a given account, this is only possible if one of the clients' status is active and the other one is pending.

Example messenger client object:

{
  "id": "67dc3cc53f09a870b773216b",
  "type": "messenger",
  "status": "active",
  "externalId": "1128837457239041",
  "integrationId": "5a99b74858247c608f64a348",
  "lastSeen": "2025-03-20T16:05:32.729Z",
  "linkedAt": "2025-03-20T16:05:25.988Z",
  "displayName": "Sue Purb",
  "avatarUrl": "https://scontent.xx.fbcdn.net/example.png",
  "info": {
    "avatarUrl": "https://scontent.xx.fbcdn.net/example.png"
  },
  "raw": {
    "first_name": "Sue",
    "last_name": "Purb",
    "profile_pic": "https://scontent.xx.fbcdn.net/example.png",
    "id": "1128837457239041"
  }
}

SDK client objects

A user can only have a single client of type sdk, which is shared by all embeddable integrations (Web, iOS, Android, and Unity). Its presence in a user's list of clients signals that the user has been present on any one of the supported platforms. Unlike on third-party channels where device registration is handled by the third-party platform, users on one of Zendesk's messaging embeddables can be active on multiple platforms simultaneously. To know specifically which embeddable types an individual user has used, you should inspect their list of devices.

The sdk client object does not contain most of the fields that a third-party client would have. Notably, the externalId, integrationId, and info fields are missing from clients of this type, since this data is stored on the devices instead.

Example sdk client object:

{
  "id": "67a0ee38f0305f4a391e9def",
  "type": "sdk",
  "status": "active",
  "lastSeen": "2025-02-03T16:26:32.575Z",
  "linkedAt": "2025-02-03T16:26:32.575Z"
}

Device objects

For users using one of Zendesk's messaging embeddables, they must interact from some physical device like a web browser or mobile phone. Using messaging authentication, users can access their conversations from multiple devices and platforms, and can therefore have multiple linked devices at a time. Some of the most important device fields are explained below:

• The device's guid is generated on the client side when the device is initialized for the first time. It's used as an identifier to correlate messages and other events to the device that generated them.
• The integrationId field identifies which SDK integration instance the device is associated with. For example, you might have multiple ios integrations associated with different brands in your account. This is important for determing which push notification credentials to use when notifying the user, or for deciding which brandId to assign to conversations created by the device.
• The device model captures various metadata about the device in the info field such as the OS version, the version of the SDK used, the language of the device, and more. The fields in this object are platform-specific, meaning a device of type android will contain different information than a device of type web.

Note: An individual user may have up to 25 registered devices. If a new device is initialized after the user has already reached the limit, the least recently used device (ordered by lastSeen timestamp) will be evicted from the user.

Example web device object:

{
  "id": "5d9b870dda96abc332625ccc",
  "type": "web",
  "status": "active",
  "guid": "f1c7abea2d49429db10094be820d5f80",
  "clientId": "5d9b870dda96abc332625cc8",
  "integrationId": "5d83a25d9916b64a83ed25e8",
  "lastSeen": "2025-01-28T17:59:58.331Z",
  "info": {
    "currentTitle": "My Web Page",
    "currentUrl": "https://example.com",
    "browserLanguage": "en-US",
    "referrer": "https://example.com",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 Safari/537.36",
    "URL": "example.com",
    "sdkVersion": "0.1",
    "vendor": "zendesk"
  }
}

Client status

A client's status property represents its current eligibility to send and receive messages. The supported status values are described below:

• A client with status of active is fully linked and can be used to send and receive messages.
• A client with status of pending means that a channel transfer flow was started, but the link has not been confirmed yet. This client is not eligible to receive business messages until the transfer is either accepted or refused.
• A client with status of blocked means that the user has opted out of receiving messages from the business on that particular channel, for example by blocking the business from within the third-party messaging app. Clients with status blocked are not eligible to receive business messages until the user decides to unblock the business.
• The inactive status is deprecated and no longer used.

When a client's status field changes, a client:update webhook event will be fired to communicate the change. The reason field in the webhook payload will indicate which type of transition occurred. For example, a reason of blocked means that the client transitioned from active to blocked status. This webhook event can be used to keep track of when a user's eligibility to receive messages on various channels changes, in case you want to reflect that state somewhere in your software.

Client intents

For users on the Apple Messages for Business channel, Apple makes it possible to craft a URL that will bring users into a conversation with the business. When crafting one of these URLs, the biz-intent-id and biz-group-id parameters can be included in the query string, which can be used to identify which specific link a user has clicked. For example:

https://bcrw.apple.com/urn:biz:{businessId}?biz-intent-id=TestingBizIntent&biz-group-id=TestingBizGroup

After a user follows a link with a group and/or intent and sends a message to the business, the values will be captured in the client's raw object. Any messages that are subsequently received from that client will then have the last known source and intent included under the message's source property. For more information on how to use groups and intents, see About Intent, Group, and Body Values.

Example client object with an intent and group:

{
  "id": "67dc3cc53f09a870b773216b",
  "type": "apple",
  "status": "active",
  "externalId": "1128837457239041",
  "integrationId": "5a99b74858247c608f64a348",
  "lastSeen": "2025-03-20T16:05:32.729Z",
  "linkedAt": "2025-03-20T16:05:25.988Z",
  "raw": {
    "group": "TestingBizGroup",
    "intent": "TestingBizIntent"
  }
}

Example message including last known intent and group ids:

{
  "id": "5e55622dac66fb73a3c01877",
  "received": "2020-02-25T18:06:37.547Z",
  "content": {
    "type": "text",
    "text": "Hello world"
  },
  "author": {
    "type": "user",
    "userId": "cbec0073faeda4dfcd21d0f1",
    "displayName": "Sue Purb",
    "user": {
      "id": "cbec0073faeda4dfcd21d0f1"
    }
  },
  "source": {
    "type": "apple",
    "group": "TestingBizGroup",
    "intent": "TestingBizIntent"
  }
}

Note: Group and intent are both optional. If both are left unspecified, the client.raw object will be absent and the message.source.group and message.source.intent fields will be absent.

Changing group or intent

A user can click a different Messages for Business link with different biz-* query parameters, thus changing the conversation's group and intent. In this case, client.raw.group and client.raw.intent will be individually updated with any new values. Group and intent values that were received with previous messages will still be preserved in the message history under each message's source.group and source.intent parameters.

Unsubscribe behaviour

If a user unsubscribes from receiving messages from the business, the group and intent fields stored on the client will be cleared. If they later change their mind and send a new message to the business (without having clicked a Messages for Business link with query parameters), these parameters will remain unset.

Devices and push notification delivery

One of the primary purposes of a device object is for push notification registration. For eligible integration types (iOS and Android), the device's pushNotificationToken property will contain a unique identifier used to send push notifications to the user over APNs or FCM.

Note: To learn how to configure your integration to dispatch push notifications, see "Setting up push notifications" on iOS and Android.

The status property of a device controls whether the device is currently eligible to receive push notifications or not. For devices where the status is inactive, push notification delivery will be suppressed. The status is automatically managed by the Zendesk messaging platform. A device will be set to inactive if the user logs out of the device, or a different user is initialized using the same device guid. Logging in again will reset the device back to active.

When a user's sdk client is selected for delivery of a business message, push notifications will be dispatched to all of the user's active devices in parallel.

User profile data inheritance

In some cases, information captured from one of a user's clients or devices can be "promoted" into a user-level field. For example, the user's Facebook profile can be used to populate the profile.givenName, profile.surname, and profile.avatarUrl fields of the user. Similarly, the user's browser or device language may be used to populate their profile.locale.

User profile information can only be inherited from their clients or devices if the user object does not have any value set yet for the field in question. For example, an empty profile.givenName field may gain a value if the user's name can be determined from their Facebook profile. However, if the user already has a profile.givenName set, it will never be automatically overwritten with their name on Facebook. This one-time promotion of user data is a best effort to automatically populate important details about the user, while ensuring that any corrections made by the business later on are not mistakenly undone.