Campanhas, automações e agentes

Campanhas, automações, agentes de IA e mensagens agendadas seguem as mesmas regras da tela: o que a API recusa, o app também recusaria.

Campanha de template em massa

1. Escolha o número (GET https://api.converzap.com/v1/channels) e um template aprovado (GET https://api.converzap.com/v1/templates?status=approved).
2. Crie o rascunho — nada é enviado ainda:

curl -X POST https://api.converzap.com/v1/campaigns \
  -H "Authorization: Bearer czk_live_SUA_CHAVE" \
  -H "Idempotency-Key: campanha-black-friday-1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday",
    "channel": "123456789012345",
    "template_id": "UUID_DO_TEMPLATE",
    "variables": { "body:1": { "kind": "field", "field": "first_name", "fallback": "cliente" } },
    "audience": { "labels": ["cliente"], "exclude_labels": ["inativo"] },
    "rate_per_minute": 60
  }'

1. Inicie: POST https://api.converzap.com/v1/campaigns/{id}/start. Com scheduled_at no futuro ela fica scheduled; senão vai para sending.
2. Acompanhe em GET https://api.converzap.com/v1/campaigns/{id} (stats: enviadas, entregues, lidas, falhas, puladas) e controle com pause, resume e cancel.

Variáveis: cada variável do template (body:1, body:nome, header:1, button:0) recebe um campo do contato (first_name, name, company, city, uf, email, phone — e, da empresa do contato vinda do enriquecimento, razao_social, cnpj, endereco_empresa e socios, até 3), um campo personalizado ({"kind": "custom", "key": "plano"}) ou um texto fixo ({"kind": "text", "value": "BF10"}). Contato sem valor e sem fallback é pulado (não vira erro da Meta).

Público: all, list_ids, labels, segment_ids e as exclusões exclude_labels / exclude_segment_ids. Quem pediu para sair, telefone fixo e contato sem telefone nunca entram.

Erros comuns: 402 limit_reached (limite mensal de contatos do plano ou número fora do plano), 409 conflict (ação que não vale no estado atual, ex.: iniciar uma campanha que já começou), 400 invalid_request com errors[] listando o que falta para iniciar.

Automações (jornadas)

As automações são montadas no app; pela API você lista e inscreve contatos:

curl -X POST https://api.converzap.com/v1/automations/{id}/enrollments \
  -H "Authorization: Bearer czk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "contact_id": "UUID_DO_CONTATO" }'

• A automação precisa estar active (senão 409).
• Cada contato passa uma vez por automação: inscrever de novo devolve 409.
• DELETE https://api.converzap.com/v1/automations/{id}/enrollments/{contact_id} encerra a jornada (stopped).
• Dica: para disparar uma jornada a partir do seu sistema, crie a automação com gatilho manual e inscreva pela API.

Agentes de IA

• GET https://api.converzap.com/v1/agents lista os agentes (status draft, active, paused).
• POST https://api.converzap.com/v1/agents/{id}/activate liga o agente; com {"channel": "<phone_number_id>"} liga neste número. O checklist de ativação, o limite de agentes ativos e "um agente por número" valem como na tela.
• POST https://api.converzap.com/v1/agents/{id}/pause para as respostas.
• Para assumir ou devolver UMA conversa ao agente, use POST https://api.converzap.com/v1/conversations/{id}/ai-agent.

Mensagens agendadas

POST https://api.converzap.com/v1/conversations/{id}/scheduled-messages com send_at (de 1 minuto a 30 dias) e text ou template (id ou name + language, com params como no envio). Texto só se a janela de 24 h ainda estiver aberta no horário escolhido (senão 409 outside_24h_window). Com cancel_if_replied (padrão), a mensagem não sai se o contato escrever antes. Cancelar: DELETE https://api.converzap.com/v1/scheduled-messages/{id}.

Postman e Insomnia

1. No Postman: Import → Link e cole https://api.converzap.com/v1/openapi.json (para descrições em inglês, ?lang=en).
2. Na coleção criada, aba Authorization → Bearer Token com a sua chave (de preferência numa variável de ambiente, nunca no código).
3. A baseUrl já vem como https://api.converzap.com/v1.

No Insomnia: Create → Import → From URL com o mesmo endereço. Reimporte quando o changelog anunciar uma versão nova.