Ignorar e ir ao conteúdo principal

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 pontos de extremidade 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 do desenvolvedor da HubSpot. Se você ainda não tiver uma conta de desenvolvedor da HubSpot, faça login aqui.

Você tem a opção de testar o SDK de extensões de chamadas em dois aplicativos de demonstração diferentes:

  • A demo-minimum-js CSS apresenta uma implementação mínima do SDK usando JavaScript, HTML e Veja como o SDK é instanciado em index.js.
  • demo-react-ts apresenta uma implementação real do SDK usando React, TypeScript e Styled Components para agir como um modelo para seu aplicativo. Veja como o SDK é instanciado em useCti.ts.

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:
  • Para demo-react-ts:

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.

  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:
  • Se você ignorou as etapas de instalação:
    • Para demo-minimal-js:
  • Para demo-react-ts:
  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

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. Você pode encontrar uma lista completa dos eventos disponíveis na seção Eventos.

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 atualizar um engajamento de chamada através da APIou através do SDK.

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:

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

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 de seu aplicativo de chamadas e seu aplicativo DEVELOPER_ACCOUNT_API_KEY.

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:

Depois de definir as configurações do seu aplicativo usando o configurações de endpoint de chamada , use o ponto de extremidade PATCH para alterar isReady para verdade.

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.

Eventos de chamadas disponíveis:

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.

Envia uma mensagem indicando que o soft phone está pronto para interação.

PropriedadeTipoDescrição
isLoggedInBooleanoCriar menus que se adaptam ao fato de o usuário estar conectado ou não.
engagementIdNúmeroUm ID de engajamento criado pelo HubSpot.
isAvailableNúmeroVerifica se um usuário está disponível ou não.

Publica a chamada em um canal conectado.

PropriedadeTipoDescrição
externalCallIdStringUm ID de chamada criado por um aplicativo de chamadas. Usado para habilitar as chamadas no help desk.
engagementIdNúmeroUm ID de engajamento criado pelo HubSpot.

Envia uma mensagem indicando que o usuário está disponível.

Envia uma mensagem indicando que o usuário não está disponível.

Envia uma mensagem indicando que o usuário fez login.

Envia uma mensagem indicando que o usuário efetuou logout.

Envia uma mensagem para notificar o HubSpot de que uma chamada de entrada foi iniciada.

PropriedadeTipoDescrição
externalCallIdNúmeroUm ID de chamada criado por um aplicativo de chamadas. Usado para habilitar as chamadas no help desk.
callStartTimeNúmeroHora de início da chamada, em milissegundos.
createEngagementBooleanoSe o HubSpot deve criar um engajamento para esta chamada. Quando verdadeiro, o HubSpot responderá com onCreateEngagementSucceeded ou onCreateEngagementFailed.
fromNumberStringO número do chamador. Parâmetro obrigatório.
toNumberStringO número de telefone do destinatário.

Envia uma mensagem para notificar o HubSpot de que uma chamada de saída foi iniciada.

PropriedadeTipoDescrição
callStartTimeNúmeroHora de início da chamada, em milissegundos.
createEngagementBooleanoSe o HubSpot deve criar um engajamento para esta chamada. Quando verdadeiro, o HubSpot responderá com onCreateEngagementSucceeded ou onCreateEngagementFailed.
toNumberStringO número de telefone do destinatário.
fromNumberStringO número do chamador. Parâmetro obrigatório.

Envia uma mensagem para notificar o HubSpot de que uma chamada de saída está sendo atendida.

PropriedadeTipoDescrição
externalCallIdStringUm ID de chamada criado por um aplicativo de chamadas. Usado para habilitar as chamadas no help desk.

Envia uma mensagem para notificar o HubSpot de que a chamada foi encerrada.

PropriedadeTipoDescrição
externalCallIdStringUm ID de chamada criado por um aplicativo de chamadas. Usado para habilitar as chamadas no help desk.
engagementIdNúmeroUm ID de engajamento criado pelo HubSpot.
callEndStatusEnumeraçãoO status da chamada uma vez encerrada. Status disponíveis:
  • INTERNAL_COMPLETED
  • INTERNAL_FAILED
  • INTERNAL_CANCELED
  • INTERNAL_BUSY
  • INTERNAL_NO_ANSWER
  • INTERNAL_REJECTED
  • INTERNAL_MISSED

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).

