Contacts

Contacts is the directory of people identified through your organization’s external channels. A person may start with one phone number, email, handle, or channel ID and later have several identities collected in the same record.

Open Contacts in the admin sidebar. The route requires contacts.view; changing the name or notes requires contacts.write; merging or undoing a merge requires contacts.merge. The current Attendant package includes all three capabilities, but a custom role may receive only some of them.

Internal Hub conversations between members do not create an external contact by themselves. A record appears when SquadOS can associate the interaction with an external_contacts record.

Find a contact

The list shows 50 records per page, newest first. Each row can include:

• Contact — the primary identity, such as a phone number, email, handle, or channel ID;
• Channel — WhatsApp, Telegram, Instagram, Email, API, or Website;
• Name — the name received from the channel or saved by the team;
• Lists — subscriptions tied to an email address;
• Tags — the contact tags;
• Source — channel, manual addition, or import, depending on the contact type;
• Status — any suppression attached to the email address; without one, the cell is empty.

Use search to find a name or identity. It also checks related identities, such as another phone number or handle, and warns when that slice exceeds 300 matches; narrow the term in that case. The available filters are channel and tag. Administrators also see the list filter.

Click the row or View details to open the record. If a query fails and the screen says No contacts yet or No contact matches the filters, reload before concluding the directory is empty: the list currently does not distinguish a loading error from an empty result.

Add, import, and export

The Add contact, Import CSV, Export CSV, and list-filter controls are available only to administrators. They belong to the email campaign workflow; they do not create an arbitrary channel identity manually.

• Add contact accepts an email, an optional name, a list, and the consent source. The contact is created or resolved by email and subscribed to the selected list.
• Import CSV opens the email-contact import wizard for a list.
• Export CSV applies the current search and filters across every page, not just the 50 visible records. The current export has a silent limit of 20,000 contacts; for a larger directory, split it with filters before treating the file as complete.

Read and edit the record

The contact record brings together:

• Name — editable with contacts.write;
• Identities — every address and identifier collected under this person;
• Merged records — absorbed records that remain preserved as pointers;
• Email lists — address, list, state, and whether the subscription belongs to an absorbed record;
• Contact tags — durable attributes of the person, shared across conversations;
• Internal notes — key-value pairs on the contact, such as plan: premium or city: Campinas;
• Conversations — up to the person’s 20 most recent conversations, ordered by last message.

Expanding a conversation in the record shows up to the 30 most recent readable user and assistant messages. Use Open conversation to access the complete exchange.

Contact notes are not free-form messages

The record’s Internal notes are structured contact memory. The team can create, change, or remove one key, and the native manage_notes tool lets an agent read and update the same object when the conversation is linked to that person. Store short, stable facts; do not use this field for sensitive content or a long narrative.

This differs from an Internal note: an internal note is a free-form human message in one conversation’s timeline and is not added to agent context.

Merge duplicate records

Use Merge contacts when two records represent the same person. Find the other record, choose which one stays, and review the summary before confirming.

A merge:

1. moves identities and conversations and adds tags that are not already on the surviving record;
2. copies only note keys that the survivor does not already have;
3. takes the absorbed record’s name only if the survivor has no name;
4. keeps the absorbed record as a pointer with an exact operation journal;
5. leaves subscriptions, suppressions, and send history tied to the original email address—the surviving record only combines their display.

Nothing is deleted. Undo appears in the confirmation for 15 seconds and beside merged records in the contact record. When you undo, later edits are preserved whenever they no longer match the value copied by the merge.

SquadOS does not build merge chains. If a record has already been absorbed, has absorbed another record, or points to another survivor, undo the earlier operation or select the surviving record directly.

Contacts, conversations, and tags

Item	Scope	Example
Contact	A person identified in one or more external channels	Maria, with WhatsApp and email
Conversation	One exchange on one channel	A question sent on WhatsApp
Contact tag	A durable characteristic of the person	customer, hot lead
Conversation tag	Context for that one exchange	refund, negotiation
Contact note	A structured fact available to the team and AI	plan: premium
Internal note	A private human message in that conversation	“Confirm receipt tomorrow”

If the label remains true in other conversations, use a contact tag. If it only describes the current exchange, use a conversation tag.