Você também pode atualizar ou criar usuários via REST API.
Importação CSV
Use um arquivo CSV para importar ou atualizar endereços de email, números de telefone, IDs externos, Tags, idioma, fuso horário, país e mais.Requisitos do CSV
Certifique-se de que seu arquivo.csv atende aos seguintes requisitos:
- Codificação UTF-8 (sem BOM)
- Sem caracteres não imprimíveis (sem caracteres especiais ou não-ASCII)
- Cabeçalhos de coluna limpos e únicos
- Tamanho do arquivo menor que 150MB (cerca de 2 milhões de linhas)
- Pelo menos um identificador dos seguintes:
external_id— Recomendado. Identifica Users em todas as Subscriptions.email— Obrigatório para criar novas assinaturas de email.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.
Colunas CSV disponíveis
Veja external ID para mais informações.
Cria uma subscription de Email. Desduplicada se já estiver presente.
Use formato E.164 como
+15555551234. Cria uma subscription de SMS.Recomendado apenas se você já rastreia IDs de Assinatura do OneSignal no seu backend.
Define o status de assinatura. Requer
email, phone_number ou subscription_id na mesma linha — não pode ser usado apenas com external_id.false remove o email das listas de supressão.Veja ISO 3166-2.
Limites e restrições de tags
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.
- “user”
- “subscription”
- “message”
- “template”
- “app”
- “org”
- “custom_data”
- “dynamic_content”
- 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.
- 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.
- Segment
- HubSpot
- Journeys
- Métodos de tagging do SDK
- APIs personalizadas ou pipelines ETL
Importar tags de uma única coluna
Em vez de usar cabeçalhos de coluna separados para cada chave de tag, você pode definir um único cabeçalhotags, 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:
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.
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:A mesma linha após apagar os valores das tags:Isso resultará na exclusão das tags
Linha antes de editar
Linha após apagar os valores das tags
level e color do usuário.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.
Precisa de ajuda?
- Experimente a seção Use IA para verificar seu CSV antes de importar acima.
- Entre em contato com
support@onesignal.come compartilhe o arquivo CSV que você enviou junto com uma captura de tela do email de confirmação. Teremos prazer em dar uma olhada!
Use IA para verificar seu CSV antes de importar
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.Exemplos de prompts de IA para problemas comuns de CSV
Exemplos de prompts de IA para problemas comuns de CSV
- Identificar formatos inválidos
- Corrigir números de telefone
- Migrar de outra plataforma
Etapas de importação
Navegue até Audience > Import e clique em Launch CSV Importer.
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.Revisar e confirmar
A tela de revisão tem duas opções:Com “Excluir tags com valores em branco” habilitado, 
- 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.
tag1 é excluída de UserA e tag2 é excluída de UserB.A importação foi iniciada. Você receberá um email de confirmação de
contact@onesignal.com quando ela for concluída.Confirmação por email
Quando o import terminar, você receberá um email de confirmação decontact@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.
100assinaturas foram criadas a partir de endereços de email ou números de telefone únicos que não existiam no app.37,814assinaturas foram atualizadas (não é a contagem de Users — cada usuário pode ter múltiplas assinaturas).621,852linhas 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.
Entrada manual
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.
Perguntas frequentes
Quanto tempo leva uma importação CSV?
A duração depende do tamanho do arquivo. A maioria das importações é concluída em alguns minutos. Você recebe um email decontact@onesignal.com quando a importação termina — adicione esse endereço aos seus contatos para garantir a entrega.
Posso desfazer uma importação CSV?
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 Assinaturas inscritas. 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 oexternal_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.