Contacts
Import, organize, and segment your contact list — the foundation of every campaign and chatbot interaction.
Contact Fields
Every contact has built-in fields plus up to 10 custom fields you define for your organization:| Field | Type | Notes |
|---|---|---|
| Phone Number | Required | E.164 format (+12125551234). Primary unique identifier. |
| Name | Text | Display name shown in conversations and campaign logs. |
| Optional — useful for cross-channel identification. | ||
| Tags | Array | Comma-separated labels for segmentation and filtering. |
| Opted In | Boolean | false means this contact is excluded from all campaigns. |
| Last Seen | DateTime | Auto-updated on every incoming message. |
| cf1 – cf10 | Text | Custom fields you define in Contacts → Custom Fields. |
Custom Fields (cf1–cf10)
Custom fields let you store business-specific data on contacts — invoice numbers, company names, plan tiers, order IDs, or anything else your templates or chatbots need.1
Define your fields
Click Custom Fields in the Contacts toolbar. Enter a display label for each field slot you want to activate (e.g. cf1 → "Company Name", cf2 → "Invoice Number"). Leave unused slots blank. Save — the labels take effect immediately across the add/edit forms and the export.
2
Set values on contacts
Open any contact's edit dialog — defined custom field inputs appear below the standard fields. Values are saved per-contact.
3
Use in campaigns
When mapping template variables, the From Contact dropdown includes all your defined custom fields. Selecting "Company Name" stores the token
{{contact.cf1}} and resolves to each recipient's value at send time.4
Use in chatbots
Custom field values are automatically injected into chatbot session variables. Use
{{cf1}} in any chatbot message, question, or condition to reference the contact's custom field value.Tip
Also pre-populated in chatbot sessions:
{{contact_name}}, {{contact_phone}}, and {{contact_email}} — no "Ask Question" node needed for these.Adding Contacts
1
Manual add
Click Add Contact in the Contacts toolbar. Enter phone (required), name, email, tags, and any defined custom field values. Best for individual contacts or testing.
2
CSV import
Click Import CSV. Your CSV must have a
phone column. Include custom fields using either the raw key (cf1, cf2, …) or the label you defined (case-insensitive).phone,name,email,tags,Company Name,Invoice Number
+12125551234,John Smith,john@acme.com,"vip,enterprise",Acme Corp,INV-001
+447911123456,Emma Jones,emma@co.uk,"trial",Widget Ltd,INV-0023
Auto-created from incoming messages
When someone messages your WhatsApp number for the first time, MotherBot automatically creates a contact with their phone number and WhatsApp display name. Enrich it with custom fields later.
4
API
Use
POST /api/whatsapp/contacts to create contacts programmatically, passing customFields: { cf1: "Acme", cf2: "INV-001" }.Exporting Contacts
Click Export to download the visible contacts as a CSV. The export includes all standard fields plus one column per defined custom field (using your label as the column header). Use this file as a template for future imports.name,phone,email,tags,opted_in,source,Company Name,Invoice Number
John Smith,+12125551234,john@acme.com,"vip,enterprise",true,import,Acme Corp,INV-001Tags
Tags are free-form labels for quick categorization and audience targeting:- Add tags manually in the contact's edit dialog, or via the chatbot 'Add Tag' action.
- Bulk-tag: select multiple contacts → Apply tag in the action bar.
- Filter the contact list by one or more tags.
- Use tags to define campaign audiences — only contacts with the selected tag(s) receive the campaign.
- Remove tags via chatbot, API, or manually.
Opt-out Management
MotherBot automatically handles opt-outs to keep you compliant with Meta's policies:- If a contact sends STOP (or a configured opt-out keyword), their Opted In flag is set to false.
- Opted-out contacts are excluded from all future campaigns automatically.
- You can still receive and respond to messages from opted-out contacts — only outbound campaign sending is blocked.
- Contacts can opt back in by messaging your number — the flag resets automatically.
- Never manually set Opted In = true for a contact who sent STOP — this violates WhatsApp policy.
Warning
Including opted-out contacts in campaigns can get your Meta account flagged. MotherBot's audience filters always exclude them automatically.