Campaigns API
A Campaigns API permite enviar uma mensagem para vários destinatários. Por padrão, um segmento pode ter até 500 pessoas. Para aumentar o limite para 10.000, fale com a gente em [email protected]. Os métodos do Inbox não estão neste documento.
Use os grupos da API nesta ordem: Segments → Campaigns → Analytics.
1. Segmentos
Crie um segmento e adicione membros. Cada membro precisa de name e de pelo menos um entre phone e bsuid.
2. Campanhas
Crie um rascunho com um channelId que a chave de API pode acessar e o segmentId do passo anterior.
Defina content.mode como text ou template:
- Texto: informe
content.text. - Template: informe
content.templateNameecontent.language(por exemplo,en).
Para templates:
content.paramsusa o mesmo formato desendTemplatee é repassado à WABA sem mudanças, com suporte a imagens no cabeçalho, variáveis no corpo, botões e cards de carrossel.content.messageSendTtlSecondsé opcional e define, em segundos, por quanto tempo o WhatsApp tenta entregar a mensagem. Ele fica ao lado deparams, não dentro dos componentes do template.
Pré-visualize o rascunho antes de enviar.
Para agendar uma campanha, defina scheduledAt com um instante futuro em ISO 8601 com Z ou deslocamento numérico, por exemplo 2026-11-01T09:00:00Z. Para começar o envio na hora, não envie o campo ou defina null.
Não existe configuração de quantidade de mensagens por dia. Os envios de template usam o limite do canal, retornado em dailyLimit. Mensagens de texto da sessão enviadas dentro de uma janela de 24 horas aberta não contam para esse limite.
3. Análise
Depois do envio, consulte a análise para acompanhar o resultado da campanha:
- Estatísticas gerais: total de mensagens enviadas, entregues, lidas e respondidas.
- Estatísticas por destinatário: quando cada mensagem foi enviada, entregue e lida, quando o destinatário respondeu e o que respondeu, incluindo toques em botões e mensagens de texto livre.
- Estatísticas de botões: quem tocou em cada botão e quando.
- Estatísticas de erros: quais destinatários tiveram erros e o erro de cada número.
4. Webhooks de campanhas
A 1MSG envia eventos de webhook para a URL HTTPS configurada quando segmentos ou campanhas são criados ou atualizados e quando o status de uma campanha muda.
Configure os webhooks em Settings → Developer → Webhooks.
Eventos
segment.created— um segmento foi criado.actionésegment_created.segment.updated— um segmento ou os membros dele mudaram.actionpode sersegment_updated,segment_deleted,member_added,member_updated,member_deletedoumembers_replaced. O payload não identifica qual membro mudou.campaign.created— um rascunho de campanha foi criado.scheduledAttraz o horário agendado do envio ounull.campaign.updated— um rascunho de campanha foi atualizado.scheduledAttraz o horário agendado do envio ounull.campaign.status_changed— o status da campanha mudou paradraft,sending,pause,completed,failedouscheduled.scheduledAttraz o horário agendado do envio ounull.
Autorização
A chave precisa ter o escopo Campaigns. Gere a chave em Settings → Developer → API key.
Authorization: Bearer 1msg_live_…Segments
Crie um segmento e depois adicione pessoas. Cada membro precisa de um nome e de um telefone em E.164 ou de um BSUID.
Campaigns
Crie um rascunho, defina o template ou o texto, pré-visualize e depois envie ou agende. O limite diário de templates é o limite do canal, não um campo da campanha.
- Listar campanhas GET
- Criar um rascunho de campanha POST
- Pré-visualizar uma campanha GET
- Enviar ou agendar uma campanha POST
- Mudar o horário agendado PATCH
- Voltar uma campanha agendada para rascunho POST
- Pausar uma campanha em envio POST
- Retomar uma campanha pausada POST
- Concluir uma campanha POST
- Enviar um teste POST
- Ver uma campanha GET
- Atualizar um rascunho de campanha PATCH
Analytics
Leia o snapshot do envio: quem foi alcançado, o que respondeu e por que um envio falhou. conversationId é a conversa no Inbox. providerConversationId é o id do chat no provedor. messageId e providerMessageId são o mesmo id da mensagem no provedor.
