Guia de início para dados e segmentos de assinantes de telecomunicações

Este guia configura um perfil de assinante de telecomunicações no Pushwoosh e o transforma em segmentos funcionais: lembretes de expiração de pacotes, alertas de saldo baixo, confirmações de recarga e mensagens de boas-vindas em roaming. Conclua todas as seções e o primeiro segmento que você criar retornará um público diferente de zero, para que você não precise entrar em contato com o suporte.

O erro mais comum é o tipo de tag. Uma data armazenada em uma tag do tipo Inteiro (Integer) parece correta na lista de tags e, silenciosamente, faz com que todos os segmentos de data retornem zero usuários. Escolha os tipos primeiro e, em seguida, carregue os dados.

Pré-requisitos

• Um aplicativo em sua conta Pushwoosh, com o SDK integrado ou dispositivos registrados por meio da API.
• Um token de acesso à API com permissão para definir tags.
• Assistência de um desenvolvedor para o trabalho de atualização de servidor para servidor.
• Um identificador de assinante que você pode mapear para o Pushwoosh: um User ID (geralmente o MSISDN, o número de telefone do assinante em formato internacional, ou um ID de assinante interno) ou o HWID do dispositivo.

Como é um perfil de assinante de telecomunicações

A tabela abaixo lista as tags que cobrem os cenários padrão de telecomunicações. Crie-as antes do primeiro carregamento de dados, exatamente com estes tipos.

Tag	Tipo	Valor de exemplo	O que impulsiona
msisdn	String	923001234567	Identidade e segmentação por SMS
tariff_plan	String	Gold Postpaid	Ofertas específicas do plano
prepaid_postpaid	String	prepaid	Dividir a base por modelo de faturamento
balance	Integer	50	Alertas de saldo baixo
bundle_id	String	DATA_5GB_30D	Sobre qual pacote é o lembrete
bundle_expiry_date	Date	2026-09-20 21:00:00	Lembretes de expiração de pacotes
roaming_status	Boolean	true	Mensagens de boas-vindas em roaming e avisos sobre cobranças de roaming

Duas linhas nessa tabela decidem se os cenários funcionarão ou não.

• bundle_expiry_date tem que ser uma tag do tipo Data (Date). Apenas as tags de Data recebem os operadores relativos, como daqui a N a M dias, que expressam “o pacote expira em três dias” sem recalcular o segmento todas as noites.
• bundle_id permanece separado da data de expiração. Uma tag armazena a data, outra armazena a qual pacote ela pertence. Armazenar ambos em uma única tag exigiria a análise de uma string dentro do segmento, o que o construtor de segmentos não pode fazer.

Por que o tipo de tag é decidido antes do primeiro upload

As tags são criadas automaticamente na primeira vez que um valor chega, e o tipo é inferido a partir desse primeiro valor. Um número inteiro se torna Inteiro (Integer), um número com ponto decimal se torna Preço (Price), uma string se torna String (ou Data, se corresponder a um formato de data e hora reconhecido, como 2024-10-02 22:11), um array se torna Lista (List), e true/false se torna Booleano (Boolean).

A inferência falha nos dados de telecomunicações, porque as datas de expiração geralmente são enviadas como timestamps Unix:

• Você envia bundle_expiry_date como o número 1758393600. É um número inteiro, então a tag é criada como uma tag do tipo Inteiro. Os valores são carregados corretamente, a tag parece saudável e nenhum operador de data é oferecido para ela.
• A tag já existe como Inteiro e você depois muda para enviar "2026-09-20". O valor não é mais analisado como um número, então é descartado sem nenhum erro. A API ainda responde com sucesso, e o dispositivo mantém seu valor antigo ou nenhum.

Ambos os casos terminam com um segmento que retorna zero usuários e nenhum erro em lugar algum para explicar isso.

O tipo de uma tag não pode ser alterado após a criação. Corrigir um tipo errado significa criar uma nova tag com o tipo correto e recarregar os valores nela. A tag antiga permanece na lista até que você a exclua.

Para evitar ambos os casos, defina os tipos você mesmo:

1. Abra a página Tags do seu Painel de Controle.
2. Clique em Criar tag.
3. Insira o nome da tag e escolha seu tipo na lista. Repita para cada tag na tabela acima, antes do primeiro upload.
4. Em bulkSetTags, envie create_missing_tags: false. Uma tag ausente retornará um erro em vez de ser criada com um tipo adivinhado.

Como atualizar o perfil de servidor para servidor

Os dados do perfil de telecomunicações mudam diariamente, então são carregados como um trabalho em lote, em vez de pelo SDK móvel.

1. Construa o delta diário do seu lado: assinantes cujo saldo, pacote ou status de roaming mudou desde a última execução. Uma recarga completa da base todas as noites raramente é necessária e consome seu volume de solicitações.
2. Envie o lote para bulkSetTags, endereçando os dispositivos por user_id quando o MSISDN for seu User ID, ou por hwid caso contrário. Uma solicitação carrega muitos dispositivos, e o método espera pelo menos 50 deles. Para um único assinante, use setTags em vez disso.
3. Consulte o request_id retornado com o status de bulkSetTags até que o trabalho seja concluído. Solicite-o com ?detailed=true e registre o resultado, porque um trabalho concluído não é o mesmo que todos os valores terem sido aceitos.
4. Tente novamente os lotes que falharam com a mesma carga útil. Definir uma tag é idempotente: enviar o mesmo valor duas vezes deixa o mesmo perfil.

Atualização diária de pacote

