SDK de extensões de chamada

Visão geralEndpoints

Observação: nossos parceiros de aplicativos de chamadas não precisam mais criar e atualizar engajamentos de chamadas manualmente; o HubSpot fará isso por eles. Saiba mais aqui.

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:

  1. O SDK de extensões de chamada, um SDK JavaScript que permite a comunicação entre seu aplicativo e o HubSpot.
  2. 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.
  3. 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 de 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.

Execute a demonstração do aplicativo de chamadas

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.

Instalar a demonstração do aplicativo de chamadas

Você pode executar os aplicativos de demonstração com ou sem instalação. Para instalar a demonstração no seu ambiente local:

  1. Instale o Node.js em seu ambiente.
  2. Clone, bifurque ou baixe o ZIP deste repositório.
  3. Abra o terminal e navegue até o diretório raiz do projeto.
  4. Execute um dos seguintes comandos:
      • Para demo-minimal-js:
cd demos/demo-minimal-js && npm i && npm start
  • Para demo-react-ts:
cd demos/demo-react-ts && npm i && npm start

Isso mudará para o diretório de demonstração desejado, instalará as dependências Node.js necessárias para o projeto usando a CLI npm e iniciará o aplicativo. 

Observação: o comando 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.

Iniciar o aplicativo de chamadas do HubSpot

  1. Acesse os registros:
    • Contatos: na sua conta da HubSpot, acesse Contatos > Contatos.
    • Empresa: na sua conta da HubSpot, acesse Contatos > Empresas.
  2. 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 ou demo-react-ts:
localStorage.setItem("LocalSettings:Calling:installDemoWidget", "local");
    • Se você ignorou as etapas de instalação:
      • Para demo-minimal-js:
localStorage.setItem("LocalSettings:Calling:installDemoWidget", "app:js");
  • Para demo-react-ts:
localStorage.setItem("LocalSettings:Calling:installDemoWidget", "app");
  1. 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). 
    call-app-in-record
  2. 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.

calling-sdk-in-app

 

Instalar o SDK de extensões de chamadas no seu aplicativo de chamadas

Para adicionar o SDK de extensões de chamadas como uma dependência do Node.js no seu aplicativo de chamadas:

  • Para npm, execute:
npm i --save @hubspot/calling-extensions-sdk
  • Para yarn, execute:
yarn add @hubspot/calling-extensions-sdk

Fluxo de mensagens típico entre o aplicativo de chamadas e o HubSpot

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:

  1. Número de discagem: o HubSpot envia o evento de número de discagem.
  2. Chamada de saída iniciada: o aplicativo notifica o HubSpot quando a chamada é iniciada.
  3. Criar engajamento: o HubSpot cria um engajamento de chamada com informações mínimas, se solicitado pelo aplicativo.
  4. Engajamento criado: o HubSpot criou um engajamento.
  5. EngagementId enviado para o aplicativo: o HubSpot envia o engagementId para o aplicativo.
  6. Chamada encerrada: o aplicativo notifica quando a chamada é encerrada.
  7. Chamada concluída: o aplicativo notifica quando o usuário termina a experiência no aplicativo.
  8. 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.

Usar o SDK de extensões de chamada

Criar uma instância

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:

