> ## Documentation Index
> Fetch the complete documentation index at: https://botsify.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# User Attributes: Personalize Botsify Conversations

> Store custom key-value data on individual bot users to power personalized conversations, conditional chat flows, and targeted outbound messaging.

User attributes are custom key-value pairs you attach to individual users in Botsify. They give your bot a persistent memory of facts about each person it talks to — their subscription plan, their preferred language, their name, their account status, or any other data point relevant to your use case. Once stored, these attributes are available to your bot during conversations, enabling personalized responses, conditional logic, and targeted outbound messaging.

***

## What Are User Attributes?

A user attribute is a simple key-value record associated with a specific user (identified by `fbId`) on a specific bot (identified by `apikey`). Attributes are:

* **Persistent** — they survive across conversations and sessions.
* **Bot-scoped** — attributes set on one bot are not visible to other bots, even within the same workspace.
* **Flexible** — keys and values are strings, so you can store anything that can be expressed as text.

Examples of user attributes in practice:

| Key | Example Value | Use Case |
| - | - | - |
| `plan` | `"pro"` | Show pro-only features in bot responses |
| `language` | `"es"` | Respond in the user's preferred language |
| `onboarding_complete` | `"true"` | Skip onboarding flow for returning users |
| `account_id` | `"acc_9812"` | Reference the user's account in responses |
| `last_order_id` | `"ord_4521"` | Personalize support conversations |

***

## Setting a User Attribute

Use the `POST /api/v1/add-user-attribute` endpoint to set or update an attribute on a user. Authentication is via the bot's `apikey` (passed in the request body), which ensures that attributes are always scoped to the correct bot.

```bash theme={null}
curl -X POST https://app.botsify.com/api/v1/add-user-attribute \
  -H "Content-Type: application/json" \
  -d '{
    "apikey": "YOUR_BOT_API_KEY",
    "messenger_user_id": "user-123",
    "fbId": "user-123",
    "key": "plan",
    "value": "pro"
  }'
```

**Request body fields:**

| Field | Type | Description |
| - | - | - |
| `apikey` | string | Your bot's API key. Scopes the attribute to this specific bot. |
| `messenger_user_id` | string | The user's identifier (typically the same value as `fbId`). |
| `fbId` | string | The user's conversation identifier, matching what you pass to `/converse`. |
| `key` | string | The attribute name (e.g. `"plan"`, `"language"`). |
| `value` | string | The attribute value to store (e.g. `"pro"`, `"en"`). |

> [!NOTE]
>
> User attributes are scoped to the bot identified by the `apikey` you provide. The same user (`fbId`) can have different attributes on different bots — setting an attribute on one bot has no effect on that user's data in any other bot.

***

## Use Cases

### Personalization

Once you know something about a user — their name, their role, their preferences — you can store it as an attribute and have your bot reference it in future turns. Instead of asking for the same information repeatedly, the bot can greet users by name, skip steps they've already completed, and tailor responses to their situation.

### Segmentation and Conditional Flows

Attributes enable conditional logic in your chat flows. For example, a `plan` attribute with value `"free"` could route users to a self-service flow, while `"enterprise"` routes them to a human agent handoff. Your flow logic checks the attribute value at runtime and branches accordingly.

### Targeted Outbound Messaging

When sending proactive outbound messages, you can use attributes to filter and target specific user segments — for example, only send a renewal reminder to users whose `subscription_status` is `"expiring"`.

### Context Across Sessions

Because attributes persist beyond individual conversations, they let your bot accumulate knowledge about a user over time. Each interaction can update attributes based on what you learn, making the bot progressively smarter about each person.

***

## Best Practices

> [!TIP]
>
> **Set attributes proactively** — update user attributes at meaningful moments in your integration (e.g. after a purchase, after account verification, after plan upgrade) rather than only inside conversation flows. This ensures the bot always has up-to-date data.

> [!TIP]
>
> **Use consistent key naming** — establish a naming convention for your attribute keys (e.g. snake\_case: `subscription_plan`, `preferred_language`) and document them. Inconsistent key names lead to attributes that are never read by your flows.

> [!WARNING]
>
> **Do not store sensitive personal data** as user attributes unless you have assessed the data handling implications for your use case. Botsify user attributes are accessible via the API — treat them like any other application database and apply appropriate data minimization principles.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.