Skip to main content

​
O fluxo principal (visão geral)

No painel (primeira vez): Tags e campos → importar ou cadastrar contatos → Topics (consentimento) → Segments → Campaigns. Na API: Criar tags → criar contatos (telefone e/ou e-mail) com tagIds → listar/filtrar → opcionalmente usar contactId no envio WhatsApp (type: contact). Abaixo o passo a passo detalhado nas duas frentes.

​
Pré-requisitos

No painel: acesso ao workspace no navegador (permissões de Contacts e Audience conforme seu perfil). Pela API:
  • API Key com escopos contacts:read/create/update/delete e tags:read/create/update/delete (conforme a operação).
  • Envie a API Key em toda requisição:
    • Header: Authorization: Bearer sk_live_xxxxx
    • ou Header: x-api-key: sk_live_xxxxx

​
1. No painel: da base à campanha

Siga esta ordem na primeira vez; depois você repete só o que mudar.

​
1.1 Contacts — tags e campos antes da massa de dados

  1. Abra Contacts.
  2. Em Tags, crie nomes que vai usar de verdade (ex.: Lead, Cliente). Tags são etiquetas; segmentos vêm depois e podem combinar tags com outras regras.
  3. Opcional: Custom fields — defina chave (ex.: cidade, plano_atual), rótulo e tipo (texto, número, sim/não, data). Esses valores entram em segmentos e em variáveis de mensagem quando o envio usa o contato.

​
1.2 Contacts — cadastrar e importar

  • Um contato: adicione pelo menos telefone ou e-mail (regra igual à API). Associe tags e preencha campos personalizados se já existirem.
  • Muitos contatos: use Import (CSV ou Excel). Colunas comuns (nome, telefone, e-mail, site) são reconhecidas; para campos extras, use cabeçalho igual à chave do campo. Defina se os números já têm DDI ou informe o país (ex.: 55). Cabeçalhos que não forem campo conhecido são ignorados — só entram custom fields já criados no workspace.

​
1.3 Audience — Topics (tópicos)

  1. Audience & campaigns → aba Topics.
  2. New (ou tecla N com a aba ativa): nome, slug estável, descrição opcional, opt-in padrão para novos contatos (use com critério em ofertas).
  3. Associe templates de marketing ao tópico certo para respeitar consentimento por tema.
Artigo longo: Tópicos e link de preferências.

​
1.4 Audience — Segments (segmentos)

  1. Aba Segments → New segment: nome e definição em JSON (versão 1), ou use os assistentes do painel quando disponíveis.
  2. Preview mostra total e amostra; confira antes de campanhas grandes.
Formato e exemplos: Segmentos na audiência · Blog: segmentos e JSON.

​
1.5 Audience — Campaigns (campanhas)

  1. Aba Campaigns: template, canais, público (segmento ou IDs de contato).
  2. Run quando estiver pronto — mesmo fluxo de filas e créditos dos envios pela API.
Guias: Campanhas no painel · Blog.

​
1.6 Preferências do contato

Na ficha do contato, gere o link de preferências (token temporário) para a pessoa ajustar marketing e tópicos. Em e-mail, use preferences_link no template quando suportado. Dicas na interface: na parte superior de Audience, há tooltips por aba; a tecla N costuma abrir o fluxo de criar novo conforme a aba ativa.

​
2. Pela API: criar tag

Crie uma tag para depois vincular a contatos (ex.: “Lead”, “Cliente”, “Newsletter”). O nome é único por workspace. Request 
POST /v1/tags
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Lead"
}
Response (200) 
{
  "success": true,
  "data": {
    "id": "clxxTag1",
    "name": "Lead",
    "contactsCount": 0,
    "createdAt": "2025-03-05T12:00:00.000Z",
    "updatedAt": "2025-03-05T12:00:00.000Z"
  }
}
Anote o id da tag para usar em tagIds ao criar/atualizar contatos.

​
3. Pela API: criar contato

É obrigatório informar pelo menos um de phone ou email (permite contatos só com e-mail ou só com telefone). Opcionalmente vincule a tags com tagIds. Request — com telefone e tags 
POST /v1/contacts
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "phone": "5511999999999",
  "name": "João Silva",
  "email": "joao@exemplo.com",
  "tagIds": ["clxxTag1"]
}
Request — só e-mail (ex.: newsletter) 
{
  "email": "joao@exemplo.com",
  "name": "João Silva",
  "tagIds": ["clxxTag1"]
}
Response (200) 
{
  "success": true,
  "data": {
    "id": "clxx123abc",
    "name": "João Silva",
    "phone": "5511999999999",
    "email": "joao@exemplo.com",
    "url": null,
    "createdAt": "2025-03-05T12:00:00.000Z",
    "updatedAt": "2025-03-05T12:00:00.000Z",
    "tags": [{ "id": "clxxTag1", "name": "Lead" }]
  }
}
Se já existir contato com o mesmo phone ou mesmo email no workspace, a API retorna 409 (CONTACT_PHONE_EXISTS ou CONTACT_EMAIL_EXISTS).

