Identify your users with PLuG

Once you have installed PLuG, all your users who interact with the widget are created as anonymous users in the DevRev app with a random name since there is no information about the user.

For users who are logged into your website, you can identify them in PLuG to enable them to view their conversation history and receive more personalized engagement.

To implement user identification, you need to generate a session token for each user who visits your website. This token is created using your application access token combined with customer information, and must be generated on your backend to keep the application token secure.

Generate an application access token

  1. In DevRev, go to Settings > Support > PLuG Tokens through the settings icon on the top-left corner.
  2. Under the Application access tokens panel, click New token and copy the token that’s displayed.

Ensure you copy your access token, as you cannot view it again.

Generate a session token

For security reasons, this API call must be made from the server side to prevent exposing your application access token (AAT).

Using the rev_info method, you can generate and recognize a user within the DevRev system by providing relevant user details. This method enables you to convey information systematically, ensuring alignment between your DevRev CRM and the structured data model. For information regarding terminologies, click here.

$curl --location 'https://api.devrev.ai/auth-tokens.create' \
>--header 'accept: application/json, text/plain, */*' \
>--header 'authorization: <AAT>' \
>--header 'content-type: application/json' \
>--data-raw '{
> "rev_info": {
> "user_ref": "example@devrev.ai",
> "account_ref": "devrev.ai",
> "workspace_ref": "devrev-dev",
> "user_traits": {
> "email": "test-user@devrev.ai",
> "display_name": "Devrev Test User",
> "phone_numbers": ["+911122334455"],
> "custom_fields": {
> "tnt__<field1_name>": "value 1"
> }
> },
> "workspace_traits": {
> "display_name": "Devrev Dev",
> "custom_fields": {}
> },
> "account_traits": {
> "display_name": "Devrev",
> "domains": [
> "devrev.ai"
> ],
> "custom_fields": {
> "tnt__<field2_name>": "value x"
> }
> }
> }
>}'

Attributes for users

AttributesDescriptionTypeRequiredUnique
user_refA unique user reference that the DevRev app uses for identifying your users. This parameter is required.string
emailThe email address of the customer. It’s used for sending email notifications of any support messages.string✅**
display_nameThe name of the user that’s shown on the widget.string❌*
phone_numbersThe customer’s mobile number, which must adhere to the E.164 format.array
  • If nothing is specified, a system-generated name is assigned to the user.

** Email uniqueness is subjected to organization preferences. If organization want, it can be marked non unique. But it is not recommended.

Attributes for workspaces

AttributesDescriptionTypeRequiredUnique
workspace_refA unique reference for the user’s workspace. If not provided, and an account reference is passed, the user is directly attached to the account.string
display_nameThe name of the workspace that’s shown on the widget.string

Attributes for accounts

AttributesDescriptionTypeRequiredUnique
account_refA unique reference for the account.string
display_nameThe name of the account that’s shown on the widget.string
domainsThe attribute must be unique. Use a format like devrev.ai. Inputs like https://devrev.ai or www.devrev.ai are invalid.array
phone_numbersThe phone number associated with the account must be in E.164 format.array

Ensure that you follow the specified format when populating phone numbers and domains in the request body.

Pass custom attributes

To create custom attributes, see Object customization.

You can pass the custom attributes that are created as shown below:

1"custom_fields": {
2 "tnt__custom_attribute_name1": <value>,
3 "tnt__custom_attribute_name2": <value>,
4}

You can pass custom traits, as shown above, not only for users but also for workspaces and accounts.

API status codes and troubleshooting

Status codeDescriptionTroubleshooting
200 OKThe request was successful and the session token would be returned in the response.No troubleshooting required.
400 Bad RequestThe request was invalid.Check the request body for errors. For fields like domain and phone number, check on their format.
401 UnauthorizedThe request was unauthorized.Check if the AAT is valid and not expired.
403 ForbiddenThe request was forbidden.Check the authorization header for errors and make sure the token is a valid AAT.
404 Not FoundThe requested resource could not be found.Verify the endpoint URL is correct.
429 Too Many RequestsRate limit exceeded.Implement request throttling or wait before retrying.
500 Internal Server ErrorServer encounters an unexpected error.Wait and try again later. If the issue persists, contact support with the request details and timestamp.

How resolution works

When you send object information to DevRev, the system automatically creates or finds existing contacts, accounts, and workspaces.

DevRev offers three ways to structure your customer’s data:

Hierarchy TypeDocuments CreatedWhat to IncludeUse Case
Single-levelContacts onlyOnly user informationRecommended for most B2C cases
Two-levelAccounts and Contacts linked to the accountUser and account informationRecommended for most B2B cases
Three-levelAccount with linked workspaces and contactsUser, workspace and account informationUsed for B2B cases but only recommended if your business model requires workspace organization

What happens when you send different combinations:

User reference:

  • A user reference is mandatory, ensuring its constant presence.
  • If a user with the provided reference doesn’t exist, the system automatically creates the user.

This approach ensures efficient management and integration of objects within the DevOrg.

Workspace RefAccount RefResults
(Most common Usage) \nIf the account doesn’t exist: An account is created, and the user is linked with the account.
No action on account or workspace. The user is returned.
If neither exists: System creates the account first, then creates the workspace. User is linked to both.
If account exists but workspace doesn’t: System creates the workspace under the existing account. User is linked to both.
If workspace exists under different account: System returns an error, as workspaces cannot be a part of 2 accounts.
If workspace doesn’t exist: System creates a new account and workspace (if needed). User is linked to both.

Best practices

  • Populate user traits like email and display name to make users identifiable and to prevent duplicate users across integrations.
  • Maintain consistent unique identifiers across your system.
  • Follow the specified formats for phone numbers and domains.
  • Keep your application access token secure.

Pass the session token

While initializing the PLuG widget you pass the session token for DevRev to identify this user and thereby make the widget more customized for the user and their context.

1// You can generate this session token using the above API in your backend
2const sessionToken = '<SESSION_TOKEN>'
3<script type="text/javascript" src="https://plug-platform.devrev.ai/static/plug.js"></script>
4<script>
5 (() => {
6 window.plugSDK.init({
7 app_id: '<your_unique_app_id>',
8 session_token: sessionToken
9 })})();
10</script>

Identify users without session token

You can also pass the identifiers in the plugSDK.init option without generating the session token.

This frontend user identification, by its nature, is not secure as the data is transmitted through the client side. It is recommended to use the session token method to securely identify users.

This method is currently in beta and comes with the following limitations:

  • Unverified users cannot be converted or merged into verified users.
  • An external reference used by an unverified user cannot be reused for any other user.
1window.plugSDK.init({
2 app_id: appId,
3 identity: {
4 user_ref: userRef,
5 user_traits: { // Optional user details
6 custom_fields?: object,
7 display_name: 'John Doe',
8 email: 'john@example.com',
9 phone_numbers: ['+1234567890']
10 }
11 }
12});

You can add or update the data in user_traits by using the updateIdentity method on the PLuG SDK. Attached is a sample code snippet for the same.

1window.plugSDK.updateIdentity({
2 user_traits: {
3 custom_fields?: object; // optional
4 display_name?: string; // optional
5 email?: string; // optional
6 phone_numbers?: string[]; // optional
7 }
8})