# Campanhas, automações e agentes

> Disparo em massa, inscrição em jornadas, agentes de IA, mensagens agendadas e Postman.

Fonte: https://developers.converzap.com/pt/campanhas-e-automacoes

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:

```bash
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
  }'
```

3. Inicie: `POST https://api.converzap.com/v1/campaigns/{id}/start`. Com `scheduled_at` no futuro ela fica `scheduled`; senão vai para `sending`.
4. 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**:

```bash
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](https://developers.converzap.com/pt/changelog) anunciar uma versão nova.