Mensagens em Massa / Campanhas

Visão Geral

O recurso de campanhas envia uma única mensagem de texto simples para muitos destinatários enquanto protege o SMSC de sobrecarga. Você faz o upload de uma lista de destinatários nomeada uma vez, e então executa uma ou mais campanhas contra ela. Cada campanha distribui mensagens na fila normal de mensagens a uma taxa configurável e relata o progresso ao vivo e estatísticas de entrega.

Dois objetos reutilizáveis:

Objeto	O que é
Lista de Campanha	Um conjunto nomeado e reutilizável de MSISDNs de destinatários, cada um com até quatro variáveis opcionais. Faça o upload uma vez (array JSON ou CSV), reutilize em campanhas.
Campanha	Uma execução de envio: uma lista (ou todos os assinantes ativos) + um modelo de mensagem, distribuído na fila.

Tudo está exposto através da API HTTP. Todo o estado é armazenado no Mnesia junto com o restante do SMSC.

Segmentação: listas e o padrão de assinante ativo

Os destinatários de uma campanha vêm de uma das duas fontes:

Uma lista de destinatários (list_id) - os MSISDNs que você fez o upload.
Nenhuma lista - se você criar uma campanha sem um list_id, ela tem como alvo todos os assinantes atualmente ativos (registrados) - cada MSISDN com um registro não expirado no armazenamento de localização no momento em que a campanha começa. Esta é a maneira mais fácil de alcançar "todos na rede agora".

Variáveis por destinatário e modelagem

Cada destinatário da lista pode carregar até quatro variáveis - var1, var2, var3, var4 - para coisas como primeiro nome, sobrenome ou nome do plano. A mensagem da campanha é um modelo: {{ var1 }}…{{ var4 }} (e {{ msisdn }}) são inseridos para cada destinatário quando a mensagem é enviada. O espaço em branco dentro das chaves é opcional, e qualquer marcador de posição sem valor é renderizado como uma string vazia.

A modelagem é deliberadamente mínima - substituição de variáveis apenas (sem condicionais ou filtros), então não há dependência extra e nenhuma surpresa no que os assinantes recebem.

Fazendo upload de variáveis via CSV - a coluna MSISDN é a nomeada msisdn/destination_msisdn/number/phone (ou a primeira coluna se nenhuma for nomeada); cada outra coluna se torna var1…var4 na ordem das colunas:

msisdn,first,last,plan
12025550101,Alice,Smith,Gold
12025550102,Bob,Jones,Silver

Fazendo upload de variáveis via JSON - objetos de destinatários podem definir as variáveis diretamente:

{ "name": "VIPs", "recipients": [
  { "msisdn": "12025550101", "var1": "Alice", "var2": "Gold" }
] }

Exemplo de modelo:

Oi {{ var1 }}, seu plano {{ var2 }} renova em breve. Responda STOP para cancelar.

Para o destinatário 12025550101 acima (var1=Alice, var2=Gold) isso envia: Oi Alice, seu plano Gold renova em breve. Responda STOP para cancelar.

Filtro de audiência

Quando uma campanha usa uma lista, a flag audience decide quem realmente recebe uma mensagem:

Audiência	Comportamento
`active_only` (padrão)	Apenas membros da lista que estão registrados (uma localização não expirada) no momento em que a campanha começa. Todos os outros são registrados como `skipped_inactive` e nunca recebem.
`all`	Todos os membros da lista, independentemente do registro.

A verificação de registro é um instantâneo tirado no momento de início - assinantes que se registram depois não são capturados. Quando uma campanha não tem lista, o conjunto de destinatários já é a base de assinantes ativos, então audience é implicitamente active_only e qualquer valor fornecido é ignorado.

Ciclo de Vida

draft - criado, sem alvos ainda.
start - a campanha tira um instantâneo de seus alvos (de sua lista ou da base de assinantes ativos), então passa para running. Se não há nada para enviar, ela vai direto para completed.
running - o trabalhador de distribuição envia mensagens para a fila.
pause / resume - parar temporariamente / continuar a distribuição.
completed - cada alvo foi distribuído na fila (a entrega continua assíncronamente, e as estatísticas de entrega continuam atualizando).
cancelled - parado permanentemente.

Deletando uma campanha

Deletar uma campanha a para, mas mantém o registro - ela é cancelada em vez de excluída, então seu histórico e estatísticas finais permanecem visíveis. Campanhas paradas e completadas são removidas automaticamente uma vez que envelhecem além do TTL de retenção (campaign_retention_hours, padrão 7 dias).

Taxa de Distribuição (proteção contra sobrecarga)

Cada campanha tem um drip_tps (mensagens enviadas para a fila por segundo, padrão da configuração). Um trabalhador em segundo plano acorda em um intervalo fixo e envia no máximo drip_tps × interval mensagens por campanha por tick - então uma campanha de um milhão de destinatários nunca inunda a fila. A taxa é por campanha; várias campanhas em execução distribuem a sua própria taxa.

