Skip to content

Contacts ​

Contacts is the CRM native app: people and companies you work with, their properties, activities, and segments. Install Contacts under Team settings → Apps, then open Contacts in the sidebar. Points and wallet passes live in the separate Loyalty app.

Overview ​

  • Store name, email, phone, tags, avatars, and custom properties
  • Log activities, view timeline, and browse memories / orders on a contact
  • Link contacts with relations — family, social, organization, business, and referrals
  • Message contacts (email / WhatsApp / SMS when integrations allow)
  • Build segments for Campaigns audiences (segment UI lives under Campaigns)
  • Per-contact Loyalty membership when Loyalty is installed
  • Agents manage contacts over MCP — always prefer find-or-create over blind create; leave company empty unless verified

In the app ​

List ​

  1. Open Contacts
  2. Search; filter by tags; use overdue / waiting / engagement filters when shown
  3. Create a contact or open an existing one

On mobile, you can import from the device address book when available (not a CSV bulk import).

Contact profile ​

AreaWhat it shows
DetailsName, email, phone, tags, social links, consent, custom properties
Activity / timelineLogged activities and history (notes, calls, meetings, messages, orders, loyalty, …)
MemoriesAgent memories tied to the contact
OrdersShop orders for this contact (when Shop is installed)
LoyaltyMembership, points, enroll / add / redeem / adjust / history
RelationsLinks to other contacts — family, social, organization, business, referrals
Send messageReach out on an available channel

Relationships between contacts ​

Contacts can be linked to each other with a typed relation, which lets you model family trees, friendships, company structures, business networks, and referral chains. Add and remove them from a contact’s Relations tab; links are grouped by category, and clicking one opens the linked contact.

GroupRelation types
Familyparent_of, child_of, spouse_of, sibling_of, aunt_of, nibling_of (niece/nephew)
Socialfriend_of
Organizationmanages, reports_to, colleague_of
Businesspartner_of, client_of, supplier_of
Referralreferred_by, referred

Relations are read from the first contact’s point of view and stored once in a canonical direction:

  • parent_of means the first contact is the parent of the second
  • referred_by means the second contact referred the first
  • Adding the inverse (for example child_of where parent_of already exists) reuses the same link instead of creating a duplicate
  • Both contacts must belong to the same team

Each relation appears on both contacts, with the type shown from that contact’s perspective. Each relation can also carry an optional short note — for example how the two people met or what a referral was about — which you can add or edit inline. Agents (MCP) can additionally change a relation’s type or clear its note.

Stages and funnel ​

Contact stages are an ordered pipeline each team defines for itself — for example outreached, onboarding, onboarded. A stage has a stable key that agents and routines use, a display name, and a position that fixes the order.

  • Stages (/contacts/stages): add, rename, reorder and archive stages.
  • Stage on a contact: pick a stage in the contact panel. Every change records the time, the acting agent or user, and an optional reason.
  • Funnel (/contacts/funnel): how many contacts sit in each stage, how many entered and exited in the last 30 days, and how many have no stage yet.

Stages are data, not code: another team can run a completely different pipeline without any change to the app.

Segments ​

Reusable audiences for campaigns. Create and manage segments in Campaigns (list + inline creator while building a campaign). MCP segment tools still require the Contacts app installed.

Loyalty ​

Program settings, scanner, and members live in Loyalty. On a contact’s Loyalty tab you can still enroll, add/redeem points, adjust balances, and view history when Loyalty is installed.

Never create duplicates ​

Creating a second contact for the same person is a data-integrity failure.

  • Pass email and/or phone whenever known
  • Prefer find-or-create (warps / MCP flows) over blind create
  • If a contact exists, update missing fields — do not invent a second row
  • Social inbound (Instagram comments, Telegram, …) matches an existing contact by profile URL, username handle, or a unique name before creating a new row
  • When two rows still exist for one person, merge the thin duplicate into the fuller contact

Merge contacts ​

Open a contact → Merge → pick the contact to keep. Activities, conversations, tags, and social links move onto the keeper; empty fields are filled from the duplicate; the duplicate is deleted.

Agents: joai-contact-merge / MCP merge tool — pass the duplicate as contactId and the keeper as intoId.

Research before creating from thin context ​

When an inbound message or a name-only lead is all you have:

  1. Research may fill verified employer, title, website, and socials — never invent them
  2. Put networking groups, events, communities, and interests in tags or notes — never in company
  3. Leave fields empty when unsure — a sparse accurate contact beats a wrong one

For agents (MCP) ​

Requires the Contacts app.

ToolPurpose
list_contacts / create_contact / update_contact / delete_contactCRUD
joai-contact-merge (warp)Absorb a duplicate into another contact
set_contact_propertyCustom properties
create_contact_activity / list_contact_activities / delete_contact_activityActivities
list_contact_timelineTimeline
create_contact_relation / list_contact_relations / update_contact_relation / delete_contact_relationLink contacts, change a relation’s type, add notes, or remove a relation
list_segments / create_segment / delete_segmentSegments (no update_segment — edit in Campaigns UI)
list_contact_stages / upsert_contact_stageRead or define the team's stages (key, name, position, archived)
set_contact_stageMove a contact onto a stage, with an optional reason
get_contact_funnelContacts per stage plus how many entered and exited in a window

Warps such as joai-contact-find-or-create are preferred for onboarding. Pass team when operating outside the agent’s default team.

Sending a message to a contact is UI/HTTP today (no dedicated MCP send-message tool in the contacts catalog).

Live schemas: tools/list. See MCP and SKILL.md.

Tips ​

  • Tag consistently — tags power filters and segments (Automations enroll from props/segments/webhooks, not tags alone)
  • Use segments for recurring campaign audiences and automation segment triggers
  • Attach contacts to Shop orders and Forms submissions
  • CLI also supports contacts — see CLI