Skip to Content
1MSG
Reference

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.templateName e content.language (por exemplo, en).

Para templates:

  • content.params usa o mesmo formato de sendTemplate e é 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 de params, 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. action pode ser segment_updated, segment_deleted, member_added, member_updated, member_deleted ou members_replaced. O payload não identifica qual membro mudou.
  • campaign.created — um rascunho de campanha foi criado. scheduledAt traz o horário agendado do envio ou null.
  • campaign.updated — um rascunho de campanha foi atualizado. scheduledAt traz o horário agendado do envio ou null.
  • campaign.status_changed — o status da campanha mudou para draft, sending, pause, completed, failed ou scheduled. scheduledAt traz o horário agendado do envio ou null.

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.

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.