Personalize messages with the active contact
If you just need the essentials, follow this quick path:
- Confirm what @contact refers to (the active contact in the run)
- Use common @contact properties (name, first_name, language, groups)
- Reference custom fields via @contact.fields or @fields
- Use @urns to reference addresses (tel, mailto, WhatsApp, etc.)
- Store inputs with @results, then reuse them later via @fields
- Use @input to reference what they just sent (text/attachments)
Once you treat variables as “reusable data,” your flows become clearer, faster to build, and easier to debug.
Step-by-Step Process
- @contact references the active contact receiving the message in the flow.
@contact.nameis the contact’s full name (if set).- If a name is not set, @contact may fall back to a URN (like a phone number), depending on your channel/workspace behavior.
Here are the most used contact variables:
@contact.first_name— friendly greeting (e.g., “Hi Ben”)@contact.groups— which groups the contact belongs to@contact.language— ISO language code (useful for branching)@contact.created_on— when the contact profile was created@contact.uuid— unique identifier (useful for integrations/troubleshooting)
[CAPTURE: A Send Message node showing “Hi @contact.first_name…”]
You can store structured data (age, district, clinic, role, etc.) as contact fields.
Use either:
@contact.fields.field_name(explicit)@fields.field_name(short form)
Examples:
@fields.age@fields.baby_name
[CAPTURE: Message editor showing @fields auto-complete list.]
URN variables reference a contact’s addresses:
@urns.tel— phone number@urns.mailto— email@urns.whatsapp,@urns.facebook, etc. — channel-specific addresses
Use @urns when:
- You want to include contact address info in internal notifications (e.g., email to staff).
- You need to route or log based on channel destination.
[CAPTURE: Send Message to Third Party showing @urns.tel and @urns.mailto in the body.]
A common pattern is:
- Collect user input with Wait for Response → saves as
@results.some_value - Use Update Contact to store it into a contact field
- Later, reuse it via
@fields.some_valueor@contact.fields.some_value
Example:
- Collect name →
@results.name - Save to contact field “name” → later greet using
@contact.first_name
[CAPTURE: Flow snippet with Wait for Response → Update Contact → Send Message using @contact.first_name.]
Use input variables to reference the most recent inbound message or attachment:
@input.text@input.attachments@input.created_on@input.channel
This is useful for:
- Echoing the user’s last response
- Parsing structured submissions
- Handling attachments
[CAPTURE: Example using @input.text in a validation message.]
Common Issues & Quick Fixes
My variable shows as plain text (e.g., “@contact.firstname”)
Problem: The variable name is invalid, so it renders as text.
Fix:
- Check spelling: it should be
@contact.first_name(underscore matters). - Use the @ auto-complete to insert variables instead of typing manually.
I’m using “Send Message to Third Party” and @contact is confusing
Problem: You expected @contact to represent the notification recipient.
Fix:
- Remember: @contact is the active contact in the run, not the recipient.
- If you need the recipient’s details, start that recipient in a flow and message them there using a standard Send Message.
@fields.field_name is empty
Problem: The contact field is missing or has no saved value.
Fix:
- Confirm the field exists in the workspace and the name matches exactly.
- Ensure you updated/saved the value before referencing it.
- Test with a known contact in the Simulator.
@results works, but @fields doesn’t
Problem: You collected a value in this run, but never stored it to the contact record.
Fix:
@resultsis only for values collected in the current run.@fieldsonly works if you stored the value into a contact field (usually via Update Contact).