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, or deleting contacts, 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, phone number, email, or channel identifier. The slice selector has two groups: By registration (With phone, With email) filters by what the person has on file, and By channel filters by where they talked to you. These are different axes — someone who arrived through WhatsApp and gave their email later appears in both. The tag filter always applies; 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 import wizard, which loads a spreadsheet into the directory in four steps. The destination list is optional: without one, contacts go only into the directory. Large files upload in blocks, with a counter of processed rows during the wait.
• 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.

Start conversation opens an exchange with this person through a WhatsApp inbox, already assigned to you and with AI disabled. See Managing Conversations.

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.

Delete contacts

Use Delete contact when the organization needs to remove the data of one person, and Delete all contacts when it needs to remove the data of the whole directory. This is different from taking a contact off a list, which keeps the record and its history. Both paths follow the same process, person by person.

This can’t be undone

Once the request is accepted, what was removed does not come back. There is no trash and no option to cancel on the screen. Before confirming, decide whether the organization must keep any data, whether by legal obligation or for another reason: that decision belongs to the organization as the data controller, and SquadOS has no option to keep the content of one specific contact.

Gradual rollout

This feature is being released gradually. If you have the permission and the buttons below don’t appear, it hasn’t reached your organization yet.

Where it is and who can use it

• One contact: open the record and choose Delete contact. The deletion covers the person’s identities and merged records, and the merge can no longer be undone.
• All contacts: on the Contacts screen, open More actions (the three-dot button) and choose Delete all contacts.

Both actions require the permission to edit contacts (contacts.write), the same one that lets you change the record’s name and notes. In the default packages, it is part of the Administrator role and the owner, besides the Attendant package mentioned at the start of this article; a custom role may or may not include it. In organizations that use departments, whoever has Manage contacts can also delete.

Confirm the deletion

1. The window shows the Organization and how many contacts and Conversations will be affected, and summarizes what happens to the data.
2. Copy the text shown and type it in the field: EXCLUIR for one contact, EXCLUIR TODOS for all of them. The text is the same when the interface is in English.
3. Confirm with the window’s button, Delete contact or Delete all contacts.

If the count changes between opening the window and confirming — for example, because a new contact arrived — nothing is deleted: the window shows the new number and asks you to type the text and confirm again.

Delete all contacts works like this:

• it includes every page of the list and does not depend on the search or filters applied;
• it counts people: merged records count as one;
• it closes the set at confirmation. Contacts that arrive afterward are not part of the batch, and channels keep receiving messages normally.

What is removed

• the record data: name, identities, notes, tags, and list subscriptions;
• the conversation content: messages, attachments, internal notes, summaries, and satisfaction ratings;
• the files of those conversations.

Pending email sends, automations, and webhooks for the person are stopped. If an automation had this person chosen as a fixed contact, by name or by identifier, in the Pick contact step (see Actions), that choice is removed from the step, which has to be configured again. The rest of the automation does not change.

What may remain

• Counts for reports and billing, such as tokens, credits, and metrics, without personal text.
• Unsubscribe protections. They keep blocking new sends with the same scope as before: an unsubscribe from a list applies to that list, and an email suppression keeps applying to the organization. Importing the person again, or the person writing to you again, does not remove the protection.
• A technical reference, when the contact had history. It does not hold the person’s data and appears as Contact deleted. When you open an old conversation with that person, the content does not appear and you cannot send messages.

These items have a purpose of their own — reports, billing, and protection against new sends — and are not a copy of the record.

Follow the progress

After you confirm, the record closes and the Contacts screen shows a card with Total, Completed, Pending, and Failed. The title shows the state of the request:

State	What it means
Deletion queued	The request was accepted and is waiting to be processed
Deletion in progress	SquadOS is removing the data. The current step appears below the title: Recording the request, Stopping sends and automations, Removing files, Removing data and content, or Checking the removal
Deletion complete	Every contact in the request was processed. The card summarizes what was deleted and, when applicable, the unsubscribe protections kept and the external procedures still pending
Deletion needs attention	At least one contact was not finished

You can close the screen: the server keeps deleting. Temporary failures are retried automatically. If the request stays at Deletion needs attention, the card shows the Request code; give that code to support.

When you return to the Contacts screen, the card reappears while the request is queued, in progress, or needs attention. A completed request stops being listed once the screen is reloaded, so note any pending external procedures before reloading or using Close.

While one person’s deletion runs, their record shows the Deletion in progress notice and cannot be edited, merged, or used for Start conversation. Other contacts and conversations keep working.

If the person writes to you again

If the person writes again through a channel, SquadOS creates a new contact and a new conversation, without the previous history and without restoring campaign subscriptions. A kept unsubscribe protection still applies to that new contact.

What deletion does not reach

SquadOS removes what it controls. Other copies depend on the organization or on whoever received them:

• Messages already delivered stay on the recipient’s device or in their mailbox, on WhatsApp, email, and the other channels. SquadOS does not erase conversations inside those services.
• Exported or downloaded files and copies saved to Files from a conversation are independent of the conversation’s files, and the organization has to handle them. The completion card tells you how many external procedures are still pending: today, that number counts the copies saved to Files. What left SquadOS by other routes, such as exports and downloads, is not counted.
• Webhooks already delivered to external systems are not undone. Handle the data in those systems there.
• Backups of SquadOS expire on their own cycle. If a backup is restored, SquadOS applies the deletion again from the request record, with no action needed from the organization.

Completing the deletion in SquadOS does not replace the organization’s own assessment of those external copies.

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.