Etiquetas de contactos

Administra el catálogo de etiquetas del CRM, ponlas y quítalas a uno o a cientos de contactos, y filtra tu base por ellas.

Las etiquetas son la forma más rápida de segmentar el CRM: «cliente», «lead-caliente», «Participante». En Met viven en dos lugares, y conviene tenerlos separados:

• El catálogo (met.contactTags): las etiquetas que existen en el workspace, aunque ningún contacto las tenga todavía. Es lo que ves en Ajustes y en los selectores del panel, de las difusiones y de los flujos.
• La asignación (met.contacts.addTag y compañía): qué etiquetas tiene cada contacto. Se guarda en el campo de sistema $tags del contacto.

Leer pide contacts:read; escribir, contacts:write. Las dos funcionan con una key de test. Las rutas son planas (/contact-tags, /contacts/…): operan sobre el workspace de la key.

El catálogo

const etiquetas = await met.contactTags.list();
// [{ id: 74, name: 'lead-caliente' }, { id: 75, name: 'Participante' }]

const vip = await met.contactTags.create({ name: 'VIP' });
await met.contactTags.rename(vip.id, 'Cliente VIP');
await met.contactTags.delete(vip.id); // { ok: true }

etiquetas = met.contact_tags.list()

vip = met.contact_tags.create({"name": "VIP"})
met.contact_tags.rename(vip["id"], "Cliente VIP")
met.contact_tags.delete(vip["id"])

curl -X POST https://api.met.meteor.com.co/api/v1/contact-tags \
  -H "Authorization: Bearer $METEOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"VIP"}'

• list() trae todo el catálogo, ordenado por nombre, incluidas las etiquetas que nadie usa.
• El nombre es único en el workspace sin distinguir mayúsculas: VIP y vip son la misma etiqueta, y crear la segunda responde 409. Hasta 60 caracteres; se guardan sin espacios al borde.
• create() solo la registra en el catálogo: no se la pone a ningún contacto.
• rename() reescribe el nombre en todos los contactos que la tenían, para que no queden etiquetas huérfanas.
• delete() la borra del catálogo y se la quita a todos los contactos. No se puede deshacer.

Ponerle y quitarle etiquetas a un contacto

await met.contacts.addTag(4821, 'lead-caliente');
await met.contacts.removeTag(4821, 'frío');

const suyas = await met.contacts.tags(4821); // ['lead-caliente', 'Participante']

met.contacts.add_tag(4821, "lead-caliente")
met.contacts.remove_tag(4821, "frío")

suyas = met.contacts.tags(4821)

Ponerle a un contacto una etiqueta que no está en el catálogo la registra en el catálogo sola. Repetir una que ya tiene no hace nada.

A muchos contactos a la vez

Una etiqueta a una lista de contactos, en una sola llamada (hasta 500 por llamada):

const r = await met.contacts.bulkAddTags({ contact_ids: [4821, 4822, 4830], tag: 'Feria 2026' });
// { updated: 2, requested: 3, tag: 'Feria 2026' }

await met.contacts.bulkRemoveTags({ contact_ids: [4821, 4822], tag: 'Feria 2026' });

r = met.contacts.bulk_add_tags({"contact_ids": [4821, 4822, 4830], "tag": "Feria 2026"})
met.contacts.bulk_remove_tags({"contact_ids": [4821, 4822], "tag": "Feria 2026"})

updated cuenta solo los contactos que de verdad cambiaron: los que ya tenían la etiqueta, o los ids que no son contactos de este workspace, no suman. Va una etiqueta por llamada (tag, no una lista).

Filtrar por etiqueta

contacts.list() acepta condiciones sobre los campos del contacto en filters, un arreglo JSON. Para las etiquetas, el campo es $tags y los operadores son has y not_has:

const { data, total } = await met.contacts.list({
  filters: JSON.stringify([{ field: '$tags', op: 'has', value: 'lead-caliente' }]),
});

import json

pagina = met.contacts.list(filters=json.dumps([{"field": "$tags", "op": "has", "value": "lead-caliente"}]))

Una condición mal escrita se ignora en vez de dar error: revisa total antes de confiar en el filtro. Para saber qué etiquetas existen, sumando las del catálogo y las que tengan los contactos aunque no estén registradas, usa met.contacts.tagsDistinct().

Enterarte de los cambios

No hay un evento propio de etiquetas. Ponerle o quitarle una etiqueta a un contacto cambia el contacto, y eso sale como contact.updated (scope contacts:read; ver Webhooks).

Errores comunes