SDK de extensiones de llamada

ResumenPuntos de terminación

El SDK de extensiones de llamada permite que las aplicaciones proporcionen una opción de llamadas personalizada a los usuarios de HubSpot directamente desde un registro en CRM. 

Una extensión de llamadas consta de tres componentes principales:

  1. El SDK de extensiones de llamada, un SDK de JavaScript que permite la comunicación entre tu aplicación y HubSpot.
  2. Los puntos finales de configuración de llamadas, los cuales se usan para establecer la configuración de llamadas para tu aplicación. Cada cuenta de HubSpot que conecta tu aplicación utilizará esta configuración.
  3. El iframe de llamadas, que es donde aparece tu aplicación para los usuarios de HubSpot y está configurado usando los puntos finales de la configuración de llamadas.

Para obtener más información sobre la experiencia de llamadas en la aplicación, revisa este artículo de la base de conocimientos. Una vez que la aplicación de la extensión de llamadas esté conectada a HubSpot, aparecerá como opción en el conmutador de llamadas cuando un usuario haga una llamada desde HubSpot.

Si no tienes una aplicación, puedes crear una desde tu cuenta de desarrollador de HubSpot. Si aún no tienes una cuenta de desarrollador de HubSpot, inicia sesión aquí.

Nota: actualmente solo se admiten llamadas salientes.

Ejecutar la aplicación de llamadas de demostración

Tienes la opción de probar el SDK de extensiones de llamada en dos aplicaciones de demostración diferentes:

  • El demo-minimal-js presenta una implementación mínima del SDK usando JavaScript, HTML y CSS. Ve cómo se instala el SDK en index.js.
  • El demo-react-ts presenta una implementación en tiempo real del SDK utilizando React, TypeScript y Styled Components para actuar como un plan para tu aplicación. Ve cómo se instala el SDK en useCti.ts.

Nota: estas aplicaciones de demostración no son aplicaciones de llamadas completamente funcionales y usan datos simulados para proporcionar una experiencia más realista.

Instalar la aplicación de llamadas de demostración

Puedes ejecutar las aplicaciones de demostración con o sin instalación. Para instalar la demostración en tu entorno local:

  1. Instala Node.js en tu entorno.
  2. Clona, bifurca o descarga el ZIP de este repositorio.
  3. Abre tu terminal y navega al directorio raíz del proyecto.
  4. Ejecuta uno de los siguientes comandos:
      • Para el demo-minimal-js:
cd demos/demo-minimal-js && npm i && npm start
  • Para el demo-react-ts:
cd demos/demo-react-ts && npm i && npm start

Estos cambiarán al directorio de demostración que desees e instalarán las dependencias de Node.js requeridas para el proyecto utilizando npm CLI e iniciarán la aplicación. 

Nota: el comando npm start abrirá automáticamente una nueva pestaña en tu navegador en https://localhost:9025/, y es posible que debas omitir una advertencia de "Tu conexión no es segura" para acceder a la aplicación.

Iniciar la aplicación de llamadas de demostración desde HubSpot

  1. Navega a tus registros:
    • Contactos: en tu cuenta de HubSpot, navega a Contactos > Contactos.
    • Empresa: en tu cuenta de HubSpot, navega a Contactos > Empresas.
  2. Abre la consola del desarrollador de tu navegador y ejecuta el siguiente comando:
    • Si completaste los pasos de instalación, para el demo-minimal-js o el demo-react-ts:
localStorage.setItem("LocalSettings:Calling:installDemoWidget", "local");
    • Si has omitido los pasos de instalación:
      • Para el demo-minimal-js:
localStorage.setItem("LocalSettings:Calling:installDemoWidget", "app:js");
  • Para el demo-react-ts:
localStorage.setItem("LocalSettings:Calling:installDemoWidget", "app");
  1. Actualiza la página y haz clic en el icono Llamar en la barra lateral izquierda. Haz clic en el menú desplegable Llamar desde y selecciona el nombre de la aplicación de demostración del paso 2 (por ejemplo, Demo App Local, Demo App JS, Demo App React). 
    call-app-in-record
  2. Haz clic en Llamar para ver cómo se integra la aplicación de demostración con HubSpot a través del SDK de extensiones de llamada. También puedes ver los eventos registrados en la consola del desarrollador de tu navegador.

calling-sdk-in-app

 

Instalar el SDK de extensiones de llamada en tu aplicación de llamadas

Para agregar el SDK de extensiones de llamada como dependencia de Node.js a tu aplicación de llamadas:

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

Flujo de mensajes típico entre la aplicación de llamadas y HubSpot

El SDK de extensiones de llamada expone una API simple para HubSpot y una aplicación de llamadas para intercambiar mensajes. Los mensajes se envían a través de métodos expuestos por el SDK y se reciben a través de eventHandlers.

