API de Disparos

Listar contatos

Contatos da conta em páginas (?pagina=, ?por_pagina= até 200), com o filtro da tela: ?busca= (nome, telefone ou e-mail), ?tags=a,b (com qualquer uma), ?tags_excluir= e ?situacao= (pode_receber, sem_whatsapp, pediu_sair ou bloqueado).

Criar ou mesclar um contato

Cria o contato ou, com um telefone que já existe, mescla: as tags se somam, os campos personalizados se juntam por chave, nome e e-mail novos substituem os antigos e campo vazio nunca apaga. Bloqueio e pedido de saída nunca mudam por aqui. Telefone sem DDI recebe o 55 (ddi_padrao muda isso).

{
  "telefone": "5511999990000",
  "nome": "Ana Souza",
  "email": "ana@exemplo.com",
  "tags": ["clientes"],
  "campos_personalizados": { "cidade": "Campinas" }
}

Criar ou mesclar em lote

Até 1.000 contatos por chamada (contatos), com as mesmas regras. Cada um volta com a situação (criado, atualizado, sem_alteracao ou recusado) e o motivo. Pesa 1 chamada a cada 10 contatos no limite por minuto.

{ "contatos": [{ "telefone": "5511999990000", "nome": "Ana Souza", "tags": ["clientes"] }] }

Um contato

Dados, tags, campos personalizados, situação e o bloqueio com o motivo (ctt_...).

Mudar um contato

Muda nome, telefone (a conferência do WhatsApp recomeça), email, tags (a lista inteira, que substitui a atual) e campos_personalizados. Bloquear e desbloquear têm endereço próprio.

{ "tags": ["clientes", "vip"] }

Apagar um contato

Apaga o contato. O histórico de envios das campanhas continua, sem o vínculo com ele.

Bloquear

A pessoa deixa de receber campanhas e automações da conta. Quem pediu para sair continua com esse motivo.

Desbloquear

Tira o bloqueio, inclusive o de quem pediu para sair. A decisão é do dono da conta.

Tags

As tags da conta com quantos contatos têm cada uma, e o total de contatos.

Listar campanhas

A que está rodando primeiro, depois a mais nova. ?filtro= (todas, andamento, interrompidas, concluidas, rascunhos ou arquivadas), ?busca= pelo nome, ?pagina= e ?por_pagina= (até 100), com a contagem de cada filtro.

Criar rascunho

Cria a campanha como rascunho, com as regras da tela: números da conta e dentro do plano, horário no mesmo dia e teto que os números dão conta de cumprir. modo é seguro (padrão) ou intenso, com cadencia_intenso (intervalo_mensagens_segundos, intervalo_lotes_segundos). Exige o cabeçalho Idempotency-Key: a mesma chave devolve a mesma campanha.

Aceita simular; criar exige Idempotency-Key.

{
  "nome": "Promoção de novembro",
  "modo": "seguro",
  "mensagem": { "tipo": "texto", "texto": "{{Oi/Olá}} {{primeiro_nome}}, a promoção começa hoje", "tem_optout": true },
  "tags_incluir": ["clientes"],
  "tags_excluir": ["pediu-pausa"],
  "numeros": ["num_..."],
  "horario": { "inicio": "08:00", "fim": "20:00", "dias_semana": [1, 2, 3, 4, 5] },
  "teto_diario": 200
}

Uma campanha

A mensagem (com a versao), as tags do público, os números, o horário, o teto e os contadores (dsp_...).

Mudar rascunho

Muda um rascunho ou uma campanha agendada, com os mesmos campos da criação. Campanha rodando muda por /ajustar (teto, números, horário) e por /mensagem (o texto).

Simular

Antes de disparar: quantas pessoas recebem, em quantos dias termina, quantas por dia, se os números dão conta do teto no horário, o risco e o que impediria o disparo agora (pronta e impedimentos). Não grava nada e aceita chave de leitura.

Disparar ou agendar

Sem agendar_para, começa agora; com ele (ISO 8601, até 90 dias), agenda. Passa pelas travas da tela: mensagem pronta, público, números da conta, horário, teto, cota do mês e plano. Agendar de novo uma campanha agendada só troca a data.

{ "agendar_para": "2026-11-10T09:00:00-03:00" }

Pausar

