# User Attributes: Store and Look Up Customer Data in Robylon

Understand the default user attributes Robylon captures, create your own, and fill them automatically from the Chat SDK or a lookup API on your own system for chat, WhatsApp, email and voice.

> Source: https://www.robylon.ai/docs/contacts/user-attributes
> Section: Contacts

User attributes are the fields stored on each contact, such as name, email, phone number, country or a customer tier you define. They give your AI agents and your team context about who they are talking to, and they appear in the user info panel next to every conversation.

Manage the list of attributes in **Settings → Data & Developer → User Attributes**. Choose how attributes are filled for each channel in **Settings → General → People**.

## Which user attributes does Robylon capture automatically?

Every workspace has a set of default attributes, most of them marked **Default** and **System Generated**. Robylon fills them in for you.

| Attribute | Key | Type | Where the value comes from |
| --- | --- | --- | --- |
| Client User ID | `client_user_id` | Text | The ID your website or app passes for a logged-in customer |
| Phone Number | `phone_number` | Text | Phone calls and WhatsApp conversations |
| Email ID | `email` | Text | Your customer lookup API, ticket systems, or the chatbot |
| Customer name | `customer_name` | Text | Your customer lookup API, helpdesks such as Freshdesk, or logged-in chatbot users |
| Connected Agent | `assigned_agent` | Dropdown | The agent assigned to the customer for sticky assignment, set when an agent handles their chat and editable by hand |
| Email ID domain | `email_domain` | Text | The domain part of the email address |
| First contacted | `first_contacted_at` | Date | The customer's first conversation on any channel |
| Last contacted | `last_contacted_at` | Date | The customer's latest conversation on any channel |
| Browser | `browser` | Text | The Chatbot SDK |
| Browser version | `browser_version` | Text | The Chatbot SDK |
| Country | `country` | Text | The customer's IP address, via the Chatbot SDK |
| Region | `region` | Text | The customer's IP address, via the Chatbot SDK |
| City | `city` | Text | The customer's IP address, via the Chatbot SDK |
| OS | `os` | Text | The customer's device, via the Chatbot SDK |
| Total conversations | `total_conversations` | Number | Conversations the customer started on any channel. Only counts conversations where the customer sent a message, so missed calls and outbound messages are excluded. |
| Channels interacted | `channels` | Text | Every channel the customer has used, such as chatbot, WhatsApp, voice or email |
| IP Address | `ip_address` | Text | The customer's connection during chatbot conversations or voice calls |

## How do I create a custom user attribute?

Click **Add an Attribute**, fill in the fields and save.

<Steps>
  <Step title="Open User Attributes">
    Go to **Settings → Data & Developer → User Attributes** and click **Add an Attribute**.
  </Step>
  <Step title="Name and describe it">
    Enter a **Name**, for example "Loyalty tier". Robylon creates the attribute's key from the name in lowercase with underscores (`loyalty_tier`). Add a **Description** so your team and your AI agents know what it holds.
  </Step>
  <Step title="Choose a type">
    Under **Type of Attribute**, pick **Text**, **Number** or **Dropdown**. For a dropdown, add the values customers can have.
  </Step>
  <Step title="Choose who sees and edits it">
    Switch on **Editable by Human Agents?** to let agents change the value from the inbox. Switch on **Display it in User Info Panel?** to show it next to conversations.
  </Step>
  <Step title="Save">
    Click **Save**. The attribute now appears on every contact, empty until a value is captured.
  </Step>
</Steps>

Attribute names must be unique in your workspace. If two names would give the same key, Robylon adds a number to the second one (`loyalty_tier_1`).

To change a custom attribute, click its row in the list. You can also delete a custom attribute from its row. Attributes marked **Default** cannot be edited or deleted.

## How do user attributes get filled in for each channel?

In **Settings → General → People**, under **User Attributes Per Channel**, each channel can look up the customer in your own system and save what it finds as user attributes.

| Channel | How the customer is identified | Input variables for the lookup |
| --- | --- | --- |
| **Robylon Chat** | Details passed by the Chat SDK when the widget starts | `{chat_email}`, `{chat_client_user_id}`, `{chat_name}`, `{chat_phone_number}` |
| **WhatsApp** | The phone number on the incoming message | `{wa_phone_number}` (E.164 format), `{wa_profile_name}`, `{wa_message_text}`, `{wa_message_id}` |
| **Email** | The sender's email address on the incoming email | `{email_from}`, `{email_from_name}`, `{email_subject}`, `{email_message_id}` |
| **Voice** | The caller's phone number on an incoming call | `{caller_phone_number}` (E.164 format) |

A channel shows **Set up** until it has a lookup, and **Configured** once it does. WhatsApp shows **Connect** until you [connect WhatsApp](https://www.robylon.ai/docs/whatsapp/connect).

For the chatbot you can also skip the lookup: pass attributes straight from your website through the Chat SDK. Send an `api_key`, an optional `user_id` and a `user_profile` object when the widget loads, and the values are attached to the contact when the conversation starts. The SDK works with React, plain JavaScript and no-code platforms such as Wix, Squarespace, WordPress and Google Tag Manager. See [chatbot installation](https://www.robylon.ai/docs/chatbot/installation).

## How do I set up a lookup API?

Point Robylon at an endpoint in your system that returns customer details, then map the response to user attributes.

<Steps>
  <Step title="Open the channel">
    Go to **Settings → General → People** and click **Set up** (or **Edit**) next to the channel.
  </Step>
  <Step title="Configure the lookup API">
    Under **Configure The Lookup API**, choose the **Method** (**GET**, the default, or **POST**, **PUT**, **PATCH** or **DELETE**) and enter the **API URL**. Use `{variable_name}` placeholders to insert an input variable, for example `https://api.example.com/customers?email={chat_email}`. Add any **Headers**, **Params** or **Body** your API needs.
  </Step>
  <Step title="Test the API">
    Click **Test API** to call your endpoint and see the response.
  </Step>
  <Step title="Map the response">
    Under **Map The Response To User Info**, click **Add mapping**. Enter the **Path** to a value in the response (for example `response.user_id`) and choose the user attribute to **Save To User Info**. Add one mapping per attribute. A channel counts as configured once it has at least one mapping.
  </Step>
  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

Store API keys for your endpoint in [credentials](https://www.robylon.ai/docs/data-and-integrations/secrets-keys) rather than pasting them into headers in plain text.

The lookup runs when a customer reaches you on that channel: when the chatbot starts with Chat SDK details, and on incoming WhatsApp messages, emails and calls. Robylon reuses a customer's result for up to 6 hours, so your API is not called for every message. If the call fails, Robylon tries again after about 15 minutes.

## How are user attributes used?

* **In the inbox:** attributes marked **Display it in User Info Panel?** show next to each conversation, so agents see who they are talking to without asking. See [the inbox panel](https://www.robylon.ai/docs/inbox/inbox-panel).
* **By workflows:** a workflow's **Update User Info** action writes a value to a user attribute, so details learned in one conversation are kept for the next. See [variables](https://www.robylon.ai/docs/data-and-integrations/variables-intents-entities).
* **For merging contacts:** Client User ID, email and phone number are the identifiers Robylon uses to [merge duplicate contacts](https://www.robylon.ai/docs/contacts/users-and-leads).
* **In reports:** chat and ticket [reports](https://www.robylon.ai/docs/analytics/reports) include user details for each conversation.
* **In AI agents and workflows:** AI agents and workflows can read a customer's attribute values, for example to personalise a reply or to route a premium customer to your team.