SDK de extensões de chamada
Os SDK de extensões de chamada permitem que os aplicativos forneçam uma opção de chamadas personalizadas para os usuários do HubSpot diretamente de um registro no CRM.
Uma extensão de chamadas consiste em três componentes principais:
- O SDK de extensões de chamada, um SDK JavaScript que permite a comunicação entre seu aplicativo e o HubSpot.
- Os endpoints de configurações de chamada são usados para definir as configurações de chamadas para o seu aplicativo. Cada conta da HubSpot conectada ao seu aplicativo usará essas configurações.
- O iframe de chamadas, que é onde seu aplicativo aparece para usuários do HubSpot e é configurado usando as configurações de chamada.
Para obter mais informações sobre a experiência de chamadas no aplicativo, examine este artigo da base de conhecimento. Depois que o aplicativo ativado de extensão de chamada estiver conectado ao HubSpot, ele aparecerá como uma opção no alternador de chamadas sempre que um usuário fizer uma chamada do HubSpot.
Se não tiver um aplicativo, você pode criar um da sua conta do desenvolvedor da HubSpot. Se você ainda não tiver uma conta de desenvolvedor da HubSpot, faça login aqui.
Observação: apenas chamadas de saída são suportadas no momento.
Você tem a opção de testar o SDK de extensões de chamadas em dois aplicativos de demonstração diferentes:
- O demo-minimal-js apresenta uma implementação mínima do SDK usando JavaScript, HTML e CSS. Veja como o SDK é instanciado em index.js.
- O demo-react-ts apresenta uma implementação real do SDK usando React, TypeScript e componentes estilizados para atuar como um modelo para o aplicativo. Veja como o SDK é instanciado em useCti.ts.
Observação: esses aplicativos de demonstração não são aplicativos de chamadas totalmente funcionais e usam dados simulados para fornecer uma experiência mais realista.
Você pode executar os aplicativos de demonstração com ou sem instalação. Para instalar a demonstração no seu ambiente local:
- Instale o Node.js em seu ambiente.
- Clone, bifurque ou baixe o ZIP deste repositório.
- Abra o terminal e navegue até o diretório raiz do projeto.
- Execute um dos seguintes comandos:
- Para
demo-minimal-js
:
- Para
- Para
demo-react-ts
:
npm start
abrirá automaticamente uma nova guia no seu navegador em https://localhost:9025/, e talvez seja necessário ignorar um aviso "Sua conexão não é segura" para acessar o aplicativo.
- Acesse os registros:
- Contatos: na sua conta da HubSpot, acesse Contatos > Contatos.
- Empresa: na sua conta da HubSpot, acesse Contatos > Empresas.
- Abra o console de desenvolvedor do navegador e execute o seguinte comando:
- Se você tiver concluído as etapas de instalação, para
demo-minimal-js
oudemo-react-ts
:
- Se você tiver concluído as etapas de instalação, para
- Se você ignorou as etapas de instalação:
- Para
demo-minimal-js
:
- Para
- Para
demo-react-ts
:
- Atualize a página e clique no ícone Chamar na barra lateral esquerda. Clique no menu suspenso Chamar de e selecione o nome do aplicativo de demonstração da etapa 2 (por exemplo, Aplicativo de Demonstração Local, Aplicativo de Demonstração JS, Aplicativo de Demonstração React).
- Clique em Chamar para ver como o aplicativo de demonstração se integra ao HubSpot por meio do SDK de extensões de chamadas. Você também pode ver os eventos registrados no console de desenvolvedor do navegador.
Para adicionar o SDK de extensões de chamadas como uma dependência do Node.js no seu aplicativo de chamadas:
- Para npm, execute:
- Para yarn, execute:
O SDK de extensões de chamadas expõe uma API simples para a troca de mensagens entre o HubSpot e um aplicativo de chamadas. As mensagens são enviadas por meio de métodos expostos pelo SDK e recebidas por meio do eventHandlers
.
A seguir, uma descrição dos eventos:
- Número de discagem: o HubSpot envia o evento de número de discagem.
- Chamada de saída iniciada: o aplicativo notifica o HubSpot quando a chamada é iniciada.
- Criar engajamento: o HubSpot cria um engajamento de chamada com informações mínimas, se solicitado pelo aplicativo.
- Engajamento criado: o HubSpot criou um engajamento.
- EngagementId enviado para o aplicativo: o HubSpot envia o
engagementId
para o aplicativo. - Chamada encerrada: o aplicativo notifica quando a chamada é encerrada.
- Chamada concluída: o aplicativo notifica quando o usuário termina a experiência no aplicativo.
- Atualizar engajamento: o aplicativo busca o engajamento pelo
engagementId
e o mescla e atualiza com detalhes adicionais da chamada. Saiba mais sobre como atualizar um engajamento de chamada.
Para começar, crie uma instância do objeto CallingExtensions
. Você pode definir o comportamento da sua extensão fornecendo o objeto de uma opção ao criar sua instância de extensões. O objeto desta opção fornece um campo eventHandlers
onde você pode especificar o comportamento da sua extensão. O bloco de código a seguir ilustra as opções disponíveis e os manipuladores de eventos que você pode definir:
O objeto extensions
fornece os seguintes manipuladores de eventos que você pode invocar para enviar mensagens para o HubSpot ou para especificar outro comportamento associado. Veja os exemplos abaixo.
initialized
: envia uma mensagem indicando que o soft phone está pronto para interação.
userLoggedIn
: envia uma mensagem indicando que o usuário fez login.
userLoggedOut
: envia uma mensagem indicando que o usuário fez logout.
outgoingCall
: envia uma mensagem para notificar o HubSpot de que uma chamada de saída foi iniciada.
callAnswered
: envia uma mensagem para notificar o HubSpot de que uma chamada de saída está sendo atendida.
callEnded
: envia uma mensagem para notificar o HubSpot de que a chamada foi encerrada.
callCompleted
: envia uma mensagem para notificar o HubSpot de que a chamada foi concluída.
sendError
: envia uma mensagem para notificar o HubSpot de que o aplicativo de chamada encontrou um erro.
resizeWidget
: envia uma mensagem para notificar o HubSpot de que o aplicativo de chamada precisa ser redimensionado.
O objeto extensions
fornece manipuladores de eventos que você pode invocar ao receber mensagens no HubSpot ou para especificar outro comportamento associado. Veja os exemplos abaixo.
onReady
: mensagem indicando que o HubSpot está pronto para receber mensagens.
onDial
: mensagem indicando que o usuário acionou uma chamada de saída.
onEngagementCreated
: mensagem indicando que o HubSpot criou dadosonEngagementCreated
.
onVisibilityChanged
: mensagem que indica se o usuário minimizou ou ocultou o aplicativo de chamada.
defaultEventHandler
: manipulador padrão para eventos.
Durante o processo de criação do seu aplicativo, você pode definir manualmente o URL do iframe para seu navegador configurando o valor localStorage
. Isso permitirá definir um URL de localhost para testes locais.
Para definir o valor, abra as ferramentas de desenvolvedor do seu navegador e execute o seguinte comando JavaScript no console:
O valor do nome será o título que aparecerá no cabeçalho do aplicativo de chamada, e o url será o URL usado no iframe. Quando esse item é definido, o nome definido aparecerá como uma opção para o provedor de chamadas ao clicar no ícone Chamada, e o aplicativo de chamada usará o URL do iframe definido.
Usando sua ferramenta de API (por exemplo, Postman), envie essa carga útil para nossa API de configurações. Certifique-se de obter o APP_ID do seu aplicativo de chamadas e do DEVELOPER_ACCOUNT_API_KEY do aplicativo.
O sinalizador isReady
indica se o aplicativo está pronto para produção. Este sinalizador deve ser definido como falso durante o teste.
localStorage
.
Depois de configurar o aplicativo, a etapa final é listar seu aplicativo de chamadas no marketplace da HubSpot. Você pode encontrar mais detalhes aqui . Você também pode optar por não o listar no marketplace se for apenas para uso interno.
How is user authentication handled?
O aplicativo de chamadas deve lidar com a autenticação.
Is Calling Extensions hosted on a CDN?
Não. As Extensões de chamadas são muito pequenas e devem ser agrupadas em um aplicativo de chamadas. Se isso não for possível, o pacote npm incluirá um pacote UMD compilado que pode ser incluído no HTML (../node_modules/@hubspot/calling-extensions-sdk/dist/main.js).
When should an engagement be created versus updated?
Um usuário pode iniciar uma chamada diretamente da interface do HubSpot e fora dela (por exemplo, aplicativo móvel, número redirecionado etc.) Se uma chamada for iniciada a partir da interface do HubSpot, o HubSpot criará um engajamento de chamada e o enviará para o aplicativo de chamadas. Quando a chamada terminar, o aplicativo poderá atualizar esse engajamento com detalhes adicionais da chamada. Se uma chamada for iniciada fora da interface do usuário do HubSpot, o aplicativo deverá criar o engajamento de chamada.
What scopes are required as a part of the integration?
Adicionar contatos e escopos de linha do tempo são obrigatórios. Esses escopos garantem que o aplicativo tenha acesso aos contatos e à capacidade de criar e atualizar engajamentos de chamadas no CRM.
Can this functionality be added to an already existing application in the marketplace or do I create a new app?
Se você já tiver um aplicativo existente que atenda ao caso de uso de chamadas, poderá adicionar diretamente essa funcionalidade a ele. Todos os clientes que já têm o aplicativo instalado terão acesso a essa nova funcionalidade sem precisar instalá-lo novamente.
Can I integrate my existing soft phone application in the SDK?
Sim, é muito fácil integrar seu aplicativo de soft phone existente. Basta seguir as etapas na documentação acima para colocar seu aplicativo em funcionamento.
Can users use multiple integrations at the same time?
Sim, os usuários podem usar várias integrações de chamadas de terceiros ao mesmo tempo. Eles podem usar a opção de troca de provedor mostrada depois de clicar no botão de chamada para alternar entre os provedores.
Can free users install app integrations?
Sim, todos os usuários podem instalar o aplicativo.
If a user already has my app installed, does the integration automatically show up?
Sim, se um usuário já tiver instalado o aplicativo e você estiver atualizando esse mesmo aplicativo com as extensões de chamadas, a integração aparecerá automaticamente. Atualmente, não há maneira de o desenvolvedor habilitar o aplicativo de chamadas apenas para um subconjunto de clientes.
Can any user install or uninstall an app?
Não, apenas os usuários com as permissões necessárias podem instalar e desinstalar um aplicativo. Saiba mais sobre como analisar as permissões de usuário.
Can I place a call from a custom object?
Sim, as integrações podem iniciar chamadas de objetos personalizados, desde que somente usem o SDK para criar a chamada. Cada integração precisará confirmar que somente usa o SDK de chamadas para criar chamadas e notificar o HubSpot no evento outgoingCall
.
Primeiro, verifique se a integração usa o SDK de chamadas para criar engajamentos no evento outgoingCall:
Se createEngagement
for verdadeiro, saiba como atualizar as informações do seu aplicativo aqui.
Veja o exemplo para todo o evento outgoingCall
:
Se você ainda precisar de ajuda, visite o fórum de suporte ao desenvolvedor da HubSpot.
Agradecemos pelos seus comentários. Eles são muito importantes para nós.