Cancela o que está na fila e deixa a campanha interrompida, pronta para /retomar. Vale para campanha agendada ou rodando.

Retomar

Retoma uma campanha interrompida ou pausada de onde parou: quem já recebeu não recebe de novo. numeros escolhe os números; sem ele, ficam os da campanha.

{ "numeros": ["num_...", "num_..."] }

Ajustar campanha rodando

Muda teto_diario, numeros e horario (inicio e fim) de uma campanha em andamento. A fila é refeita a partir de agora, e quem já recebeu ou está recebendo não recebe de novo.

{ "teto_diario": 150, "horario": { "inicio": "09:00", "fim": "18:00" } }

Editar o texto com a campanha rodando

Troca o texto (ou a legenda) de uma campanha em andamento ou pausada; vale para quem ainda não recebeu. Exige a versao da mensagem que você leu: se outra edição entrou antes, a resposta é 409 conflito. Variável que não existe nos contatos volta como aviso, com 409 confirmar_avisos; para aplicar assim mesmo, mande confirmar_avisos: true.

{ "texto": "{{Oi/Olá}} {{primeiro_nome}}, a promoção vai até sexta", "versao": 2 }

Relatório

Total, enviados, erros, interrompidos, pendentes e o percentual, o resultado por número e se algum número teve restrição do WhatsApp durante a campanha (com ela, parte dos enviados pode não ter chegado a quem nunca falou com o número).

Envios pessoa a pessoa

Do mais novo ao mais antigo. ?situacao= (pendente, enviado, erro ou abortado), ?pagina= e ?por_pagina= (até 200).

Listar automações

As automações da conta, com a situação (ligada ou pausada, com o motivo), as regras, o movimento de hoje e dos 7 dias e se a fila está atrasada.

Uma automação

A mensagem, as variáveis que cada evento precisa trazer, os números, o horário, o teto por dia, a validade, a prioridade e o movimento (aut_...).

Pausar ou retomar

Pausar para os envios; quem chegar enquanto isso espera na fila até a validade. Retomar religa com as mesmas travas da tela (mensagem pronta, números, plano e cota).

Ações: pausar, retomar

Pausar todas

Pausa todas as automações ligadas da conta de uma vez, para uma emergência.

Colocar pessoas na fila

Um evento (telefone, nome, variaveis, identificador) ou um lote (eventos, até 500). O identificador (o número do pedido, por exemplo) torna o pedido repetível: o mesmo identificador devolve o mesmo evento, e a pessoa recebe uma mensagem só. Num evento sozinho sem identificador, vale o cabeçalho Idempotency-Key. enviar_a_partir_de adia o envio (até 60 dias) e validade_ate diz até quando a mensagem ainda vale para essa pessoa, no lugar da validade da automação. Quem não entra (telefone inválido, variável obrigatória faltando, pediu para sair, repetição, cota) volta como descartado, com o motivo. Até 20 eventos, a resposta traz a previsão de envio de cada um. O lote pesa 1 chamada a cada 10 eventos no limite por minuto.

{
  "telefone": "5511999990000",
  "nome": "Ana Souza",
  "identificador": "pedido-88231",
  "variaveis": { "produto": "Tênis Corrida", "link": "https://loja.exemplo.com/c/88231" }
}

Histórico

Os eventos da automação, do mais novo ao mais antigo, com a contagem por situação. ?situacao= (aguardando, agendado, enviando, enviado, falhou, expirado, descartado ou cancelado), ?de= e ?ate= (ISO 8601), ?limite= (até 200) e ?cursor= com o proximo da página anterior.

Cancelar pelo identificador

?identificador=pedido-88231: cancela o evento antes de sair. Serve para quando o motivo da mensagem deixou de existir (a compra foi paga, o carrinho foi concluído). Evento que já saiu ou está saindo não pode ser cancelado.

Fila

Quem está na fila, com a previsão de envio de cada um e quem não cabe na validade com as regras de hoje (vao_expirar). Até 1.000 pessoas, com o total.

Um evento

A situação, o motivo, o número que mandou e os horários de um evento (evt_...).

Cancelar um evento

Cancela o evento antes de sair. Evento que já saiu ou está saindo agora não pode ser cancelado (409 conflito).

Uso do mês

