Skip to main content
Familias principales: contacts, tags, topics, segments, campaigns, tasks. Las campañas también exigen alcances de envío por canal (whatsapp:send, sms:send, …).
Cada alcance desbloquea un tipo de operación en Contactos. Use solo lo que su integración necesita.

​
Cómo enviar la clave

Recomendado
Alternativo
Cada clave API pertenece a un espacio de trabajo. No puede acceder a otro espacio de trabajo con la misma clave.

​
Combinaciones comunes

Solo leer base

contacts:read, tags:read

Sincronizar CRM

contacts:read, contacts:create, contacts:update, tags:read, tags:create

Fila de tareas

tasks:read (lista del workspace) + contacts:update (crear/editar en el contacto)

Campañas vía API

campaigns:read, campaigns:create, campaigns:run + alcances de envío de los canales

Gestión completa

Todos los contacts:*, tags:*, topics:*, segments:*, campaigns:*
Lista de alcances vacía al crear = acceso ADMIN (todo). En producción, restrinja siempre.

​
Contactos (contacts:*)

Listar y obtener contacto por ID.
Crear contacto (teléfono y/o correo obligatorio).
Editar ficha, etiquetas, campos y tareas CRM (POST/PATCH /v1/contacts/{id}/tasks).
Eliminar contacto.

​
Tareas (tasks:read)

Las tareas CRM aparecen en dos niveles: en el contacto y vista del workspace.
GET /v1/tasks — lista paginada del workspace (status, overdueOnly, assignedUserId). Por defecto: tareas OPEN.
Crear y editar tareas usan alcance contacts:update (POST y PATCH en /v1/contacts/{id}/tasks). Listar tareas de un contacto usa contacts:read. No existe DELETE en API v1 — use PATCH con status: CANCELLED para cancelar.

​
Etiquetas (tags:*)

Listar y obtener etiqueta.
Crear etiqueta reutilizable.
Renombrar etiqueta.
Eliminar etiqueta.

​
Temas (topics:*)

Consentimiento por tema de marketing (Newsletter, Promociones). Igual que en el panel en Audience → Topics.
Listar y obtener tema.
Crear tema con slug estable.
Editar nombre, descripción y opt-in predeterminado.
Eliminar tema.

​
Segmentos (segments:*)

Audiencias con reglas (etiquetas, campos, temas, marketing). Incluye preview antes de campañas.
Listar, obtener y preview (muestra paginada de la audiencia).
Crear segmento con JSON version: 1, match, rules.
Editar reglas del segmento.
Eliminar segmento.

​
Campañas (campaigns:*)

Listar, obtener, estadísticas y destinatarios por ejecución.
Crear campaña (opcionalmente con scheduledFor).
Editar campaña y cancelar (DRAFT/SCHEDULED → CANCELLED).
Eliminar campaña.
Disparar ahora (Run); encola envíos en los canales de la campaña.
Disparar una campaña exige campaigns:run y alcances de envío de cada canal (whatsapp:send, sms:send, email:send, telegram:send, push:send, rcs:send, instagram:send) cuando la cola procese mensajes.

​
Errores comunes

Verifique el alcance de la operación (Missing scope: contacts:read, etc.).
Plan vencido o suspendido (WORKSPACE_BLOCKED). Regularice en el panel.
Límites de temas/segmentos/campañas (PLAN_LIMIT_CRM, PLAN_LIMIT_TEMPLATES) o trial sin recarga. Código 403, no 402.
Teléfono o correo ya registrado en el espacio de trabajo.

​
Próximos pasos