{
  "application": "XXXXX-XXXXX",
  "auth": "your API access token",
  "create_missing_tags": false,
  "devices": [{
    "user_id": "923001234567",
    "tags": {
      "bundle_id": "DATA_5GB_30D",
      "bundle_expiry_date": "2026-09-20 21:00:00",
      "balance": 50,
      "roaming_status": false
    }
  }]
}

Quais formatos de data uma tag do tipo Data (Date) aceita

Uma tag de Data armazena um timestamp da época Unix em segundos. Envie um destes:

• Um valor de época em segundos, como um número: 1758393600.
• Uma string de data e hora com separadores: 2026-09-20 21:00:00, 2026-09-20 21:00 ou 2026-09-20. Uma data sem hora significa meia-noite.
• Uma string ISO 8601 com um deslocamento: 2026-09-20T21:00:00+05:00.

Dois formatos se comportam de uma maneira que surpreende a maioria das integrações:

• Uma string sem fuso horário é lida como UTC. Não é lida no seu horário local. Um pacote que expira às 21:00 em Karachi é 2026-09-20T21:00:00+05:00, ou o valor de época correspondente. 2026-09-20 21:00:00 é três horas mais cedo em tempo real, o que move os assinantes entre as ondas de lembretes diários.
• Uma string de dígitos é um valor de época, não uma data. "20260920" não é 20 de setembro de 2026, é um timestamp de época que aponta para 1970. Envie um valor de época real ou uma string com separadores.

Um valor que não corresponde a nenhum dos formatos aceitos é descartado sem falhar a solicitação. É por isso que o passo 3 acima verifica o resultado do trabalho em vez de apenas o status HTTP.

Receitas de segmentos

Cada receita abaixo é um segmento. Abra a seção Segments, clique em Criar segmento para abrir o construtor e, em seguida, adicione os filtros listados. Para o passo a passo completo do construtor, consulte Criar segmentos por tags.

Pacote expira em três dias

Visa assinantes cujo pacote atual termina em três dias, para que o lembrete chegue enquanto uma renovação ainda faz sentido.

• Tag: bundle_expiry_date
• Operador: abra a lista de operadores, vá para a seção DATAS RELATIVAS e escolha daqui a N a M dias
• Valores: 3 e 3

Altere ambos os valores para 1 e 1 para o lembrete do último dia. Adicione um segundo filtro em bundle_id quando a mensagem mencionar o pacote específico.

Não use os operadores de ANIVERSÁRIO aqui

A seção ANIVERSÁRIO oferece é em N dias. Esse operador compara apenas o dia e o mês, então ele corresponde a todos os assinantes cujo pacote expirou nessa data em qualquer ano. Use-o para aniversários, não para a validade do pacote.

Saldo baixo

Visa assinantes pré-pagos que não podem mais pagar pela próxima renovação.

• Tag: balance, operador menor ou igual, valor 50
• Tag: prepaid_postpaid, operador é, valor prepaid

Ambas as condições vão no mesmo grupo, combinadas com E.

Entrada em roaming

Visa assinantes que estão atualmente no exterior, para uma mensagem de boas-vindas com as tarifas locais.

• Tag: roaming_status, operador é verdadeiro

Um segmento baseado em tags reflete o estado no momento da compilação. Quando você precisa que a mensagem seja enviada no momento em que o roaming começa, acione uma jornada do cliente a partir de um evento de roaming em vez de enviar para este segmento.

Confirmação de recarga e outras reações

Confirmar uma recarga é uma reação à ação de um único assinante, não um público a ser compilado. Envie um evento personalizado do seu sistema de faturamento com postEvent e inicie uma Jornada do Cliente a partir dele. O mesmo se aplica à compra de pacotes e à mudança de plano.

O segmento retorna zero usuários

Verifique estes itens em ordem. Os três primeiros cobrem a maioria dos casos relatados ao suporte.

1. Verifique o tipo da tag na página Tags. Se bundle_expiry_date for Inteiro, nenhum operador de data foi aplicado e o segmento comparou números. Crie uma tag de Data e recarregue os valores.
2. Verifique se os valores realmente chegaram. Abra o User Explorer, encontre um assinante que você sabe que estava no lote e veja suas tags. Uma tag vazia após um trabalho bem-sucedido significa que os valores foram rejeitados pelo formato, na maioria das vezes strings apenas com dígitos ou uma data que nenhum layout correspondeu.
3. Verifique a seção do operador. é em N dias em ANIVERSÁRIO ignora o ano. daqui a N a M dias em DATAS RELATIVAS não ignora.
4. Verifique o fuso horário. Timestamps de expiração enviados sem um deslocamento são lidos como UTC, o que pode mover um assinante para o dia anterior ou seguinte do seu cronograma de lembretes.
5. Recalcule o segmento antes de ler o número, para não estar olhando para um tamanho em cache. Consulte Calcular o tamanho do segmento.

Limitações a serem consideradas

• O tipo de uma tag é permanente. Planeje o perfil antes do primeiro upload, porque corrigir um tipo mais tarde significa uma nova tag e uma recarga completa.
• Operadores de data relativa não estão disponíveis em segmentos de entrega de alta velocidade. Aplicativos configurados para entrega de alta velocidade pré-compilam seus segmentos, e os operadores de data relativa não são oferecidos lá. Lembretes de expiração de pacotes devem ser executados como segmentos comuns.
• Um trabalho em lote não é em tempo real. Os segmentos veem o perfil como estava no último carregamento bem-sucedido. Cenários que devem ser acionados segundos após uma mudança de saldo pertencem a uma jornada acionada por evento, não a um lote noturno.