​
4. Pela API: listar contatos

Liste com paginação, busca e filtro por tag (tagId). Cada item inclui tags. Request 
GET /v1/contacts?page=1&limit=20&tagId=clxxTag1
Authorization: Bearer sk_live_xxxxx
Query opcionais: search (nome, telefone ou e-mail), tagId (apenas contatos que têm essa tag). Response (200) 
{
  "success": true,
  "data": [
    {
      "id": "clxx123abc",
      "name": "João Silva",
      "phone": "5511999999999",
      "email": "joao@exemplo.com",
      "url": null,
      "createdAt": "2025-03-05T12:00:00.000Z",
      "updatedAt": "2025-03-05T12:00:00.000Z",
      "tags": [{ "id": "clxxTag1", "name": "Lead" }]
    }
  ],
  "pagination": { "total": 1, "page": 1, "limit": 20, "totalPages": 1 }
}

​
5. Pela API: obter contato por ID

Request 
GET /v1/contacts/clxx123abc
Authorization: Bearer sk_live_xxxxx
Response (200) — inclui tags. 
{
  "success": true,
  "data": {
    "id": "clxx123abc",
    "name": "João Silva",
    "phone": "5511999999999",
    "email": "joao@exemplo.com",
    "url": null,
    "createdAt": "2025-03-05T12:00:00.000Z",
    "updatedAt": "2025-03-05T12:00:00.000Z",
    "tags": [{ "id": "clxxTag1", "name": "Lead" }]
  }
}

​
6. Pela API: atualizar contato

Atualize campos e/ou tags. Enviar tagIds substitui a lista de tags do contato. O contato deve continuar com pelo menos um de phone ou email. Request 
PUT /v1/contacts/clxx123abc
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "João Silva Santos",
  "tagIds": ["clxxTag1", "clxxTag2"]
}
Response (200) — inclui tags atualizadas.

​
7. Pela API: excluir contato

Request 
DELETE /v1/contacts/clxx123abc
Authorization: Bearer sk_live_xxxxx
Response (200) 
{
  "success": true,
  "message": "Contact deleted successfully"
}

​
8. Pela API: rotas de tags

MétodoRotaEscopoDescrição
GET/v1/tagstags:readListar tags (com contactsCount)
GET/v1/tags/:idtags:readObter tag
POST/v1/tagstags:createCriar tag (name único por workspace)
PUT/v1/tags/:idtags:updateAtualizar nome
DELETE/v1/tags/:idtags:deleteExcluir tag (desvincula de todos os contatos)

​
9. Enviar contato via WhatsApp (contactId)

POST /v1/whatsapp/messages com type: "contact" e payload.contactId. Requer whatsapp:send. 
{
  "instanceId": "clxx...",
  "to": ["5511888888888"],
  "type": "contact",
  "payload": { "contactId": "clxx123abc" }
}

​
Resumo das rotas de contatos

MétodoRotaEscopoDescrição
GET/v1/contactscontacts:readListar (page, limit, search, tagId)
GET/v1/contacts/:idcontacts:readObter contato
POST/v1/contactscontacts:createCriar (phone ou email obrigatório; tagIds opcional)
PUT/v1/contacts/:idcontacts:updateAtualizar (tagIds substitui tags)
DELETE/v1/contacts/:idcontacts:deleteExcluir

​
Referências

  • Conceitos e diferenças (contatos × tags × tópicos × segmentos): Introdução.
  • Tópicos, segmentos e campanhas (detalhe): Topics · Segments · Campaigns.
  • Escopos: Contatos (contacts:read/create/update/delete) e Tags (tags:read/create/update/delete).
  • 400 CONTACT_REQUIRES_PHONE_OR_EMAIL: É obrigatório enviar pelo menos um de phone ou email ao criar/atualizar.
  • 409 CONTACT_PHONE_EXISTS / CONTACT_EMAIL_EXISTS: Phone ou email já existe no workspace.
  • 409 TAG_NAME_EXISTS: Nome de tag já existe no workspace.