Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results

Tracking users

WebEngage offers APIs for creating and updating users. Both of these operations can be performed using the /users endpoint as described below.

Identifying users

There are two types of user identifiers that WebEngage uses:

  1. Anonymous IDs (LUID) for users who are unidentified
  2. Non-anonymous IDs (CUID) for users who are identified

Assigning a CUID helps collect the user's activity and information across systems in a single unified profile.

A user profile's ID once assigned, cannot be changed. Although ID can be any String that uniquely identifies users in your system, we recommend using system generated user IDs from your database instead of information that can change over time such as email addresses, usernames or phone numbers.

The usual places to assign IDs are

  • On user signups
  • On user logins
  • On screen or page views where user identity becomes known
  • When the user context changes

You can assign LUID by passing anonymousID and CUID by passing userId parameter in the request body.

User attributes

There is often additional identifying information, such as name and email address, associated with user profiles. You can set these attributes using respective parameters in the request body as described below. These attributes can be used to segment users and target campaigns to a specific group. Additionally, they can be referred to personalize campaign messages to each user.

Attributes can be set on “anonymous” profiles as well.

Each user session has its own user attributes, but they get copied from one session to the next. This is in contrast to event parameters, which may take on different values per event. For this reason, you generally use user attributes for things that do not change much within the session, or with which you want the entire session associated.

Setting system attributes

You can set system attributes by passing them as parameters in the request body as described below.

Setting custom attributes

You can set custom attributes by passing them as key-value pairs in the attributes parameter in the request body.

/users

METHOD
POST

DESCRIPTION
Add or update users.

URL STRUCTURE

https://api.webengage.com/v1/accounts/<YOUR_WEBENGAGE_LICENSE_CODE>/users

HEADERS

Name
Description

x-request-id:{HEX_STRING}

Replace {HEX_STRING} with a unique random hex string.

If API re-attempts are being made, this tag stops propagation of duplicate events within a 4 hour window. Events with same ID re-attempted within 4 hours won't get duplicated if the previous HTTP request was able to ingest the event.

AUTHENTICATION
User Authentication

EXAMPLE

Run in Postman

curl -X POST https://api.webengage.com/v1/accounts/<YOUR_WEBENGAGE_LICENSE_CODE>/users \
    --header 'Authorization: Bearer <YOUR_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
    "userId": "johndoe",
    "firstName": "John",
    "lastName": "Doe",
    "birthDate": "1986-08-19T15:45:00-0800",
    "gender":"male",
    "email":"john@doe.com",
    "phone":"+551155256325",
    "company":"Alphabet Inc.",
    "attributes": {
    	"Age":"31",
      "Twitter username": "@origjohndoe86",
      "Dollars spent": 461.93,
      "Points earned": 78732
      }
    }'

Make sure you replace YOUR_WEBENGAGE_LICENSE_CODE with your WebEngage license code and YOUR_API_KEY with your WebEngage API key.

PARAMETERS

{
  "userId": "johndoe",
  "firstName": "John",
  "lastName": "Doe",
  "birthDate": "1986-08-19T15:45:00-0800",
  "gender":"male",
  "email":"john@doe.com",
  "phone":"+551155256325",
  "company":"Alphabet Inc.",
  "attributes": {
      "Age":"31",
     "Twitter username":"@origjohndoe86",
     "Dollars spent": 461.93,
     "Points earned": 78732
    }
}

Constraints

  • Attribute names must be less than 50 characters long. String type attribute values must be less than 1000 characters long. Any characters beyond that will be truncated.
  • In addition to the system attributes, you can create at most 25 user attributes of each data type.
    You cannot start your attribute names with we_.
  • If attribute value is JSON Object, it cannot be used to create user segments. It can only be used to personalize campaigns.
Parameter
Type
Description
Is mandatory

userId

String

Identifier for known user.
Either one of userId or anonymousId is mandatory.
Constraint:

  • userId can be of maximum 100 characters.

No

anonymousId

String

Identifier for anonymous user. Either one of userId or anonymousId is mandatory. In case both IDs are sent, anonymousId will be ignored.

Constraint:

  • anonymousId can be of maximum 100 characters.

No

firstName

String

First name of the user.

No

lastName

String

Last name of the user.

No

birthDate

String

Birth date of the user in ISO format: yyyy-MM-ddTHH:mm:ss±hhmm.

No

gender

String

Gender of the user.
Can be one of male, female or other.

No

email

String

Email address of the user.

No

emailOptIn

Boolean

Email subscription preference of the user.
Users who are opted out of this will not receive any communication over email. Users are by default opted in to email.

No

phone

String

Phone number of the user.
phone must be in E.164 format, eg. +551155256325, +917850009678.

No

smsOptIn

Boolean

SMS subscription preference the user. Users who are opted out of this will not receive any communication over SMS. Users are by default opted in to SMS.

No

company

String

Name of the company the user works for.

No

hashedEmail

String

Encrypted email address for use with a private Email Service Provider.

No

hashedPhone

String

Encrypted phone number for use with a private SMS Service Provider.

No

attributes

Object

Custom attributes of the user as key-value pairs. For example:
{ "isPaidUser": true, "userPlan": "Premium" }
These data types are allowed for custom attributes: String, Number, Boolean, Date, JSON Array JSON Object. JSON Object can contain one of these data types.

No

1. User attribute names are case sensitive.
2. attributeName must not start with we_. Attribute names starting with we_ are reserved for WebEngage's internal use, and will be ignored if used for custom attributes.
3. For custom user attributes, the first datapoint synced to WebEngage defines the data type for that attribute in WebEngage. Therefore, data types must be consistent with the data that you want to store for the attribute. If you change the data type later, attribute data will stop flowing to WebEngage.

RETURNS

{
	"response": {
		"status": "queued"
	}
}

ERRORS
Example: Both userId and anonymousID missing

{
  "response": {
  "message":"Error: userId and anonymousId cannot be empty.",
  "status":"error"
	}
}

What's Next

Tracking events

Tracking users