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.

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").

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

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.

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.

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.