Visão geral
A integração HubSpot do OneSignal conecta seu CRM HubSpot ao OneSignal por meio de ações de workflow nativas — sem middleware de terceiros. Você pode:- Enviar mensagens — acionar notificações push, e-mails e SMS a partir dos Workflows do HubSpot
- Criar usuários — sincronizar contatos do HubSpot com o OneSignal com assinaturas de e-mail e SMS
- Gerenciar tags — definir ou excluir Tags do OneSignal com base nas propriedades de contato do HubSpot
- Segmentar mensagens no aplicativo — usar tags definidas pelo HubSpot para criar segmentos que controlam a entrega de mensagens no aplicativo
Pré-requisitos
- Função de Super Admin do HubSpot ou Permissões do Marketplace de Aplicativos
- Um plano pago do OneSignal (não disponível em planos gratuitos)
O HubSpot descontinuou o aplicativo OneSignal original de terceiros em dezembro de 2024. O OneSignal agora fornece seu próprio aplicativo HubSpot com funcionalidade expandida. Se você usou a integração anterior, consulte as etapas de migração abaixo.
Migrando da integração legada do HubSpot
Migrando da integração legada do HubSpot
Instalar a nova integraçãoAtive a integração do HubSpot no painel do OneSignal em Dados > Integrações conforme descrito em Conectar o HubSpot ao OneSignal abaixo.Migrar seus workflowsRecomendamos criar um novo workflow para testar a nova integração antes de substituir ações em seus workflows existentes.
- Clonar seu workflow — Na página Workflows do HubSpot, clique em Clonar ao lado do seu workflow existente.
- Remover gatilhos — No workflow clonado, remova todos os gatilhos de inscrição para que ele não seja acionado automaticamente quando publicado.
- Substituir ações legadas — Remova cada ação legada do OneSignal e substitua pela nova versão. Se ambos os aplicativos estiverem instalados, o aplicativo legado mostrará “Built by HubSpot” — use o que não mostrar isso.
- Testar com um único contato — Salve e publique o workflow, depois inscreva manualmente um contato de teste. Verifique o histórico de inscrições para confirmar que as ações foram concluídas com sucesso.
- Substituir ou atualizar — Depois de confirmar que o workflow funciona corretamente, substitua o workflow original pelo clone ou aplique as mesmas alterações ao original.
support@onesignal.com.Conectar o HubSpot ao OneSignal
Ativar a integração
No OneSignal, acesse Dados > Integrações > Catálogo e selecione HubSpot.
Corresponder usuários com External ID
Para vincular contatos do HubSpot a usuários do OneSignal, defina o External ID no OneSignal com um valor que corresponda a uma propriedade única no HubSpot (por exemplo, um ID de usuário ou endereço de e-mail). Defina o External ID usando o métodologin do SDK no seu aplicativo ou site. Escolha uma propriedade que esteja prontamente disponível tanto no seu aplicativo quanto no HubSpot para que a correspondência seja confiável.
Consulte Usuários e Assinaturas para detalhes sobre gerenciamento de identidade e assinatura.
Criar um workflow do HubSpot
No HubSpot, acesse Automação > Workflows e clique em Criar workflow. Selecione Baseado em contato e configure seus gatilhos de inscrição. Para adicionar uma ação do OneSignal, clique em + no editor de workflow e pesquise “OneSignal.”
- Aplicativo OneSignal — o aplicativo que você conectou durante a configuração
- External ID — a propriedade de contato do HubSpot que corresponde ao External ID no OneSignal
Ações do OneSignal
Criar usuários do OneSignal a partir do HubSpot
A ação Criar Usuário cria um Usuário no OneSignal quando um contato passa pelo workflow. Use para manter o OneSignal e o HubSpot sincronizados conforme novos contatos são adicionados. Se as seguintes propriedades do HubSpot estiverem definidas, o OneSignal cria automaticamente as Assinaturas correspondentes:- E-mail → cria uma assinatura de e-mail no OneSignal
- Número de telefone → cria uma assinatura de SMS no OneSignal
Editar tags do OneSignal a partir do HubSpot
A ação Editar Tags define ou exclui Tags no usuário OneSignal correspondente. Tags habilitam a Personalização de Mensagens e Segmentação, e são o mecanismo para segmentar mensagens no aplicativo a partir do HubSpot.Definir tags
Insira um objeto JSON no campo Tags:Excluir tags
Defina o valor como uma string vazia para remover uma tag:
Enviar mensagens a partir dos workflows do HubSpot
A ação Enviar Notificação entrega uma notificação push, e-mail ou SMS ao usuário OneSignal correspondente.
Primeiro Nome) para personalizar o conteúdo da notificação.
Enviar mensagens no aplicativo com o HubSpot
Mensagens no aplicativo não podem ser enviadas diretamente de um workflow do HubSpot. Em vez disso, use o HubSpot para marcar usuários e segmente esses usuários com uma mensagem no aplicativo baseada em segmento no OneSignal.Marcar usuários a partir do HubSpot
No seu workflow do HubSpot, use a ação Editar Tags para definir uma tag nos contatos. Por exemplo:
{ "hubspot_campaign": "spring_promo" }.Criar um segmento no OneSignal
No painel do OneSignal, acesse Audiência > Segmentos e clique em Novo Segmento. Adicione um filtro Tag de Usuário correspondendo à chave e valor da tag definida pelo HubSpot (por exemplo,
hubspot_campaign é spring_promo).Criar a mensagem no aplicativo
Acesse Mensagens > No Aplicativo e crie uma nova mensagem no aplicativo. Em Audiência, selecione Mostrar para Segmento(s) Específico(s) e escolha o segmento que você criou.Conforme os usuários passam pelo workflow do HubSpot e recebem a tag, eles são adicionados ao segmento imediatamente.
Configurar o gatilho
Tags por si só não acionam mensagens no aplicativo. Se a tag for definida enquanto o usuário está usando ativamente o aplicativo, a mensagem no aplicativo não será exibida até a próxima sessão (uma nova sessão começa após o aplicativo ficar em segundo plano por 30+ segundos).Gatilhos disponíveis:
- Ao abrir o aplicativo — exibe na próxima vez que o usuário abrir o aplicativo
- Duração da sessão — exibe após um número definido de segundos na sessão
- Tempo desde a última mensagem no aplicativo — evita mensagens consecutivas
- Programático — acionar do código do aplicativo usando o SDK do OneSignal
Padrões comuns de workflow
Os workflows do HubSpot combinam gatilhos de inscrição (o evento que inicia o workflow) com ações do OneSignal (o que acontece com o usuário no OneSignal). Abaixo estão os padrões recomendados para casos de uso comuns.Todo padrão de workflow abaixo pressupõe que você já conectou o HubSpot ao OneSignal e está correspondendo usuários via External ID.
Boas-vindas e integração
Envie uma mensagem de boas-vindas quando um novo usuário se cadastrar e marque-o para mensagens no aplicativo de integração.| Etapa | Tipo | Configuração |
|---|---|---|
| Gatilho de inscrição | HubSpot | Propriedade de contato Data em que se tornou cliente é conhecida |
| Ação 1 | OneSignal: Criar Usuário | Defina o External ID para a propriedade de contato do HubSpot que corresponde ao seu aplicativo (por exemplo, um ID de usuário ou endereço de e-mail) |
| Ação 2 | OneSignal: Editar Tags | { "onboarding": "active", "name": "<First Name>" } — insira o token de propriedade Primeiro Nome do HubSpot para o valor do nome |
| Ação 3 | OneSignal: Enviar Notificação | Use um template de push de boas-vindas ou componha inline com uma saudação personalizada |
Reengajamento
Alcance usuários que não visitaram seu aplicativo recentemente.| Etapa | Tipo | Configuração |
|---|---|---|
| Gatilho de inscrição | HubSpot | Propriedade de contato Data da última atividade é há mais de 14 dias |
| Ação 1 | OneSignal: Enviar Notificação | Use um template de push de reengajamento (por exemplo, “Sentimos sua falta — veja as novidades”) |
| Atraso | HubSpot: Aguardar 3 dias | — |
| Ramificação If/then | HubSpot | Verifique se o contato visitou seu site desde a inscrição |
| Ramificação Sim | OneSignal: Editar Tags | { "reengaged": "true" } |
| Ramificação Não | OneSignal: Enviar Notificação | Use um template de e-mail com incentivo mais forte |
Mudança de estágio do ciclo de vida
Sincronize as mudanças de estágio do ciclo de vida no HubSpot com tags do OneSignal para que você possa segmentar diferentes segmentos de usuários.| Etapa | Tipo | Configuração |
|---|---|---|
| Gatilho de inscrição | HubSpot | Propriedade de contato Estágio do ciclo de vida muda para qualquer valor |
| Ação 1 | OneSignal: Editar Tags | { "lifecycle_stage": "<Lifecycle Stage>" } — insira o token de propriedade Estágio do Ciclo de Vida do HubSpot para o valor |
| Ramificação If/then | HubSpot | Verifique se o estágio do ciclo de vida = Cliente |
| Ramificação Sim | OneSignal: Enviar Notificação | Use um template de push ou e-mail de “Bem-vindo à família” |
Negócio fechado / pós-compra
Acione uma mensagem de agradecimento e marque usuários para campanhas de upsell após o fechamento de um negócio.| Etapa | Tipo | Configuração |
|---|---|---|
| Gatilho de inscrição | HubSpot | Propriedade de negócio Estágio do negócio = Fechado Ganho |
| Ação 1 | OneSignal: Editar Tags | { "customer": "true", "deal_value": "<Amount>" } — insira o token de propriedade Valor do Negócio do HubSpot para o valor |
| Ação 2 | OneSignal: Enviar Notificação | Use um template de e-mail de agradecimento |
| Atraso | HubSpot: Aguardar 7 dias | — |
| Ação 3 | OneSignal: Enviar Notificação | Use um template de push de upsell/cross-sell |
Workflows baseados em negócios requerem um tipo de workflow Baseado em Negócio no HubSpot. Use o External ID do contato associado para corresponder ao usuário do OneSignal.
Campanha promocional via mensagem no aplicativo
Segmente um público específico com uma mensagem no aplicativo acionada por uma lista ou formulário do HubSpot.| Etapa | Tipo | Configuração |
|---|---|---|
| Gatilho de inscrição | HubSpot | O contato se torna membro de uma lista estática ou ativa (por exemplo, “Elegíveis para Promoção de Primavera”) |
| Ação 1 | OneSignal: Editar Tags | { "promo": "spring_2025" } |
promo = spring_2025 e configurar uma mensagem no aplicativo para esse segmento.
Para remover usuários da campanha após o término, crie um segundo workflow que exclua a tag:
| Etapa | Tipo | Configuração |
|---|---|---|
| Gatilho de inscrição | HubSpot | Baseado em data, definido para a data de término da campanha |
| Ação 1 | OneSignal: Editar Tags | { "promo": "" } |
Solução de problemas
A ação de workflow mostra “Falhou” no HubSpot
- Verifique a mensagem de erro — Expanda a ação com falha no histórico de inscrição do workflow do HubSpot. A mensagem de erro frequentemente indica a causa (por exemplo, “Usuário não encontrado,” “ID de aplicativo inválido”).
- Verifique o External ID — Confirme que a propriedade de contato do HubSpot usada como External ID corresponde a um usuário no OneSignal. Verifique o perfil do usuário em OneSignal > Audiência > Usuários e pesquise por External ID.
- Confirme que a integração está ativa — Acesse OneSignal > Dados > Integrações > HubSpot e verifique se o status da conexão está ativo.
Mensagem enviada, mas o usuário não a recebeu
- Verifique as assinaturas — O usuário deve ter uma assinatura ativa para o canal em que você está enviando (push, e-mail ou SMS). Verifique no perfil do usuário no OneSignal em Assinaturas.
- Verifique a associação ao segmento — Se você estiver usando um template com segmentação de segmento, confirme que o usuário pertence ao segmento segmentado.
- Revise os relatórios de mensagens — No painel do OneSignal, acesse Mensagens, encontre a mensagem e verifique seu relatório de entrega para ver se a mensagem foi entregue, descartada ou gerou um erro.
Tags não aparecem no usuário do OneSignal
- Verifique a correspondência do External ID — Se o External ID no workflow não corresponder a um usuário OneSignal existente, a ação Editar Tags falha silenciosamente. Use a ação Criar Usuário antes de Editar Tags para garantir que o usuário exista.
- Verifique o formato JSON — As tags devem ser um objeto JSON válido. Erros comuns incluem aspas ausentes ao redor de chaves ou valores, vírgulas à direita ou uso de aspas simples em vez de aspas duplas.
- Verifique valores vazios — Definir um valor de tag como
""exclui a tag. Verifique se as propriedades de contato do HubSpot sendo injetadas não estão em branco.
Mensagem no aplicativo não está sendo exibida
Consulte Por que minha mensagem no aplicativo não foi exibida após a tag ser definida? no FAQ abaixo.FAQ
Quais dados são compartilhados entre o HubSpot e o OneSignal?
| HubSpot | Direção | OneSignal | Descrição |
|---|---|---|---|
| Propriedades de contato | → | External ID, Tags | Os dados de contato do HubSpot correspondem e enriquecem os usuários do OneSignal via External ID e Tags. |
| Workflows | ← | Templates de Mensagem | Os Templates do OneSignal estão disponíveis para seleção nas ações de workflow do HubSpot. |
O que acontece se o External ID não corresponder a um usuário do OneSignal?
As ações Enviar Notificação e Editar Tags falham silenciosamente — nenhuma mensagem é enviada e nenhuma tag é definida. Sempre coloque uma ação Criar Usuário antes de outras ações do OneSignal no seu workflow para garantir que o usuário exista no OneSignal.Posso usar listas do HubSpot para segmentar segmentos do OneSignal?
Não diretamente. Listas do HubSpot e segmentos do OneSignal são sistemas independentes. Para conectá-los, crie um workflow que inscreva contatos de uma lista do HubSpot e use a ação Editar Tags para definir uma tag. Em seguida, crie um segmento do OneSignal baseado nessa tag. Consulte Campanha promocional via mensagem no aplicativo para um exemplo prático.Quais canais do OneSignal posso enviar a partir do HubSpot?
Notificações push podem ser enviadas usando templates ou campos de formulário. E-mail e SMS só podem ser enviados usando Templates criados no OneSignal. Mensagens no aplicativo não podem ser enviadas a partir de workflows do HubSpot — use o padrão de tag e segmento em vez disso.Por que minha mensagem no aplicativo não foi exibida após a tag ser definida?
Tags sozinhas não acionam mensagens no aplicativo. A tag adiciona o usuário a um segmento, mas a mensagem no aplicativo ainda requer um gatilho para ser exibida. Se a tag for definida enquanto o usuário estiver usando ativamente o aplicativo, a mensagem não aparecerá até a próxima sessão (30+ segundos em segundo plano). Defina o gatilho da mensagem no aplicativo como Ao abrir o aplicativo para o comportamento mais confiável. Consulte Gatilhos de Mensagens no Aplicativo para todas as opções de gatilho.Posso usar webhooks do HubSpot para chamar a API do OneSignal diretamente?
Sim. A ação de workflow Código Personalizado do HubSpot permite fazer solicitações HTTP para APIs externas. Você pode chamar a API REST do OneSignal para enviar mensagens, criar usuários ou atualizar tags fora da integração nativa. Isso é útil para casos de uso que as ações nativas não cobrem, como envio para um segmento em vez de um usuário individual.Posso enviar eventos de mensagens do OneSignal de volta ao HubSpot?
Sim. Use Fluxos de Eventos para exportar eventos de mensagens do OneSignal (enviadas, clicadas, etc.) para um endpoint de webhook. Você pode rotear esses eventos para a API de Eventos Personalizados do HubSpot ou usar um serviço de middleware para atualizar propriedades de contato do HubSpot com base nos dados de engajamento do OneSignal.Posso acionar uma Jornada do OneSignal a partir do HubSpot?
Há duas opções para inserir usuários do HubSpot em uma Jornada do OneSignal:- Tags — Use a ação Editar Tags para definir uma tag no usuário. Crie um segmento no OneSignal baseado nessa tag e use o segmento como condição de entrada da Jornada.
- Eventos Personalizados — Use a ação Código Personalizado do HubSpot para chamar a API de Eventos Personalizados do OneSignal, que pode servir como gatilho de entrada da Jornada.
Posso enviar eventos personalizados do HubSpot para o OneSignal?
Não por meio das ações de workflow nativas. A integração nativa suporta Criar Usuário, Editar Tags e Enviar Notificação. Para enviar eventos personalizados, use a ação Código Personalizado do HubSpot para chamar a API de Eventos Personalizados do OneSignal diretamente.Quais gatilhos de inscrição do HubSpot funcionam com o OneSignal?
Qualquer gatilho de inscrição do HubSpot funciona — as ações do OneSignal são ações de workflow padrão que são executadas independentemente de como o contato foi inscrito. Gatilhos comuns incluem:- Mudanças de propriedade de contato (estágio do ciclo de vida, status de lead, data da última atividade)
- Envios de formulário (formulários de cadastro, solicitações de demonstração, registros de eventos)
- Associação a listas (adicionado a uma lista estática ou ativa)
- Mudanças de estágio de negócio (progressão do pipeline, fechado ganho/perdido)
- Baseado em data (campanhas agendadas, tempo desde um evento)
- Inscrição manual (para envios únicos ou testes)
Como testar um workflow antes de colocá-lo em produção?
- Crie o workflow e remova todos os gatilhos de inscrição automáticos
- Salve e publique o workflow
- Inscreva manualmente um único contato de teste
- Verifique o histórico de inscrições no HubSpot para sucesso/falha da ação
- Verifique o usuário, as tags ou a mensagem no painel do OneSignal
- Após confirmado, adicione seus gatilhos de inscrição e republique
Tags
Adicione propriedades personalizadas aos usuários para personalização e segmentação.
Templates
Crie templates de mensagens reutilizáveis para push, e-mail e SMS.
Jornadas
Crie fluxos de mensagens multicanal automatizados acionados pelo comportamento do usuário.
Fluxos de Eventos
Exporte eventos de mensagens em tempo real para plataformas externas via webhooks.
Segmentação
Crie segmentos de audiência com base em tags, comportamento e propriedades do usuário.
Gatilhos de Mensagens no Aplicativo
Controle quando e como as mensagens no aplicativo são exibidas para os usuários.