Contact Tags

Contact tags are colored labels used to classify a person—for example, “hot lead,” “customer,” or “awaiting payment.” The catalog is shared by the organization, and each tag can be linked to multiple contacts.

They belong to the contact record, not to a conversation. They therefore appear across every conversation linked to the same unified contact. Channels or identities that still belong to separate records do not share tags until the contacts are merged. The customer-facing interface does not render these labels; they are for internal operations.

Caution

Do not confuse Contact tag with Conversation tag. The former describes the person across all conversations; the latter describes only the subject of one conversation. Both use the same catalog of names and colors but store different associations.

Where to find contact tags

In /admin/conversations:

1. Open a conversation that has an external contact.
2. In the Context panel, select the Contact tab.
3. Find Contact tags in the person’s profile. When editing is available, the block shows the current labels, Add, and the removal ×.

Conversations without an externalContactId, such as an internal conversation with no external person attached, do not show contact tags. In the conversation list, chips appear with the other indicators: the current view shows up to two tags and summarizes the rest as +N.

Applying or creating a tag

In the Contact tags block:

1. Click Add.
2. Use Search or create tag….
3. If the name already exists, select the matching tag.
4. Otherwise, select Create “name” to create and apply it in one operation.

Name matching is case-insensitive. Creating VIP when vip already exists reuses the stored tag. A new tag deterministically receives one of the catalog’s eight colors; reapplying the same tag neither duplicates it nor changes its color.

To remove the association, click the chip’s ×. This removes the tag only from that contact; the label remains in the catalog and on other contacts.

Filtering conversations by contact tag

1. In Conversations, click Filters.
2. Open Contact tag.
3. Search for and select one or more tags.

When several contact tags are selected, the list includes contacts that carry any one of them. Other filters—such as inbox, channel, agent, and Conversation tag—still apply together. The selection is stored in the URL’s tags parameter, so the link preserves the filter.

Caution

At present, a failure while querying tag associations can be shown as an empty list. If a known filter unexpectedly returns zero conversations, reload and confirm without the filter before concluding that there are no results.

Applying tags in bulk

The current list lets you select up to 50 visible conversations per action. After selecting them:

1. Open Actions.
2. Under Organization, choose Add tag or Remove tag.
3. Select an existing tag and confirm.

The action changes the contact linked to each conversation, not the conversation itself. Each item is validated separately: conversations with no external contact or insufficient permission can fail while the others continue. To label the subject of the selected conversations, use Tag conversations.

Managing the catalog

The product contains a Manage tags dialog that can show contact counts, rename, recolor, and delete tags. However, the current Conversations interface mounts its tag filter with that action disabled and provides no other button that opens the dialog.

Do not look for Manage tags in the current filter. You can still create a tag while applying it to one contact. To list, rename, recolor, or delete the catalog, use the documented Tags API. Deleting a catalog tag removes it from every contact and cannot be undone.

Agents, API, and Automations

All of these paths use the contact-tag catalog:

• The Contact Tags native tool (manage_tags) lists, applies/creates by name, and removes tags on the current conversation’s external contact.
• The Tags API manages the catalog and UUID-based associations.
• In Automations, the Contact tag trigger reacts when a tag is applied or removed, and the Apply tag action adds or removes tags from the contact. Automations may still be limited by the organization’s rollout.

Permissions and screen updates

The granular contract separates contacts.view, which reads contacts and the catalog, from contacts.write, which changes the record. The Conversations route requires conversations.view.

Caution

There is a known product inconsistency: the current panel can show editing controls without checking contacts.write, while the tag RPCs still check for the legacy collaborator-or-higher role. Someone who sees the control can therefore receive Failed to apply tag, and a granular role may not produce the expected result. Treat this as a product permission issue and ask an administrator to review the role; do not recreate the tag repeatedly.

A change made by you invalidates local caches and usually appears immediately. External events update the conversation list and catalog, but currently do not invalidate the contact-specific query in a panel that is already open. If an agent, automation, or teammate changed a tag and the panel did not follow, switch to another conversation and back or reload before acting again.

Best practices

• Use a small set of canonical names and check the catalog before creating a variation.
• Tell the agent exactly when manage_tags should apply or remove each label.
• Combine Contact tag with Conversation tag when you need both the person’s profile and the conversation’s subject.
• Do not use tags for secrets or unnecessary personal data: they are visible to anyone allowed to read contacts in the organization.