Importar ou atualizar usuários no OneSignal usando uploads de CSV, API REST ou entrada manual. Suporta email, SMS, tags e muito mais para integração ou migração de usuários.
Importe ou atualize usuários em massa pelo painel do OneSignal usando um arquivo CSV ou entrada manual. Casos de uso comuns incluem migração de usuários de outra plataforma, atualização de detalhes de usuários e organização de usuários com Tags e Segmentos.
Você também pode atualizar ou criar usuários via REST API.
email — Obrigatório para criar novas assinaturas de email. Consulte Validação de endereço de email para mais informações.
phone_number — Obrigatório para criar novas assinaturas de SMS.
subscription_id — Recomendado apenas para casos onde você já rastreia IDs de Assinatura do OneSignal no seu backend.
Apenas um identificador de cada tipo é permitido por linha. Para associar múltiplos emails ou números ao mesmo usuário, use linhas separadas compartilhando o mesmo external_id.
Inclua external_id para desduplicar usuários. Certifique-se de que corresponde ao ID usado no método SDK login — caso contrário, ele será redefinido quando o usuário abrir o aplicativo.
Para alterar o status de assinatura, a linha deve incluir email, phone_number ou subscription_id. Apenas external_id não é suficiente.
subscription_id não vincula ou mescla Assinaturas. Use external_id para adicionar novos emails ou números de telefone a um usuário existente.
Os limites de plano de tags se aplicam por usuário, não por aplicativo. Por exemplo, se seu plano permite 20 tags por usuário e um usuário já tem 19, você só pode adicionar mais 1 — mesmo que o aplicativo possa ter chaves de tag ilimitadas.
Use o fluxo de trabalho de Atualizações em massa de tags para exportar usuários, limpar valores de tags indesejados e reimportar com a opção de exclusão habilitada.
Evite espaços nas chaves de tag — use underscores em vez disso.
Chaves de tag reservadas e restritasAs seguintes chaves de tag são reservadas e não devem ser usadas:
“user”
“subscription”
“message”
“template”
“app”
“org”
“custom_data”
“dynamic_content”
Se você acidentalmente definir uma delas como chave de tag, remova-a via API de Atualização de Usuário.Substituições e exclusões de tagsDurante uma importação de CSV:
Tags incluídas no seu CSV são substituídas pelo valor fornecido.
Tags não incluídas no seu CSV permanecem inalteradas no registro do usuário.
Se uma tag ainda estiver presente após a importação, verifique se:
A coluna de cabeçalho contém a chave da tag.
A linha não contém nenhum valor.
Você selecionou a opção “Excluir tags com valores em branco” na tela de Revisão.
Outras fontes de tags sendo adicionadasSe tags excluídas reaparecerem após a importação, uma integração pode estar automaticamente escrevendo-as de volta. Fontes comuns incluem:
Segment
HubSpot
Journeys
Métodos de tagging do SDK
APIs personalizadas ou pipelines ETL
Revise os mapeamentos de integração e gatilhos de eventos para garantir que eles não estejam substituindo suas alterações no CSV.
Em vez de usar cabeçalhos de coluna separados para cada chave de tag, você pode definir um único cabeçalho tags, com cada linha de usuário contendo um mapa JSON de todos os pares chave-valor entre aspas. Isso é especialmente útil se você exportou anteriormente um CSV com tags e deseja reimportá-lo sem reformatação.Exemplo de cabeçalho:
external_id,email,tags
Exemplo de linhas:
As tags devem ser formatadas como um objeto JSON entre aspas.
Quando importado, o OneSignal converte automaticamente cada par chave-valor em tags distintas para o registro de assinatura.Exemplo: Excluir tags em massaPara remover tags em massa, exporte seus dados atuais, apague os valores das tags e reimporte o CSV com a opção de exclusão habilitada.
1
Exporte seus dados
Navegue até Audience > Subscriptions no painel do OneSignal. Habilite apenas as colunas External ID, Subscription ID e Tags (e opcionalmente Email ou Phone Number).
Clique em Export para exportar o CSV.
Selecione as colunas exibíveis para exportação
2
Apague os valores das tags que deseja excluir
Abra o CSV exportado em um editor de texto e defina os valores de cada tag que deseja excluir como uma string vazia.Por exemplo, uma linha com valores de tag antes de editar:
Isso resultará na exclusão das tags level e color do usuário.
3
Reimporte o CSV com a opção de exclusão
Pegue o CSV editado e importe.
Na tela de Revisão, selecione Sim para Excluir tags com valores em branco. O OneSignal exclui as tags com valores em branco durante a importação.
Tela de revisão com a opção de remover tags com valores vazios
Para remover apenas tags específicas, apague os valores dessas tags e deixe as outras inalteradas. Apenas valores em branco são excluídos quando a opção de exclusão está habilitada.
Entre em contato com support@onesignal.com e compartilhe o arquivo CSV que você enviou junto com uma captura de tela do email de confirmação. Teremos prazer em dar uma olhada!
A validação de endereço de email detecta problemas comuns em endereços de email antes que cheguem ao seu público. Ela sinaliza erros de digitação, domínios inválidos, endereços baseados em função e serviços de email descartáveis que podem aumentar sua taxa de rejeição ou prejudicar sua reputação de remetente.
Validação de endereço de email
Valide endereços de email durante a importação de CSV e em massa para reduzir rejeições e proteger sua reputação de remetente.
Se você tiver erros ou dúvidas sobre a formatação do seu CSV, pode descrever o problema do CSV para uma ferramenta de IA (como Claude, ChatGPT ou similar) para limpar ou reconstruir automaticamente seu arquivo antes de importar novamente.
Sempre teste com uma amostra pequena (5-10 linhas) antes de importar milhares de registros.
Exemplos de prompts de IA para problemas comuns de CSV
Excluindo tags
Formatação de tags
Identificar formatos inválidos
Corrigir números de telefone
Migrar de outra plataforma
Exemplo de prompt de IA para excluir tags indesejadas
Quero remover todas as tags, exceto "user_name" deste CSV.Por favor:1. Mantenha apenas a coluna de tag "user_name".2. Remova todas as outras colunas de tags.3. Formate o CSV para que corresponda aos requisitos de importação do OneSignal neste documento: https://documentation.onesignal.com/docs/en/importAqui está meu CSV:[COLAR CSV]
Exemplo de prompt de IA para corrigir formato de várias colunas de tags
Tenho várias colunas de tags como tag_first_name, tag_last_name e tag_city.De acordo com a documentação de importação do OneSignal, cada tag deve:- Usar o prefixo tag_- Conter apenas caracteres alfanuméricos e sublinhados- Seguir tipos de dados suportadosVocê poderia revisar meu CSV, identificar o que está formatado incorretamente e retornar uma versão corrigida que atenda a esses requisitos?Link da documentação:https://documentation.onesignal.com/docs/en/import
Exemplo de prompt de IA para identificar formatação ausente ou inválida
O OneSignal rejeitou meu CSV durante a importação.Por favor:1. Valide minha estrutura CSV.2. Identifique quaisquer problemas de formatação (cabeçalhos, colunas de ID, formatos de tags, aspas).3. Retorne uma versão corrigida que siga os requisitos neste documento: https://documentation.onesignal.com/docs/en/import#prepare-your-csvAqui está o arquivo:[COLAR CSV]
Exemplo de prompt de IA para corrigir formatos de número de telefone inválidos (E.164)
Minha importação está fallhando porque os números de telefone não estão no formato E.164.Por favor:1. Converta todos os números de telefone para o formato E.164.2. Mantenha todos os outros campos inalterados.3. Certifique-se de que o CSV corresponda à estrutura exigida do OneSignal: https://documentation.onesignal.com/docs/en/importExemplo de formato atual: (555) 555-1234Aqui está meu CSV:[COLAR CSV]
Exemplo de prompt de IA para migrar de outra plataforma
Estou migrando de [Nome da Plataforma] para o OneSignal.Você poderia transformar este CSV para corresponder ao formato de importação do OneSignal?Inclua:- `external_id`- Quaisquer tags convertidas com o prefixo `tag_` (se desejado)- Números de telefone no formato E.164 (se aplicável)Documento de referência:https://documentation.onesignal.com/docs/en/importAqui está meu CSV:[COLAR CSV]
Navegue até Audience > Import e clique em Launch CSV Importer.
1
Faça upload do seu CSV
Selecione seu arquivo CSV preparado.
Tela de importação CSV
2
Mapear campos
O OneSignal mapeia automaticamente os cabeçalhos do CSV para propriedades conhecidas. Revise os mapeamentos antes de confirmar — use external_id, email, phone_number e/ou subscription_id como identificadores, não como tags.
Para adicionar um novo email ou número de telefone a um usuário existente, você deve usarexternal_id. Não use subscription_id — ele não vinculará ou mesclará assinaturas.
Tela de mapeamento de campos CSV
Se o OneSignal detectar problemas de formato, corrija o CSV e reenvie (recomendado) ou desmarque a coluna afetada para ignorá-la.
3
Revisar e confirmar
A tela de revisão permite que você:
Criar automaticamente um Segmento — Adiciona uma tag a cada usuário importado e cria um Segmento correspondente. Fique atento aos limites do seu plano.
Excluir tags com valores em branco — Remove qualquer tag com valor em branco no CSV. Útil para limpar tags indesejadas e ficar dentro dos limites do plano.
Configurar validação de endereço de email — Configure as configurações de validação de endereço de email para reduzir rejeições e proteger sua reputação de remetente.
Quando o import terminar, você receberá um email de confirmação de contact@onesignal.com com os dados a seguir. Um único User pode ter múltiplas Subscriptions (ex: email + push), portanto as contagens de assinatura podem ser maiores que o número de linhas.Registro(s) de assinatura adicionado(s) — Novas Subscriptions de email ou SMS criadas. 0 significa que nenhum identificador único de email ou phone_number foi encontrado.Registro(s) de assinatura modificado(s) — Subscriptions com dados alterados (tags, propriedades, etc.). Exemplo: 10 External IDs cada um vinculado a 20 assinaturas = 200 registros modificados.Atualizações de assinatura ignoradas — Subscriptions ignoradas pelo motivo indicado. Se o motivo for “acima do limite de tags do seu app”, remova tags e reimporte ou faça upgrade do seu plano.Não importado — Linhas que não foram atualizadas ou importadas. Causas comuns: o external_id não corresponde a nenhuma assinatura existente, ou o email/phone_number já existe sem novos dados a definir.Novo segmento criado — O nome do segmento, se você selecionou essa opção.
Exemplo de confirmação por email.
No exemplo acima:
100 assinaturas foram criadas a partir de endereços de email ou números de telefone únicos que não existiam no app.
37,814 assinaturas foram atualizadas (não é a contagem de Users — cada usuário pode ter múltiplas assinaturas).
621,852 linhas não foram importadas porque seus External IDs não correspondiam a usuários existentes, ou emails/números de telefone já existiam sem novos dados.
Segments contam apenas Subscriptionsinscritas. Assinaturas canceladas são atualizadas pelo import, mas não são refletidas nas contagens de segmentos. Melhorias na segmentação estão em andamento.
Você pode adicionar manualmente as assinaturas de email e número de telefone do usuário através do painel do OneSignal navegando para Audience > Users > Update/Import Users > Manually Add Users.
Tela de adicionar usuários manualmente
Na tela New User, inclua os dados que você deseja e selecione Create User.
A duração depende do tamanho do arquivo. A maioria das importações é concluída em alguns minutos. Você recebe um email de contact@onesignal.com quando a importação termina — adicione esse endereço aos seus contatos para garantir a entrega.
Não. Não há desfazer integrado para importações CSV. Se você precisar reverter alterações, prepare um novo CSV com os valores corretos e reimporte-o. Para exclusões de tags, use o fluxo de trabalho de Excluir tags em massa.
Por que as contagens do meu segmento não correspondem às linhas do meu CSV?
Os Segmentos contam apenas Assinaturasinscritas. As assinaturas canceladas são atualizadas pela importação, mas não são refletidas nas contagens de segmentos.
Por que minha importação mostrou “não importado” para algumas linhas?
As linhas são ignoradas quando o external_id não corresponde a nenhuma assinatura existente no aplicativo, ou quando o email ou phone_number já existe sem novos dados para definir. Verifique a seção de Confirmação por email para obter detalhes sobre cada status.
Uma integração ou chamada de SDK pode estar readicionando as tags após sua importação. Fontes comuns incluem Segment, HubSpot, Journeys, métodos de marcação do SDK e APIs personalizadas. Revise seus mapeamentos de integração e gatilhos de eventos.