import CallingExtensions from "@hubspot/calling-extensions-sdk"; const options = { /** @property {boolean} debugMode - Whether to log various inbound/outbound debug messages to the console. If false, console.debug will be used instead of console.log */ debugMode: true | false, // eventHandlers handle inbound messages eventHandlers: { onReady: () => { /* HubSpot is ready to receive messages. */ }, onDialNumber: event => { /* HubSpot sends a dial number from the contact */ }, /** onEngagementCreated will be @deprecated in 2024 */ onEngagementCreated: event => { /* HubSpot has created an engagement for this call. */ }, onCreateEngagementSucceeded: event => { /* HubSpot has created an engagement for this call. */ } onEngagementCreatedFailed: event => { /* HubSpot has failed to create an engagement for this call. */ } onUpdateEngagementSucceeded: event => { /* HubSpot has updated an engagement for this call. */ }, onUpdateEngagementFailed: event => { /* HubSpot has failed to update an engagement for this call. */ } onVisibilityChanged: event => { /* Call widget's visibility is changed. */ } } }; const extensions = new CallingExtensions(options);

Enviar mensagens para o HubSpot

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. 
// The initialized call allows you to send a message indicating that the soft phone is ready for interaction. const payload = { // Whether a user is logged-in isLoggedIn: true|false, // Optionally send the desired widget size sizeInfo: { height: number, width: number } } extensions.initialized(payload);
  • userLoggedIn: envia uma mensagem indicando que o usuário fez login.
// Sends a message indicating that user has logged in // This message is only needed when user isn't loged in when initialized extensions.userLoggedIn();
  • userLoggedOut: envia uma mensagem indicando que o usuário fez logout.
// Sends a message indicating that user has logged out extensions.userLoggedOut();
  • outgoingCall: envia uma mensagem para notificar o HubSpot de que uma chamada de saída foi iniciada. 
// Sends a message to notify HubSpot that an outgoing call has started. const callInfo = { phoneNumber: string, // optional unless call is initiated by the widget createEngagement: true, // whether HubSpot should create an engagement for this call callStartTime: number // optional unless call is initiated by the widget }; extensions.outgoingCall(callInfo);
  • callAnswered: envia uma mensagem para notificar o HubSpot de que uma chamada de saída está sendo atendida.
extensions.callAnswered();
  • callEnded: envia uma mensagem para notificar o HubSpot de que a chamada foi encerrada.
// Sends a message to notify HubSpot that the call has ended. // After receiving the call ended event, the user can navigate away, can close the call widget. extensions.callEnded();
  • callCompleted: envia uma mensagem para notificar o HubSpot de que a chamada foi concluída. As propriedades de engajamento são de propriedade da HubSpot e não precisam mais ser criadas ou atualizadas manualmente (consulte o destaque).
Observação: a propriedade hideWidget será ignorada quando o usuário estiver em uma fila de tarefas com o tipo de tarefaCall.
// Sends a message to notify HubSpot that the call has completed. // After receiving the call completed event, HubSpot will // 1) insert the engagement into the timeline // 2) set the default associations on the engagement // 3) closes the widget unless `hideWidget` is set to false. // 4) update the engagement with any engagement properties const data = { engagementId: number, hideWidget: boolean, // (optional) defaults to true engagementProperties?: { [key: string]: string } // opt in to hs owned engagements by adding properties in https://developers.hubspot.com/docs/api/crm/calls#properties extensions.callCompleted(data);
  • sendError: envia uma mensagem para notificar o HubSpot de que o aplicativo de chamada encontrou um erro.
// Sends a message to notify HubSpot that the call widget has encountered an error. // After receiving the sendError event, HubSpot will display an alert popup to the user with the error message provided. const data = { message: string // error message to be displayed in the alert popup }; extensions.sendError(data);
  • resizeWidget: envia uma mensagem para notificar o HubSpot de que o aplicativo de chamada precisa ser redimensionado.
// Sends a message to notify HubSpot that the call widget needs to be resized. // After receiving the resizeWidget event, HubSpot will use the provided height and width to resize the call widget. const data = { height: boolean // desired height of the call widget width: number, // desired width of the call widget }; extensions.resizeWidget(data);

Receber mensagens do HubSpot

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.
// Message indicating that HubSpot is ready to receive messages onReady() { // Send initialized message to HubSpot to indicate that the call widget is also ready extensions.initialized(payload); ... }
  • onDial: mensagem indicando que o usuário acionou uma chamada de saída.
// Message indicating that user has triggered an outbound call onDialNumber(data) { const { /* The phone nubmer to dial */ phoneNumber: string, /* The id of the logged in user. */ ownerId: number, /* The id of the hubspot account */ portalId: number, /* HubSpot object Id of the phoneNumber */ objectId: number, /* HubSpot object type of the phoneNumber */ objectType: CONTACT | COMPANY } = data; ... }
  • onEngagementCreated: mensagem indicando que o HubSpot criou dados onEngagementCreated.
Observação: a HubSpot descontinuará o evento onEngagementCreated e o substituirá por onCreateEngagementSucceeded em 2024.
/** @deprecated */ // Message indicating that HubSpot has created onEngagementCreated(data) { const { /* A HubSpot created engagement id. */ engagementId: number, } = data; ... }
  • onCreateEngagementSucceeded ou onCreateEngagementFailed (NOVO): o HubSpot envia uma mensagem para notificar o parceiro do aplicativo de chamada de que a atualização do engajamento foi bem-sucedida ou falhou.
onCreateEngagementSucceeded: event => { /* HubSpot has created an engagement for this call. */ }, onCreateEngagementFailed: event => { /* HubSpot has failed to create an engagement for this call. */ }
  • onUpdateEngagementSucceeded ou onUpdateEngagementFailed (NEW): o HubSpot envia uma mensagem para notificar ao parceiro do aplicativo de chamada de que a criação do engajamento foi bem-sucedida ou falhou.
onUpdateEngagementSucceeded: event => { /* HubSpot has updated an engagement for this call. */ }, onUpdateEngagementFailed: event => { /* HubSpot has failed to update an engagement for this call. */ }
  • onVisibilityChanged: mensagem que indica se o usuário minimizou ou ocultou o aplicativo de chamada.
// Message indicating if user has minimized/hide the call widget onVisibilityChanged(data) { const { isMinimized, isHidden } = data; ... }
  • defaultEventHandler: manipulador padrão para eventos.
// Default handler for events. defaultEventHandler(event) { console.info("Event received. Do you need to handle it?", event); }

Teste seu aplicativo

Para iniciar as extensões de chamadas do iFrame para usuários finais, o HubSpot exige os parâmetros do iFrame descritos abaixo.

{ name: string /* The name of your calling app to display to users. */, url: string /* The URL of your calling app, built with the Calling Extensions SDK */, width: number /* The iFrame's width */, height: number /* The iFrame's height */, isReady: boolean /* Whether the widget is ready for production (defaults to true) */, supportsCustomObjects : true /* Whether calls can be placed from a custom object */ }

Usar o ponto de extremidade das configurações de chamada

Usando sua ferramenta de API (por exemplo, Postman), envie a carga útil a seguir para a API de configurações do HubSpot. Certifique-se de obter o APP_ID do seu aplicativo de chamadas e o DEVELOPER_ACCOUNT_API_KEY do aplicativo.

Observação: o sinalizador isReady indica se o aplicativo está pronto para produção. Este sinalizador deve ser definido como falso durante o teste.
# Example payload to add the call widget app settings curl --request POST \ --url 'https://api.hubapi.com/crm/v3/extensions/calling/APP_ID/settings?hapikey=DEVELOPER_ACCOUNT_API_KEY' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{"name":"demo widget","url":"https://mywidget.com/widget","height":600,"width":400,"isReady":false}' # Note that this endpoint also supports PATCH, GET and DELETE

Substitua as configurações de extensão utilizando localStorage

Você pode substituir qualquer uma das suas configurações de extensão para fins de teste. Abra o console de desenvolvedor do navegador a partir de uma guia do HubSpot, edite as configurações abaixo e execute o comando:

const myExtensionSettings = { isReady: true, name: "My app name", url: "My local/qa/prod URL", }; localStorage.setItem( "LocalSettings:Calling:CallingExtensions", myExtensionSettings, );

Preparar o aplicativo para produção

Se você já usou o ponto de extremidade POST ao testar seu aplicativo, poderá usar o ponto de extremidade PATCH para alterar isReady para true. Caso contrário, usando sua ferramenta de API (por exemplo, Postman), envie esta carga útil para a API de configurações da HubSpot. Certifique-se de obter o APP_ID do seu aplicativo de chamadas e o DEVELOPER_ACCOUNT_API_KEY do aplicativo.

# Example payload to add the call widget app settings curl --request POST \ --url 'https://api.hubapi.com/crm/v3/extensions/calling/APP_ID/settings?hapikey=DEVELOPER_ACCOUNT_API_KEY' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{"name":"demo widget","url":"https://mywidget.com/widget","height":600,"width":400,"isReady":true}' # Note that this endpoint also supports PATCH, GET and DELETE

Publicar o aplicativo de chamadas no marketplace da HubSpot

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.

SDK de chamadas | Perguntas frequentes

How is user authentication handled?

O aplicativo de chamadas deve lidar com a autenticação.

Is Calling Extensions hosted on a CDN?

Sim. Você pode instalar o SDK de Extensões de Chamada via jsDeliver. Por exemplo, para instalar calling-extensions-sdk@0.2.2, você pode usar https://cdn.jsdelivr.net/npm/@hubspot/calling-extensions-sdk@0.2.2/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:

outgoingCall({ createEngagement: true })

Se createEngagement for verdadeiro, saiba como atualizar as informações do seu aplicativo aqui.

Veja o exemplo para todo o evento outgoingCall:

const callInfo = { phoneNumber: string, // optional unless call is initiated by the widget createEngagement: true // whether HubSpot should create an engagement for this call callStartTime: number // optional unless call is initiated by the widget }; extensions.outgoingCall(callInfo);

Se você ainda precisar de ajuda, visite o fórum de suporte ao desenvolvedor da HubSpot.

Este artigo foi útil?
Este formulário deve ser usado apenas para fazer comentários sobre esses artigos. Saiba como obter ajuda para usar a HubSpot..