Mensagens ativas e campanhas pela API

Rotas

Passo a passo: disparo imediato

1. Pegue o id do canal e o id do modelo. Os modelos estão em Consultar cadastros.
2. Envie o disparo, com contatos por contactId ou phone:

curl -s -X POST https://http.pipebr.app/v1/messages-active \
  -H "Authorization: Bearer $PIPE_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "b3a1c9de-0000-4000-8000-000000000700",
    "template_id": "b3a1c9de-0000-4000-8000-000000000400",
    "queueId": "b3a1c9de-0000-4000-8000-000000000001",
    "contacts": [
      { "phone": "+5511955550101", "name": "Maria Exemplo", "parametros": ["Maria", "1234"] },
      { "contactId": "b3a1c9de-0000-4000-8000-000000000011", "parametros": ["João", "1235"] }
    ]
  }'

1. A resposta é 201, com um resultado por contato. Um contato recusado não impede os outros:

{
  "enviadas": 1,
  "recusadas": 1,
  "data": [
    {
      "telefone": "+5511955550101",
      "contato_id": "b3a1c9de-0000-4000-8000-000000000010",
      "enviada": true,
      "mensagem_id": "b3a1c9de-0000-4000-8000-000000000201",
      "conversa_id": "b3a1c9de-0000-4000-8000-000000000100",
      "motivo": null,
      "detalhe": null,
      "codigo_blip": null
    },
    {
      "telefone": "+5511955550102",
      "contato_id": "b3a1c9de-0000-4000-8000-000000000011",
      "enviada": false,
      "mensagem_id": null,
      "conversa_id": null,
      "motivo": "ja_em_atendimento",
      "detalhe": null,
      "codigo_blip": 1602
    }
  ]
}

Motivos de recusa por contato: numero_invalido, ja_em_atendimento, limite_diario, contact_duplicated e atendente_indisponivel. O limite diário por contato vem desligado (0) por padrão. Consulte GET /v1/messages-active/limits para ver maxContactsByTrigger e dailyLimitByContact.

Passo a passo: campanha

1. Confira o ritmo e o teto de destinatários em GET /v1/campaigns/limits e a saúde do número em GET /v1/campaigns/number-quality?channelId=.... Qualidade baixa deixa apto: false.
2. Crie a campanha:

curl -s -X POST https://http.pipebr.app/v1/campaigns \
  -H "Authorization: Bearer $PIPE_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Aviso de reposição",
    "channelId": "b3a1c9de-0000-4000-8000-000000000700",
    "templateId": "b3a1c9de-0000-4000-8000-000000000400",
    "modo": "massa",
    "tags": ["reposicao"],
    "agendadaPara": "2026-10-15T13:00:00.000Z",
    "destinoResposta": { "tipo": "atendente", "atendenteId": "b3a1c9de-0000-4000-8000-000000000020" },
    "destinatarios": [
      { "telefone": "+5511955550101", "nome": "Maria Exemplo", "parametros": ["Maria", "1234"] },
      { "telefone": "+5511955550102", "nome": "João Exemplo", "parametros": ["João", "1235"] }
    ]
  }'

1. A resposta é 201, com a campanha e duplicados (telefones repetidos que foram ignorados):

{
  "id": "b3a1c9de-0000-4000-8000-000000000800",
  "nome": "Aviso de reposição",
  "canal_id": "b3a1c9de-0000-4000-8000-000000000700",
  "template_id": "b3a1c9de-0000-4000-8000-000000000400",
  "modo": "massa",
  "estado": "agendada",
  "agendada_para": "2026-10-15T13:00:00.000Z",
  "contadores": { "audiencia": 2, "erros": 0, "enviadas": 0, "entregues": 0, "lidas": 0, "pendentes": 2 },
  "duplicados": 0
}

1. Acompanhe com GET /v1/campaigns/:id. O detalhe traz destinatarios paginados, que aceitam estado (pendente, enviando, enviada, recusada ou falhou), pagina e porPagina.
2. Para parar, POST /v1/campaigns/:id/cancel. O que já saiu fica; o resto permanece pendente.

Regras da campanha:

• modo: massa (padrão) ou individual, que exige exatamente um destinatário.
• Até 5000 destinatários por campanha. Telefones inválidos recusam a campanha inteira e a resposta lista as linhas com problema.
• Todo destinatário precisa ter os valores de todas as variáveis do modelo.
• agendadaPara pode ser até 90 dias à frente. Data no passado significa enviar já.
• Até 10 tags, com até 50 caracteres cada.
• Estados da campanha: rascunho, agendada, enviando, concluida, cancelada e falhou.