La siguiente es una descripción de los eventos:

  1. Número de marcación: HubSpot envía el evento de número de marcación.
  2. Llamada saliente iniciada: la aplicación notifica a HubSpot cuando se inicia la llamada.
  3. Crear interacción: HubSpot crea una interacción de llamada con información mínima si la aplicación lo solicita.
  4. Interacción creada: HubSpot creó una interacción.
  5. EngagementId enviado a la aplicación: HubSpot envía el engagementId a la aplicación.
  6. Llamada finalizada: la aplicación notifica cuando finaliza la llamada.
  7. Llamada completada: la aplicación notifica cuando el usuario ha terminado con la experiencia de usuario de la aplicación.
  8. Actualizar interacción: la aplicación obtiene la interacción mediante el engagementId, luego combina y actualiza la interacción con detalles adicionales de la llamada. Más información sobre cómo actualizar una interacción de llamada.

Usar la SDK de extensiones de llamada

Crear un instancia

Para comenzar, crea una instancia del objeto CallingExtensions. Puedes definir el comportamiento de tu extensión proporcionando el objeto de una opción al crear tu instancia de extensiones. El objeto de esta opción proporciona un campo eventHandlers donde puedes especificar el comportamiento de tu extensión. El siguiente bloque de código ilustra las opciones disponibles y los controladores de eventos que puedes 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: event => { /* HubSpot has created an engagement for this call. */ }, onVisibilityChanged: event => { /* Call widget's visibility is changed. */ } } }; const extensions = new CallingExtensions(options);

Enviar mensajes a HubSpot

El objeto extensions proporciona los siguientes controladores de eventos que puedes invocar para enviar mensajes a HubSpot o para especificar otro comportamiento asociado. Consulta los siguientes ejemplos.

  • initialized: envía un mensaje que indica que el teléfono flexible está listo para la interacción. 
// 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: envía un mensaje que indica que el usuario ha iniciado sesión.
// 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: envía un mensaje que indica que el usuario ha cerrado sesión.
// Sends a message indicating that user has logged out extensions.userLoggedOut();
  • outgoingCall: envía un mensaje para notificar a HubSpot que se ha iniciado una llamada saliente. 
// 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: envía un mensaje para notificar a HubSpot que se está respondiendo una llamada saliente.
extensions.callAnswered();
  • callEnded: envía un mensaje para notificar a HubSpot que la llamada ha finalizado.
// 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: envía un mensaje para notificar a HubSpot que la llamada se ha completado.
// 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 the widget unless `hideWidget` is set to false. const data = { engagementId: number, hideWidget: boolean // (optional) defaults to true }; extensions.callCompleted(data);
  • sendError: envía un mensaje para notificar a HubSpot que la aplicación que llama ha encontrado un error.
// 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: envía un mensaje para notificar a HubSpot que la aplicación que llama necesita ser redimensionada.
// 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);

Recibir mensajes en HubSpot

El objeto extensions proporciona los siguientes controladores de eventos que puedes invocar al recibir mensajes en HubSpot o para especificar otro comportamiento asociado. Consulta los siguientes ejemplos.

  • onReady: mensaje que indica que HubSpot está listo para recibir mensajes.
// 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: mensaje que indica que el usuario ha activado una llamada saliente.
// 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: mensaje que indica que HubSpot ha creado datos onEngagementCreated.
// Message indicating that HubSpot has created onEngagementCreated(data) { const { /* A HubSpot created engagement id. */ engagementId: number, } = data; ... }
  • onVisibilityChanged: mensaje que indica si el usuario ha minimizado u ocultado la aplicación de llamada.
// Message indicating if user has minimized/hide the call widget onVisibilityChanged(data) { const { isMinimized, isHidden } = data; ... }
  • defaultEventHandler: controlador predeterminado para eventos.
// Default handler for events. defaultEventHandler(event) { console.info("Event received. Do you need to handle it?", event); }

Prueba tu aplicación desde un entorno local

Mientras estás en el proceso de crear tu Aplicación, puedes establecer manualmente la URL de iframe para tu navegador configurando un valor de localStorage. Esto te permite establecer una URL de localhost para las pruebas locales.

Para establecer el valor, abre las herramientas de desarrollador para tu navegador y ejecuta el siguiente comando JavaScript en la consola:

localStorage.setItem( "LocalSettings:Calling:CallingExtensions", '{"name": "<your intended widget name>", "url": "<your dev url or prod url>"}' );

El valor de nombre aparecerá en el encabezado de la aplicación de llamada y la url será la URL utilizada para iframe. Cuando este elemento esté establecido, el nombre que configuras aparecerá como opción para el proveedor de llamadas cuando hagas clic en el icono de llamada y el widget de llamada utilizará la url de iframe que configuraste.

Prepara tu aplicación para la producción

