Skip to main content
Famílias principais: contacts, tags, topics, segments, campaigns, tasks. Campanha também exige escopos de envio dos canais (whatsapp:send, sms:send, …).
Cada escopo libera um tipo de operação em Contatos. Use só o que sua integração precisa.

​
Como enviar a chave

Recomendado
Alternativo
A API Key pertence a um workspace. Você não acessa outro workspace com a mesma chave.

​
Combinações comuns

Só ler base

contacts:read, tags:read

Sincronizar CRM

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

Fila de tarefas

tasks:read (lista do workspace) + contacts:update (criar/editar no contato)

Campanhas pela API

campaigns:read, campaigns:create, campaigns:run + escopos de envio dos canais

Gestão completa

Todos os contacts:*, tags:*, topics:*, segments:*, campaigns:*
Lista de escopos vazia na criação = acesso ADMIN. Em produção, restrinja sempre.

​
Contatos (contacts:*)

Listar e buscar contato por ID.
Criar contato (telefone e/ou e-mail obrigatório).
Editar ficha, tags, campos e tarefas CRM (POST/PATCH /v1/contacts/{id}/tasks).
Excluir contato.

​
Tarefas (tasks:read)

Tarefas CRM aparecem em dois níveis: no contato e visão do workspace.
GET /v1/tasks — lista paginada do workspace (status, overdueOnly, assignedUserId). Padrão: tarefas OPEN.
Criar e editar tarefas usam escopo contacts:update (POST e PATCH em /v1/contacts/{id}/tasks). Listar tarefas de um contato usa contacts:read. Não existe DELETE na API v1 — use PATCH com status: CANCELLED para cancelar.

​
Tags (tags:*)

Listar e buscar tag.
Criar etiqueta reutilizável.
Renomear tag.
Excluir tag.

​
Tópicos (topics:*)

Consentimento por tema de marketing (Newsletter, Promoções). Igual ao painel em Audience → Topics.
Listar e buscar tópico.
Criar tópico com slug estável.
Editar nome, descrição e opt-in padrão.
Excluir tópico.

​
Segmentos (segments:*)

Públicos com regras (tags, campos, tópicos, marketing). Inclui preview antes de campanhas.
Listar, buscar e preview (amostra paginada do público).
Criar segmento com JSON version: 1, match, rules.
Editar regras do segmento.
Excluir segmento.

​
Campanhas (campaigns:*)

Listar, buscar, estatísticas e destinatários por execução.
Criar campanha (opcionalmente com scheduledFor).
Editar campanha e cancelar (DRAFT/SCHEDULED → CANCELLED).
Excluir campanha.
Disparar agora (Run), enfileira envios nos canais da campanha.
Disparar campanha exige campaigns:run e escopos de envio de cada canal (whatsapp:send, sms:send, email:send, telegram:send, push:send, rcs:send, instagram:send) quando a fila processar mensagens.

​
Erros comuns

Verifique escopo da operação (Missing scope: contacts:read, etc.).
Plano expirado ou suspenso (WORKSPACE_BLOCKED). Regularize no painel.
Limite de tópicos/segmentos/campanhas (PLAN_LIMIT_CRM, PLAN_LIMIT_TEMPLATES) ou trial sem recarga. Código 403, não 402.
Telefone ou e-mail já cadastrado no workspace.

​
Próximos passos