Understand contacts in a few steps
If you just need the essentials, follow this:
- Know what a contact is and how it connects to channels
- Create contacts manually, automatically via channels, or by bulk import
- Use contact fields (default + custom) to store project data
- Manage contact addresses (URNs) and their priority for correct delivery
- Reference contact data in flows with @contact and the last message with @input
You’re done. You can now structure contact data cleanly and understand how RapidPro.app decides where to send messages.
Step-by-Step Process
A contact is an end-user who has interacted (or will interact) with your RapidPro.app workspace. Communication with contacts happens through a channel
(SMS, Telegram, Messenger, and more).
[CAPTURE: Contacts tab overview showing the contacts list.]
A contact can be created in three main ways:
- Manually in the Contacts tab.
- Automatically when a new address (for example, a phone number) interacts with your workspace through a channel.
- Imported in bulk (for example, via an XLS/XLSX spreadsheet).
Each contact has attributes called contact fields. Fields can store values such as names, phone numbers, and any other data you collect.
RapidPro.app contact fields fall into two types: default fields and custom fields (created by you).
Fields can hold different value types, such as text, numeric, and date/time.
[CAPTURE: Contact fields section showing default + custom fields.]
Default fields
Default fields typically include items like Name, Channel / Preferred Channel, Language, and Status (for example, active/blocked).
[CAPTURE: Default fields visible on a contact profile.]
Custom fields
Custom fields are fields you create to store project-specific information, such as age (numeric), registered_on (date/time), or village (text).
[CAPTURE: Custom fields list or “Add field” interface.]
A contact’s address (also called a URN) is where RapidPro.app sends messages to reach that contact. Common URN types include phone numbers (SMS/Voice),
Telegram identifiers, Facebook/Messenger IDs, email addresses, and external identifiers for custom integrations.
A contact can have multiple addresses, including multiple addresses of the same type (for example, two phone numbers). If a contact has multiple addresses,
you can prioritize them to control which address is preferred.
[CAPTURE: Contact profile showing multiple URNs/addresses.]
Prioritizing addresses
- Prioritized addresses appear in order on the contact profile.
- Only the top prioritized address typically appears in the main contacts list view.
[CAPTURE: Contact profile showing URNs ordered by priority.]
[CAPTURE: Contacts list showing only the prioritized URN.]
Channels, URN types, and preferred channel behavior
RapidPro.app maps channel types to corresponding address types (URN types). A contact’s preferred channel and URN priority help determine how messages are sent.
If you have multiple channels of the same type (for example, multiple SMS numbers), RapidPro.app typically prioritizes the channel the contact last initiated contact with,
depending on configuration.
Contacts can become “locked” to a specific channel when multiple channels of the same type exist, the contact’s URN priority matches that channel type,
and the contact initiates contact via an incoming message.
[CAPTURE: Table or diagram showing channel types mapped to URN types.]
RapidPro.app lets you reference contact data using variables. @contact refers to the active contact (the person currently in the flow),
and @input refers to the last message received from the contact.
@contact basics
Common examples include:
- @contact / @contact.name — name (or fallback identifier)
- @contact.first_name — first name (if set)
- @contact.groups — groups the contact belongs to
- @contact.uuid — unique identifier
- @contact.display — name or URN shown in UI
- @contact.language — language code (ISO)
- @contact.created_on — creation timestamp
- @contact.channel — preferred channel
- @contact.fields.[field_name] — custom field value (for example, @contact.fields.age)
[CAPTURE: Flow editor showing a message using @contact fields.]
Referencing the last incoming message with @input
Common examples include:
- @input.text — message text
- @input.created_on — timestamp of the input
- @input.type — input type
- @input.uuid — input ID
- @input.channel — channel where the input was received
- @input.attachments — attachments from the last message
[CAPTURE: Flow showing a rule or split using @input.text.]
Common Issues & Quick Fixes
Problem: New contacts aren’t appearing in my workspace.
Fix: Confirm you have an active channel connected and that the contact is messaging the correct channel; contacts are created automatically when a new address interacts through a channel.
Problem: Messages go to the wrong number or platform for a contact.
Fix: Check the contact’s URN list and ensure the correct address is prioritized, then review the contact’s preferred channel configuration.
Problem: A custom field shows blank in a flow.
Fix: Verify the field key matches exactly in your expression (for example, @contact.fields.age), and confirm the field is populated on the contact record.