Update identify-web-user.mdx

fern/docs/pages/sdks/web/user-identity.mdx

@@ -1,15 +1,13 @@
 Once you have [installed PLuG](./installation), 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 so they can view their past conversations. Identifying your users also enables more personalized engagement.
+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.
 
-In this flow, you have to generate a session token for every user who visits your website. The session token identifies the customer when they interact with the widget. The session token is generated using the application access token and customer information. It should be generated on your website's back end since the app token needs to be kept hidden.
-
-To identify logged-in users, follow these steps:
+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.
+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.
 
 <Callout intent="note">
 Ensure you copy your access token, as you will not be able to view it again.
@@ -18,7 +16,7 @@ Ensure you copy your access token, as you will not be able to view it again.
 ## Generate a session token
 
 <Callout intent="note">
-For security reasons, this call should be made from the server side so that your AAT isn't exposed.
+For security reasons, this API call must be made from the server side to prevent exposing your application access token (AAT).
 </Callout>
 
 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](https://devrev.ai/docs/product/grow).
@@ -35,7 +33,7 @@ curl --location 'https://api.devrev.ai/auth-tokens.create' \
         "workspace_ref": "devrev-dev",
         "user_traits": {
             "email": "[email protected]",
-            "display_name": "Devrev Test USer",
+            "display_name": "Devrev Test User",
             "phone_numbers": ["+911122334455"],
             "custom_fields": {
                "tnt__<field1_name>": "value 1"
@@ -56,10 +54,39 @@ curl --location 'https://api.devrev.ai/auth-tokens.create' \
         }
     }
 }'
