Ir para o conteúdo

Marketing

Importar contatos, organizar em listas, enviar campanhas e respeitar o opt-out.

As rotas de /api/v1/marketing abrem com uma chave de API (wck_...) com o escopo Marketing: crie uma na área do cliente, em API > Chaves de API (veja Começar). A chave de um número ou de um cluster não abre essas rotas. As mesmas regras valem na área do cliente, em Marketing. O plano precisa incluir Marketing, senão a resposta é 403 plan_feature_disabled.

Uma chave restrita a alguns números só vê as campanhas que enviam por esses números: as outras ficam fora das listas e respondem 404. Criar ou iniciar uma campanha com remetente fora da chave responde 403 SENDER_NOT_ALLOWED. Contatos, listas e opt-out são da conta inteira.

Importar contatos

bash
curl -X POST "$API_URL/api/v1/marketing/contacts/import" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"defaultCountry": "55", "tags": ["clientes"], "rows": [{"phone": "+55 (11) 98765-4321", "name": "Ana", "fields": {"cidade": "Recife"}}]}'
json
{"imported": 1, "updated": 0, "discarded": [{"row": 2, "reason": "duplicate_in_file"}]}
  • Até 5.000 linhas e 8 MiB por chamada. Para um arquivo grande, mande em lotes.
  • O telefone é a identidade do contato: importar de novo atualiza o contato, não duplica. Nome e campos enviados substituem os anteriores, e as listas (tags) são somadas.
  • Linhas inválidas são descartadas com o motivo (invalid_length, invalid_ddd, invalid_characters, duplicate_in_file...), sem impedir as outras.
  • No limite de contatos do plano, a resposta é 403 plan_limit, mas o que coube foi gravado: leia imported, updated e discarded também nesse caso.
  • Importar nunca desfaz um opt-out.

Consultar e organizar

  • GET /api/v1/marketing/contacts?tag=clientes&q=ana&limit=100: lista com paginação por cursor (o nextCursor vazio indica o fim).
  • PATCH /api/v1/marketing/contacts/<id>: muda nome e campos.
  • DELETE /api/v1/marketing/contacts/<id>: apaga o contato e o consentimento dele.
  • GET /api/v1/marketing/tags: listas, com a contagem de cada uma.
  • POST /api/v1/marketing/contacts/tags: põe e tira listas de vários contatos de uma vez:
json
{"filter": {"tag": "evento"}, "add": ["vip"], "remove": ["antigos"]}

Campanhas

Uma campanha manda uma mensagem para uma ou mais listas, no ritmo e na janela de horário que você escolhe.

bash
curl -X POST "$API_URL/api/v1/marketing/campaigns" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Lançamento", "sender": {"instanceIds": ["<id do número>"]}, "audience": {"tags": ["clientes"]}, "message": {"type": "text", "text": "Olá {{nome}}! Novidade em {{cidade}}."}, "defaults": {"cidade": "sua cidade"}, "timezone": "America/Sao_Paulo", "window": {"start": "08:00", "end": "20:00"}, "ratePerMinute": 6, "scheduledAt": null}'
  1. A criação gera um rascunho. POST /campaigns/<id>/preview com {"contactId": "<id>"} mostra o texto final e o tamanho do público.
  2. POST /campaigns/<id>/start congela o público e começa (ou agenda, se scheduledAt estiver preenchido).
  3. POST /campaigns/<id>/pause, /resume e /cancel controlam o envio.
  4. GET /campaigns/<id>/stats mostra quantos foram enviados, entregues, lidos e com falha, e o motivo de espera (outside_window, rate_limited, sender_offline, plan_limit, billing_blocked para a conta suspensa e plan_downgrade para a campanha pausada porque o plano baixou, que volta quando o plano sobe).

{{nome}} usa o nome do contato, e as demais variáveis usam os campos dele, com o valor de defaults quando o campo está vazio.

Opt-out

Quem pede para sair não recebe mais campanhas nem fluxos.

  • A pessoa manda uma das palavras de saída (sair, parar, stop, cancelar, por padrão) e o opt-out é gravado sozinho. A comparação ignora maiúsculas e acentos e vale para a mensagem inteira ou a primeira palavra.
  • GET e PUT /api/v1/marketing/optout/keywords leem e trocam as palavras.
  • POST /api/v1/marketing/contacts/<id>/optout e /optin registram a escolha à mão.

O envio direto de mensagens (/instances/<id>/send) não consulta o opt-out: respeitar o pedido nesses envios é responsabilidade de quem chama.