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
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"}}]}'{"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 é
403plan_limit, mas o que coube foi gravado: leiaimported,updatedediscardedtambé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 porcursor(onextCursorvazio 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:
{"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.
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}'- A criação gera um rascunho.
POST /campaigns/<id>/previewcom{"contactId": "<id>"}mostra o texto final e o tamanho do público. POST /campaigns/<id>/startcongela o público e começa (ou agenda, sescheduledAtestiver preenchido).POST /campaigns/<id>/pause,/resumee/cancelcontrolam o envio.GET /campaigns/<id>/statsmostra quantos foram enviados, entregues, lidos e com falha, e o motivo de espera (outside_window,rate_limited,sender_offline,plan_limit,billing_blockedpara a conta suspensa eplan_downgradepara 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. GETePUT /api/v1/marketing/optout/keywordsleem e trocam as palavras.POST /api/v1/marketing/contacts/<id>/optoute/optinregistram 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.