Skip to main content

​
Por que este canal importa

Sem uma base de contatos organizada, toda campanha vira planilha solta e todo envio vira “adivinha se esse e-mail é o mesmo WhatsApp”. A API de Contatos existe para você criar e manter pessoas no workspace — com telefone e/ou e-mail, tags e dados extras — e usar o mesmo registro no painel (segmentos, tópicos, campanhas) e na API (WhatsApp, templates, etc.).

​
O que você encontra no painel

Área do menuO que você faz ali
ContactsFicha da pessoa, tags, campos personalizados, importação por planilha.
AudienceTópicos (consentimento por tema), segmentos (públicos por regras) e campanhas (disparo em lote com template e audiência).
Em uma frase: contato é a pessoa; tudo o mais classifica, filtra ou envia em cima dessa base.

​
O que você encontra na API

  • CRUD de contatos — listar (com busca e filtro por tag), obter, criar, atualizar e excluir (/v1/contacts/...).
  • CRUD de tags — etiquetas reutilizáveis com contagem de uso (/v1/tags/...).
  • Regras de dados — telefone e e-mail são opcionais, mas pelo menos um é obrigatório; quando preenchidos, são únicos por workspace (evita duplicata óbvia).
  • Ligação com envio — por exemplo, cartão de contato no WhatsApp com POST /v1/whatsapp/messages, type: "contact" e payload.contactId.
Todas as rotas usam API Key e escopos contacts:* e tags:* conforme a operação.

​
Mapa mental rápido (sem confundir conceito)

  • Tag — etiqueta colada no contato (Cliente, Lead). Serve para filtro rápido e pode entrar em regras de segmento.
  • Campo personalizado — dado extra estruturado (cidade, plano) para segmentação e variáveis de mensagem.
  • Tópico — tema de marketing para o qual a pessoa aceita ou recusa e-mail/WhatsApp promocional (além do opt-in geral).
  • Segmento — filtro salvo (várias condições, AND/OR) usado em campanhas.
  • Campanha — amarra template, canais e público; usa o mesmo pipeline de cobrança e fila dos envios por API.
Guias mais profundos: Tópicos · Segmentos · Campanhas.

​
Autenticação e requisitos

  • Headers: Authorization: Bearer sk_live_xxxxx ou x-api-key: sk_live_xxxxx
  • Escopos típicos: contacts:read|create|update|delete e tags:read|create|update|delete
  • Workspace ativo (conta suspensa/expirada retorna 402).

​
Uso com WhatsApp

Para enviar a ficha de um contato como mensagem: POST /v1/whatsapp/messages com type: "contact" e payload.contactId (exige whatsapp:send). O destino to continua sendo o número/JID da conversa; o contato fornece os dados do cartão.

​
Próximos passos