Progresso e estatísticas de entrega

Cada objeto de campanha inclui um bloco stats ao vivo (poll GET /api/campaigns/:id):

Campo	Significado
`total`	Alvos registrados no início
`pending`	Ainda não distribuídos na fila
`queued`	Enviados, aguardando um relatório de entrega
`delivered`	Confirmado como entregue
`failed`	Falha na entrega / enviado para carta morta
`skipped_inactive`	Ignorado porque não registrado no início
`dispatched`	`queued + delivered + failed`
`progress_percent`	Percentual de alvos que não estão mais `pending`
`delivery_percent`	Percentual de mensagens enviadas entregues

Contagens de entrega e falha atualizam automaticamente à medida que os relatórios de entrega fluem de volta pelo caminho normal de entrega do SMSC. Detalhes por destinatário (e filtragem por estado, por exemplo, todos que falharam) estão disponíveis via GET /api/campaign_targets/:id?state=failed.

Configuração

config :sms_c, :campaigns,
  # Iniciar o trabalhador de distribuição (defina como falso para pausar TODA entrega de campanhas)
  enabled: true,
  # Intervalo entre ticks de distribuição em milissegundos
  drip_tick_ms: 1000,
  # Mensagens por segundo por campanha quando uma campanha não define seu próprio drip_tps
  default_drip_tps: 50,
  # Janela de validade da mensagem padrão quando uma campanha não define validity_hours
  message_validity_hours: 72,
  # Quanto tempo uma campanha parada/completada persiste antes de ser excluída (horas)
  campaign_retention_hours: 168

Validade e entrega agendada

Uma campanha pode definir, no momento da criação:

validity_hours - o período de validade da mensagem. Cada mensagem enviada é carimbada com um expires para que mensagens não entregues expirem em vez de permanecer na fila. Padrão é message_validity_hours da configuração.
deliver_after - um horário ISO8601 opcional (deve estar no futuro) para um envio agendado.

Como a entrega agendada interage com a distribuição. A campanha ainda começa a distribuir imediatamente a drip_tps, mas o relógio de cada mensagem é deslocado para frente por um deslocamento fixo delta = deliver_after − started_at. Assim, uma mensagem distribuída em tempo real t é carimbada send_time/deliver_after = t + delta e expires = t + delta + validity_hours. Como as mensagens são inseridas a drip_tps em tempo real, seus valores deliver_after por mensagem saem escalonados a drip_tps começando em deliver_after - a entrega é limitada por taxa em vez de um rebanho estrondoso no instante agendado. Sem deliver_after, delta = 0 e as mensagens são distribuídas e entregues imediatamente.

Fluxo de trabalho típico

# 1. Faça o upload de uma lista de destinatários nomeada com variáveis por destinatário (CSV ou JSON)
curl -k -X POST https://smsc:8443/api/campaign_lists \
  -H 'Content-Type: application/json' \
  -d '{"name":"Clientes VIP",
       "csv":"msisdn,first,plan\n12025550101,Alice,Gold\n12025550102,Bob,Silver\n"}'
# => {"id": 1, "recipient_count": 2, ...}

# 2. Crie uma campanha contra essa lista, modelando as variáveis
curl -k -X POST https://smsc:8443/api/campaigns \
  -H 'Content-Type: application/json' \
  -d '{"name":"Aviso de Renovação","message":"Oi {{ var1 }}, seu {{ var2 }} plano renova em breve.",
       "source_msisdn":"12345","source_smsc":"IMS_SMSC",
       "list_id":1,"audience":"active_only","drip_tps":50}'
# => {"id": 7, "status": "draft", ...}

# 3. Inicie-a
curl -k -X POST https://smsc:8443/api/campaigns/control \
  -H 'Content-Type: application/json' \
  -d '{"campaign_id":7,"action":"start"}'

# 4. Consulte o progresso / estatísticas de entrega
curl -k https://smsc:8443/api/campaigns/7
# => {... "stats": {"total":..,"delivered":..,"failed":..,"progress_percent":..}}

Para enviar mensagens a todos os assinantes ativos, omita list_id na etapa 2 (e pule a etapa 1 completamente).

Veja também

Referência da API de Campanhas
Guia de Roteamento de SMS - como mensagens distribuídas são roteadas/entregues
Referência de Configuração

Visão Geral​

Segmentação: listas e o padrão de assinante ativo​

Variáveis por destinatário e modelagem​

Filtro de audiência​

Ciclo de Vida​

Deletando uma campanha​

Taxa de Distribuição (proteção contra sobrecarga)​

Progresso e estatísticas de entrega​

Configuração​

Validade e entrega agendada​

Fluxo de trabalho típico​

Veja também​