- ```
+```
+
+**Attributes for [users](https://developer.devrev.ai/public/api-reference/dev-users/product-builders-and-service-providers)**
+
+| Attributes    | Description                                                                 | Type   | Required | Unique |
+|---------------|-----------------------------------------------------------------------------|--------|----------|--------|
+| `user_ref`      | A unique user reference that the DevRev app uses for identifying your users. This parameter is required. | string | ✅       | ✅    |
+| `email`         | The email address of the customer. It's used for sending email notifications of any support messages. | string | ❌       | ✅**     |
+| `display_name`  | The name of the user that's shown on the widget.                          | string | ❌*       | ❌     |
+| `phone_numbers` | The 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](https://developer.devrev.ai/public/api-reference/rev-orgs/workspaces)**                                              
+
+| Attributes      | Description                                                                                                        | Type   | Required | Unique |
+|-----------------|--------------------------------------------------------------------------------------------------------------------|--------|----------|--------|
+| `workspace_ref` | A 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_name`  | The name of the workspace that's shown on the widget.                                                              | string | ❌        | ✅     |
+
+**Attributes for [accounts](https://developer.devrev.ai/public/api-reference/accounts/accounts)**                                                        
+
+| Attributes      | Description                                                                                                             | Type   | Required | Unique |
+|-----------------|-------------------------------------------------------------------------------------------------------------------------|--------|----------|--------|
+| `account_ref`   | A unique reference for the account.                                                                                     | string | ❌        | ✅     |
+| `display_name`  | The name of the account that's shown on the widget.                                                                     | string | ❌        | ✅     |
+| `domains`       | The attribute must be unique. Use a format like `devrev.ai`. Inputs like `https://devrev.ai` or `www.devrev.ai` are invalid. | array  | ❌        | ✅     |
+| `phone_numbers` | The phone number associated with the account must be in E.164 format.                                                   | array  | ❌        | ❌     |
 
 <Callout intent="note">
-Ensure that you follow the specified format when providing your phone number.
+Ensure that you follow the specified format when populating phone numbers and domains in the request body.
 </Callout>
 
 ## Pass custom attributes
@@ -77,32 +104,55 @@ You can pass the custom attributes that are created as shown below:
 
 You can pass custom traits, as shown above, not only for `users` but also for `workspaces` and `accounts`.
 
-If you prefer a two-level structure, where users are directly associated with an account instead of a workspace, you can provide the `user_ref` and details along with the `account_ref` and details.
+### API status codes and troubleshooting
+
+| Status code| Description | Troubleshooting |
+|----------|----------|
+| 200 OK                    | The request was successful and the session token would be returned in the response. | No troubleshooting required. |
+| 400 Bad Request           | The request was invalid. | Check the request body for errors. For fields like domain and phone number, check on their format. |
+| 401 Unauthorized          | The request was unauthorized. | Check if the AAT is valid and not expired. |
+| 403 Forbidden             | The request was forbidden. | Check the authorization header for errors and make sure the token is a valid AAT. |
+| 404 Not Found             | The requested resource could not be found. | Verify the endpoint URL is correct. |
+| 429 Too Many Requests     | Rate limit exceeded. | Implement request throttling or wait before retrying. |
+| 500 Internal Server Error | Server 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:
 
-**Attributes for users**
+| Hierarchy Type | Documents Created | What to Include | Use Case |
+|----------------|-------------------|-----------------|----------|
+| **Single-level** | Contacts only | Only user information | Recommended for most B2C cases |
+| **Two-level** | Accounts and Contacts linked to the account | User and account information | Recommended for most B2B cases |
+| **Three-level** | Account with linked workspaces and contacts | User, workspace and account information | Used for B2B cases but only recommended if your business model requires workspace organization |
 
-|Attributes   |Description   |Type   |
-|---|---|---|
-|`user_ref`   |A unique user reference that the DevRev app uses for identifying your users. This parameter is required.   |string   |
-|`email`   |The email address of the customer. It's used for sending email notifications of any support messages.   |string   |
-|`display_name`   |The name of the user that's shown on the widget.   |string   |
-|`phone_numbers`   |The mobile number of the customer.   |array   |
+**What happens when you send different combinations:**
 
-**Attributes for workspaces**
+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.
 
-|Attributes   |Description   |Type   |
-|---|---|---|
-|`workspace_ref`   |A 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_name`   |The name of the workspace that's shown on the widget.   |string   |
+This approach ensures efficient management and integration of objects within the DevOrg.
 
-**Attributes for accounts**
+| Workspace Ref | Account Ref | Results                                                                                              |
+|---------------|-------------|------------------------------------------------------------------------------------------------------|
+| ❌            | ✅          | (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. |
 
-|Attributes   |Description   |Type   |
-|---|---|---|
-|`account_ref`   |A unique reference for the account.    |string   |
-|`display_name`    | The name of the account that's shown on the widget.    |string   |
-|`domains`   |The domain names of the accounts that the users belongs to.   |array   |
-| `phone_numbers`    |The phone number associated with the account.   |array   |
+
+
+### 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
 
@@ -115,7 +165,7 @@ const sessionToken = '<SESSION_TOKEN>'
 <script>
     (() => {
       window.plugSDK.init({
-        app_id: '<your_unique_app_id>',
+          app_id: '<your_unique_app_id>',
           session_token: sessionToken
         })})();
 </script>
@@ -137,17 +187,17 @@ This method is currently in beta and comes with the following limitations:
 
 ```jsx
 window.plugSDK.init({
-  app_id: '<your_unique_app_id>',
+  app_id: appId,
   identity: {
-    user_ref: string;
-    user_traits?: { // optional
-      custom_fields?: object; // optional
-      display_name?: string; // optional
-      email?: string; // optional
-      phone_numbers?: string[]; // optional
+    user_ref: userRef,
+    user_traits: { // Optional user details
+      custom_fields?: object,
+      display_name: 'John Doe',
+      email: '[email protected]',
+      phone_numbers: ['+1234567890']
     }
   }
-})
+});
 ```
 
 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. 
@@ -162,4 +212,3 @@ window.plugSDK.updateIdentity({
   }
 })
 ```
-