Para iniciar las extensiones de llamada iFrame para usuarios finales, HubSpot requiere los siguientes parámetros iFrame.

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

Usando tu herramienta de API (por ejemplo, Postman), envía esta carga útil a nuestra API de configuración. Asegúrate de obtener el APP_ID de tu aplicación de llamadas y la aplicación DEVELOPER_ACCOUNT_API_KEY de tu aplicación.

# 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 support GET and DELETE

La marca isReady indica si la aplicación está lista para la producción. Esta marca debe establecerse en false durante la prueba. 

Nota: esta marca o cualquier otro campo se puede sobrescribir a través de localStorage.
/** * Override the isReady flag for the call widget */ localStorage.setItem( "LocalSettings:Calling:CallingExtensions", '{"name": "<your intended widget name>", "isReady": true}' );

Publica tu aplicación de llamadas en el mercado de HubSpot

El paso final una vez que tu aplicación esté configurada es publicar tu aplicación de llamadas en el mercado de HubSpot. Puedes encontrar más detalles aquí. También puedes elegir no publicarlo en el mercado si esta aplicación es solo para uso interno.

Llamadas SDK | Preguntas frecuentes

How is user authentication handled?

La aplicación de llamada debe manejar la autentificación.

Is Calling Extensions hosted on a CDN?

No. Las extensiones de llamada son muy pequeñas y deben incluirse con la aplicación de llamadas. Si no es posible agrupar el archivo, el paquete npm incluye un paquete UMD compilado que se puede incluir en HTML (../node_modules/@hubspot/calling-extensions-sdk/dist/main.js).

When should an engagement be created versus updated?

Un usuario puede iniciar una llamada desde dentro de la interfaz de usuario de HubSpot y fuera de la interfaz de usuario de HubSpot (por ejemplo, aplicación móvil, número redirigido, etc.) Si se inicia una llamada desde la interfaz de usuario de HubSpot, HubSpot creará una interacción de llamada y enviará la interacción a la aplicación de llamada. Una vez que finaliza la llamada, la aplicación de llamadas puede actualizar esta interacción con detalles adicionales de la llamada. Si se inicia una llamada fuera de la interfaz de usuario de HubSpot, la aplicación debe crear la interacción de llamada.

What scopes are required as a part of the integration?

Se debe agregar contactos y alcances de cronología. Estos alcances aseguran que tu aplicación tenga acceso a contactos y la capacidad de crear y actualizar interacciones de llamadas en el CRM.

Can this functionality be added to an already existing application in the marketplace or do I create a new app?

Si ya tienes una aplicación existente que sirve para el caso de uso de llamadas, puedes agregar directamente esta funcionalidad a la aplicación existente. Todos los clientes que ya tienen tu aplicación instalada tendrán acceso a esta nueva funcionalidad sin tener que volver a instalar la aplicación.

Can I integrate my existing soft phone application in the SDK?

Sí, integrar tu aplicación de softphone existente debería ser muy fácil. Simplemente sigue los pasos de la documentación anterior para tener tu aplicación en funcionamiento.

Can users use multiple integrations at the same time?

Sí, los usuarios pueden usar múltiples integraciones de llamadas de terceros al mismo tiempo. Pueden usar el conmutador de proveedor que se presenta después de hacer clic en el botón de llamada para cambiar sin problemas entre proveedores.

Can free users install app integrations?

Sí, todos los usuarios pueden instalar la aplicación.

If a user already has my app installed, does the integration automatically show up?

Sí, si un usuario ya ha instalado tu aplicación y estás actualizando la misma aplicación con las extensiones de llamada, la integración aparecerá automáticamente. Actualmente, no hay manera de que el desarrollador habilite la aplicación de llamada solo para un subconjunto de clientes.

Can any user install or uninstall an app?

No, solo los usuarios que tengan los permisos necesarios pueden instalar y desinstalar una aplicación. Más información sobre cómo revisar los permisos de un usuario. 

Can I place a call from a custom object?

Sí, las integraciones de llamadas pueden realizar llamadas desde objetos personalizados siempre que solo usen el SDK para crear la llamada. Cada integración deberá verificar que solo usan el SDK para llamadas para crear llamadas y notificar a HubSpot en el evento outgoingCall.

Primero, verifica que la integración esté usando el SDK de llamadas para crear interacciones en el evento outgoingCall:

outgoingCall({ createEngagement: true })

Si createEngagement es verdadero, descubre cómo actualizar la información de tu aplicación aquí.

Este es el ejemplo de todo el 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);

Si necesitas más ayuda, visita el foro de asistencia técnica para desarrolladores de HubSpot.

¿Te resultó útil este artículo?
Con este formulario puedes enviar tu opinión sobre nuestros documentos para desarrolladores. Si tienes comentarios sobre el producto de HubSpot, puedes enviarlos al Foro de ideas.