Pular para o conteúdo principal

Mensagens em Massa / Campanhas

← Voltar para o Índice da Documentação

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 as estatísticas de entrega.

Dois objetos reutilizáveis:

ObjetoO que é
Lista de CampanhasUm 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.
CampanhaUma execução de envio: uma lista (ou todos os assinantes ativos) + um modelo de mensagem, distribuído na fila.

Tudo é 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 assinantes ativos​

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

  • Uma lista de destinatários (list_id) — os MSISDNs que você enviou.
  • Nenhuma lista — se você criar uma campanha sem um list_id, ela segmenta 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 espaço reservado sem valor é renderizado como uma string vazia.

A modelagem é deliberadamente mínima — substituição de variáveis apenas (sem condicionais ou filtros), portanto, 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 chamada 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 público​

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

PúblicoComportamento
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.
allCada membro da lista, independentemente do registro.

A verificação de registro é uma foto tirada no momento do início — assinantes que se registram depois não são considerados. 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​

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

Excluindo uma campanha​

Excluir 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 submetidas na fila por segundo, padrão da configuração). Um trabalhador em segundo plano acorda em um intervalo fixo e submete no máximo drip_tps × interval mensagens por campanha por tick — assim, uma campanha de um milhão de destinatários nunca inunda a fila. A taxa é por campanha; várias campanhas em execução cada uma distribui em 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):

CampoSignificado
totalAlvos capturados no início
pendingAinda não distribuídos na fila
queuedSubmetidos, aguardando um relatório de entrega
deliveredConfirmado como entregue
failedFalha na entrega / marcado como carta morta
skipped_inactiveIgnorado porque não registrado no início
dispatchedqueued + delivered + failed
progress_percentPercentual de alvos que não estão mais pending
delivery_percentPercentual de mensagens enviadas entregues

Contagens de entrega e falha são atualizadas automaticamente à medida que os relatórios de entrega fluem de volta através do 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 programada​

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

  • validity_hours — o período de validade da mensagem. Cada mensagem submetida é carimbada com um expires para que mensagens não entregues expirem em vez de permanecerem na fila. O padrão é message_validity_hours da configuração.
  • deliver_after — um horário ISO8601 opcional (deve estar no futuro) para um envio programado.

Como a entrega programada 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 ser uma enxurrada no instante programado. Sem deliver_after, delta = 0 e as mensagens são distribuídas e entregues imediatamente.

Fluxo de trabalho típico​

# 1. Fazer 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. Criar uma campanha contra essa lista, modelando nas 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 plano {{ var2 }} renova em breve.",
       "source_msisdn":"12345","source_smsc":"IMS_SMSC",
       "list_id":1,"audience":"active_only","drip_tps":50}'
# => {"id": 7, "status": "draft", ...}

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

# 4. Consultar 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 no passo 2 (e pule o passo 1 completamente).

Veja também​

Última atualização em