Mensagens do mês (campanhas e automações somadas) contra a cota do plano (limite nulo é sem limite) e os disparos de cada número nos últimos 30 dias.

Subir um arquivo

Devolve um upload_url (suba o arquivo com PUT e o mesmo Content-Type) e o url_publica, que vai em mensagem.midia_url. Imagem (JPEG, PNG, GIF, WEBP), vídeo MP4, áudio (MP3, OGG, M4A), PDF, DOCX ou XLSX, até 50 MB.

{ "nome_arquivo": "catalogo.pdf", "tipo_mime": "application/pdf", "tamanho_bytes": 2400000 }

Listar

Os webhooks da conta com o resumo das últimas 24 horas. O segredo nunca volta aqui.

Criar

url https pública, eventos e descricao opcional. A resposta é a única vez em que o segredo aparece. Até 5 por conta, e o dono é avisado no painel.

{ "url": "https://seu-sistema.com/protectzap", "eventos": ["disparos.evento.enviado", "disparos.evento.descartado"] }

Um webhook

Endereço, avisos pedidos, situação e as falhas recentes (whk_...).

Mudar

Muda url, eventos, descricao ou ativo. Religar entrega o que ficou na fila.

Apagar

Apaga o webhook e o histórico de entregas dele.

Entregas

Os últimos avisos (até 200, 30 dias de histórico) com a situação e a resposta de cada um.

Testar

Manda um webhook.teste agora e devolve o que o endereço respondeu.

Trocar o segredo

Gera um segredo novo; o antigo deixa de valer na hora. A resposta é a única vez em que ele aparece.

Reenviar um aviso

Manda de novo um aviso (whe_...) com o mesmo id, para o seu sistema descartar se já recebeu.

Catálogo

Os avisos do Disparos que um webhook pode pedir.

Uso do mês contra a cota do plano, campanhas rodando ou agendadas, automações (ligadas, pausadas com o motivo e com a fila atrasada) e os números com os disparos dos últimos 30 dias.

Campanhas da conta, a que está rodando primeiro, com situação, público, enviados, erros e a contagem de cada filtro. Use os ids dsp_ daqui em disparos_relatorio e disparos_planejar_pausa.

Parâmetros: filtro, busca, pagina

Resultado de uma campanha: total, enviados, erros, interrompidos, pendentes e o percentual, o resultado por número e se algum número teve restrição do WhatsApp durante a campanha.

Parâmetros: campanha

Automações da conta com a situação (ligada ou pausada e o motivo), as regras, o movimento de hoje e dos 7 dias e se a fila está atrasada (pessoas que não cabem na validade com as regras de hoje). Use os ids aut_ daqui em disparos_fila e disparos_planejar_eventos.

Quem está na fila de uma automação, com a previsão de envio de cada um e quem não cabe na validade. As pessoas aparecem só com o final do telefone.

Parâmetros: automacao, limite

Busca nos contatos da conta por nome, telefone ou e-mail, por tag e pela situação (pode receber, sem WhatsApp, pediu para sair, bloqueado). Devolve o total e até 50 contatos, com o final do telefone.

Parâmetros: busca, tags, situacao, pagina

Confere uma campanha nova com as mesmas regras da tela (números da conta e do plano, horário, teto diário, mensagem pronta, público pelas tags, cota do mês) e mostra o público, a duração prevista, o ritmo por dia e o risco. Nada é criado: devolve um codigo_confirmacao (15 min) e só confirmar cria e dispara (ou agenda, com agendar_para).

Parâmetros: nome, modo, mensagem, tags_incluir, tags_excluir, numeros, horario, teto_diario, agendar_para

Confere quem entraria na fila de uma automação (até 100 pessoas por vez) com as mesmas regras da API: telefone, variáveis obrigatórias, repetição, pedido de saída, bloqueio e cota. Mostra quantas entram e quem fica de fora com o motivo. Nada é gravado: devolve o código, e só confirmar coloca na fila.

Parâmetros: automacao, pessoas

Planeja pausar uma campanha que está rodando ou agendada, uma automação ligada ou todas as automações da conta de uma vez. Informe só um alvo. Devolve o código para confirmar. Retomar volta a enviar e é feito pela tela ou pela API.

Parâmetros: campanha, automacao, todas_automacoes