Skip to main content
Attributes are the structured data fields Soneka attaches to every contact and conversation. Think of them as columns in a CRM — but live, syncable, and usable inside every message, broadcast, flow, and AI agent you build. Instead of storing customer context in spreadsheets or scattered notes, attributes let your team, your automations, and your AI reference the same source of truth in real time.
Image

​
Who It’s For

Attributes are for any team that wants to move beyond generic broadcasts and support. E-commerce teams use them to store last_order_id and lifetime_value. Healthcare clinics store appointment_date and insurance_provider. SaaS companies track plan_tier and trial_expires_at. If you’ve ever wished a WhatsApp message could say more than “Hi ”, attributes are the answer.

​
Attribute Types

Every attribute in Soneka has a fixed data type. Choosing the right type unlocks validation, filtering, and formatting for that field everywhere it’s used.

Text

Free-form strings up to 500 characters. Best for names, addresses, notes, or any unstructured value.

Number

Integers or decimals. Supports arithmetic in flows (e.g., cart_value > 5000) and formatting in messages.

Date

ISO 8601 dates and datetimes. Enables relative filters like “expires in 7 days” and timezone-aware scheduling.

Boolean

True/false flags. Ideal for opted_in, vip, has_paid, or any binary state you branch on.

List

Predefined single-select or multi-select options (e.g., plan_tier: [free, pro, enterprise]). Guarantees consistent values.

URL

Validated links. Auto-formats as clickable in the inbox and passes safely into template buttons.
Types are enforced at write time. If a flow tries to save "tomorrow" into a Date attribute, Soneka rejects the write and logs the error rather than silently corrupting your data.

​
System vs Custom Attributes

Soneka ships with a set of system attributes that are populated automatically, and lets you define unlimited custom attributes for anything specific to your business. System attributes are guaranteed to exist on every contact. Custom attributes are optional per contact — a missing value returns null rather than an error, and you can set fallbacks in templates.

​
Creating a Custom Attribute

1

Open the Attributes Library

Navigate to Settings → Contacts → Attributes. You’ll see all existing system and custom attributes, along with their types and usage counts.
2

Click New Attribute

In the top-right, click + New Attribute. Give it a name (lowercase, snake_case is recommended — e.g., last_order_total) and a human-friendly label (e.g., “Last Order Total”).
3

Pick a Type

Select one of the six types above. For List, add each allowed option on its own line. For Number, choose whether to allow decimals.
4

Set a Default Value (Optional)

Provide a default that Soneka assigns when a new contact is created without an explicit value. Useful for flags like opted_in: false.
5

Choose Visibility

Decide whether agents can edit this attribute from the inbox, or whether it’s system-managed by flows and integrations only. Locking sensitive attributes (like lifetime_value) prevents accidental edits.
6

Save

Click Create Attribute. The field is now available across broadcasts, flows, templates, AI agents, and the inbox sidebar.
Renaming an attribute updates its label everywhere, but the underlying key stays the same. Deleting an attribute is permanent and removes the value from every contact — export first if you might need it back.

​
Populating Attribute Values

Attributes are only useful if they’re kept fresh. Soneka gives you five ways to write values, and most teams use a combination.
Any agent with permission can update attributes from the contact sidebar during a conversation. Great for ad-hoc updates like address changes or preferences captured verbally.
The Set Attribute node writes a value at any step in a flow. Combine with Ask Question nodes to collect data conversationally — e.g., ask for the customer’s city, then save it into city.
Bulk-update thousands of contacts by uploading a CSV. Soneka matches on phone and updates only the columns you include, leaving other attributes untouched.
POST to /v1/contacts/{id}/attributes to sync from your CRM, e-commerce platform, or data warehouse. Ideal for real-time updates like last_order_id after checkout.
Shopify, WooCommerce, and Google Sheets integrations map source fields to Soneka attributes automatically. Set the mapping once and updates flow both ways.

​
Using Attributes in Messages

Attributes drop into any message using double-brace syntax: {{attribute_name}}. Soneka validates references at send time and warns you if a template uses an attribute that doesn’t exist.

​
Fallbacks

If an attribute might be missing, provide a fallback with the pipe syntax so the message never renders as an awkward blank:
If name is empty, the message renders as “Hi there, thanks for reaching out!”.

​
Segmenting with Attributes

Every attribute becomes a filter you can layer in the Audience Builder for broadcasts and flow entry points. Filters combine with AND/OR logic and support ranges, list membership, and “exists / doesn’t exist” checks. Saved segments update in real time — when a contact’s attributes change, they enter or leave segments automatically without a re-run.

​
Attributes and AI Agents

AI agents read attributes as part of their context on every reply. This means an agent can greet a returning customer by name, quote the correct plan tier, or refuse to discuss billing with a contact whose verified flag is false — all without you writing custom prompts for each case.
When designing an AI agent, list the exact attributes it should reference in the System Prompt. This prevents hallucination and keeps replies grounded in your real data.

​
Best Practices

  • Name attributes for their meaning, not their source. customer_city beats shopify_city — you may swap sources later.
  • Prefer List types over free-text where possible. Consistent values make segments and analytics reliable.
  • Use booleans for state, not text. is_vip: true is faster to filter than vip_status: "yes".
  • Lock down financial and PII attributes. Restrict edit access to admins and integrations only.
  • Set defaults for opt-in flags. Never leave opted_in as null — it should always be true or false.
  • Archive unused attributes quarterly. Fewer fields means faster imports and cleaner UX for agents.

​
Limits

Need more? Enterprise plans lift these ceilings — contact support to discuss your use case.