Update identify-web-user.mdx

fern/docs/pages/plug-sdk/web/user-identity.mdx

@@ -1,10 +1,8 @@
 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
 
@@ -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 your 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"
@@ -58,8 +56,37 @@ 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`       | Use a unique format like 'devrev.ai'. Formats such as 'https://devrev.ai' or 'www.devrev.ai' are not valid.       | 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,61 @@ 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
+
+DevRev offers three ways to structure your customer's data:
+1. **Single-level (Recommended for most B2C cases)**
+   - User
+   - What to include: Only user information
+
+2. **Two-level (Recommended for most B2B cases)**
+   - User → Account
+   - What to include: User and account information
+
+3. **Three-level**
+   - User → Workspace → Account
+   - What to include: User, workspace and account information
+   - Only use workspace information if your business model requires workspace organization
+
+In a DevOrg, unique identifiers are utilized to handle objects. If an object doesn't exist, it is created and then an attempt is made to link it. For example, here's how it operates:
+
+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 for users**
+This approach ensures efficient management and integration of objects within the DevOrg.
 
-|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   |
+| 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 for workspaces**                                              
 
-|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   |
 
-**Attributes for accounts**                                                        
+### Best practices
 
-|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   |
+- Populate user traits like email and display name to:
+    - Make users identifiable
+    - 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