PropriedadeTipoDescrição
engagementIdNúmeroUm ID de engajamento criado pelo HubSpot.
hideWidgetBooleanoSe o widget deve ser ocultado quando a chamada é encerrada. Parâmetro opcional. Assume o padrão true.
engagementPropertiesStringAceite os engajamentos hs adicionando propriedades. Faz com que o HubSpot responda com onUpdateEngagementSucceeded ou onUpdateEngagementFailed.
externalCallIdNúmeroUm ID de chamada criado por um aplicativo de chamadas. Usado para habilitar as [chamadas no help desk.

Este evento é chamado ao navegar para um registro.

PropriedadeTipoDescrição
externalCallIdNúmeroUm ID de chamada criado por um aplicativo de chamadas. Usado para habilitar as [chamadas no help desk.
engagementIdNúmeroUm ID de engajamento criado pelo HubSpot.

Este evento é chamado ao navegar para um registro.

PropriedadeTipoDescrição
engagementIdNúmeroUm ID de engajamento criado pelo HubSpot.
objectCoordinatesCoordenadas do objetoReferências a portalId, objectId, e objectTypeID.

Envia uma mensagem para notificar o HubSpot de que o aplicativo de chamada encontrou um erro.

PropriedadeTipoDescrição
messageStringMensagem de erro a ser exibida no pop-up de alerta.

Envia uma mensagem para notificar o HubSpot de que o aplicativo de chamada precisa ser redimensionado.

PropriedadeTipoDescrição
heightNúmeroAltura desejada do widget da chamada.
widthNúmeroLargura desejada do widget da chamada.

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.

Mensagem indicando que o HubSpot está pronto para receber mensagens.

PropriedadeTipoDescrição
engagementIdNúmeroUm ID de engajamento criado pelo HubSpot.
iframeLocationEnumerarwidget: o widget de arrastar e soltar mostrado nas páginas de registro ao chamar o aplicativo não funciona suporte a chamadas de entrada.
remote: quadro na barra de navegação ao chamar o aplicativo que oferece suporte a chamadas de entrada.
window: iframe na janela de chamada quando o aplicativo de chamada oferece suporte a chamadas de entrada.
ownerIdString ou NúmeroO ID do usuário conectado (no HubSpot).
PortalIdNúmeroO ID da conta da HubSpot.
userIdNúmeroO ID do usuário da HubSpot.

Este evento será disparado quando um usuário no HubSpot fizer uma chamada. O evento onDialNumber fornecerá uma payload que inclui todos os campos pertinentes associados à chamada. Estes campos são detalhados na tabela abaixo:

PropriedadeTipoDescrição
phoneNumberStringO número de telefone da pessoa que foi chamada.
ownerIdString ou NúmeroO ID do usuário conectado (no HubSpot).
subjectIdNúmeroO ID do assunto.
objectIdNúmeroTipo de objeto do número de telefone.
objectTypeStringO tipo de objeto associado ao número de telefone discado (por exemplo, o número de telefone do contato ou da empresa). Os possíveis valores são "CONTACT" ou "COMPANY".
portalIdNúmeroO ID do portal da HubSpot.
countryCodeStringO código do país do número de telefone.
calleeInfoMatrizMais informações sobre o autor da chamada. Deve incluir o seguinte:
  • calleeID: number
  • calleeObjectTypeId: string
startTimestampNúmeroData/hora do início da chamada.
toPhoneNumberSrcStringO nome da ' propriedade dos números de telefone no HubSpot. A propriedade pode ser um valor de propriedade padrão ou uma propriedade personalizada. Por exemplo, um contato pode ter três números de telefone de contato, um pode ser rotulado Escritório, outro pode ser rotulado Pessoal e o outro, Celular.

Descontinuado. Em vez disso, use o filtro onCreateEngagementSucceeded.

PropriedadeTipoDescrição
engagementIdNúmeroUm ID de engajamento criado pelo HubSpot.

Este evento é chamado quando a navegação para um registro falha.

PropriedadeTipoDescrição
engagementIdNúmeroUm ID de engajamento criado pelo HubSpot.
objectCoordinatesCoordenadas do objetoReferências a portalId, objectId, e objectTypeID.

Este evento é chamado quando a publicação em um canal é bem-sucedida.

| Propriedade | Tipo | Descrição | | --- | --- | --- | --- | | engagementId | Número | Um ID de engajamento criado pelo HubSpot. | | externalCallId | String | Um ID de chamada criado por um aplicativo de chamadas. Usado para habilitar as chamadas no help desk | . |

Este evento é chamado quando a publicação em um canal falha.

PropriedadeTipoDescrição
engagementIdNúmeroUm ID de engajamento criado pelo HubSpot.
externalCallIdStringUm ID de chamada criado por um aplicativo de chamadas. Usado para habilitar as chamadas no help desk.

Este evento é chamado quando a correspondência do ID do chamador é bem-sucedida.

Este evento é chamado quando a correspondência do ID do chamador falha.

O HubSpot envia uma mensagem para notificar o parceiro do aplicativo de chamada de que a atualização do engajamento foi bem-sucedida.

O HubSpot envia uma mensagem para notificar ao parceiro do aplicativo de chamada de que a criação do engajamento falhou.

Mensagem que indica se o usuário minimizou ou ocultou o aplicativo de chamada.

Manipulador padrão para eventos.

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

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.

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.

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.

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.

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.

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.

Sim, todos os usuários podem instalar o aplicativo.

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.

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.

Sim, é possível criar uma propriedade personalizada utilizando a API de properties.

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: