Users

Connect needs to know certain information about your users to send messages to them effectively. You can send this user data to Zendesk Connect using any of the following methods:

  • Use the Identify User endpoint in the Outbound REST API
  • Use the identify() method in any of the Connect integration options
  • Go to the Users page in your Connect account and upload a CSV file

After the initial sync, you should try to keep your Connect user database in sync with the user database in your system. A best practice is to identify users with Connect whenever one of the following events occurs:

  • A user is added to your database
  • A user's information is updated in your database

Topics covered in this document:

User properties

Users are represented by the following properties. Some Connect libraries may not implement all the properties or use slightly different names. For implementation details, see the docs for your library.

Name Type Mandatory Description
user_id string yes Unique user ID. See User id
first_name string no User's first name. Used in messages
last_name string no User's last name. Used in messages
email string no User's email. See Email address
apns array of strings no Apple Push Notification service (APNs) device tokens. See Device tokens
gcm array of strings no Google Cloud Messaging (GCM) device tokens. Also accepts Firebase Cloud Messaging (FCM) tokens. See Device tokens
phone_number string no User's phone number with country code. Example: '+1 555-123-4567'. See Phone number
timezone string no A valid tz database name. Example: 'Europe/Berlin'
attributes object no Custom user attributes, such as 'username', 'date of birth', or 'address'. See Attributes
previous_id string no A previously assigned id. See Aliasing users
User id

A user ID is the unique identifier for a user. The value can be a string or number. Connect always treats it as a string and converts any number value to a string.

A user ID should be static. If possible, it should be the same value you use to identify the user in your own system.

Sometimes you don't have an id for a user yet but you still want to send messages to the user with Connect. One solution is to generate an anonymous id and use it as the value of the user_id property. Once the user is identified, you can alias the known user to the anonymous user by specifying the anonymous user ID as the known user's previous_id. See Aliasing users.

Email address

Email addresses are required for Connect campaigns that send email messages. All email addresses are validated using Mailgun's email validation API. Connect won't save an address unless it's valid.

Phone number

Phone numbers are required for Connect campaigns that send SMS messages or make voice calls. Phone numbers are validated using a validation library by Google. Connect won't save a number unless it's valid.

A common issue with phone validation is country codes. Example: '+1 555-123-4567'. If the phone number doesn't have a country code, Connect assumes it's a U.S. phone number.

Device tokens

If you have an iOS or Android mobile app and want to use push notifications in your Connect campaigns, include the user's Apple Push Notification service (APNs) token, Google Cloud Messaging (GCM) token, or Firebase Cloud Messaging (FCM) token. Use the gcm property to specify the GCM or FCM token.

Attributes

The attributes property takes an object specifying one or more custom attributes for a user. Example:

...
"attributes": {
  "address": {
    "street": "395 Collins St",
    "city": "Melbourne"
  }
}

The team responsible for creating campaigns in Connect could then select the address.street or address.city attribute in the example to define a filter. They could also insert the values in a message by selecting the attributes from the "@" variable list when composing the campaign message.

To view the user attributes already sent to or tracked in Connect, go to the Users page (Settings > Users) in Connect.

image

JSON example
{
  "user_id": "jdoe@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jdoe@example.com",
  "phone_number": "+61 3 9003 6275",
  "timezone": "Australia/Melbourne",
  "attributes": {
    "address": {
      "street": "395 Collins St",
      "city": "Melbourne"
    }
  },
  "previous_id": "anonymous_user_123"
}

For other data formats, see the docs for your integration option.

Aliasing users

Connect lets you alias users -- that is, associate one user id to another user id. This ability is useful to prevent multiple records for the same user in Connect.

For example, Connect's JavaScript library and some third-party libraries assign a user id to any anonymous user who visits the application. If the anonymous user then signs in, you can alias the anonymous user's id with the known user's id in Connect. Example:

REST API

{
  "user_id": "jdoe@example.com",
  "previous_id": "anonymous_user_123"
}

For implementation details, see the docs for your integration option.

The attributes of both records are combined. If they share a common attribute, the value of the most recent identify request is used. Example:

JavaScript library

// anonymous user identified before signing in
outbound.identify("12345", {
  attributes : {
    favorite_color : "red",
    favorite_dog : "shiba inu"
  }
});

// anonymous user id aliased with known id after signing in, and attributes added
outbound.identify("charlie89", {
  firstName: "Charlie",
  lastName: "Young",
  email: "charlie@example.com",
  previous_id : "12345",
  attributes : {
    favorite_color : "blue"
  }
});

In the example, the following combined attributes would be available for campaigns in Connect:

  • firstName: "Charlie",
  • lastName: "Young",
  • email: "charlie@example.com",
  • favorite_color: "blue",
  • favorite_dog: "shiba inu"

Note that favorite_color is "blue" because the request that set the attribute value to blue is more recent.