SDK de extensiones de llamada

ResumenPuntos de terminación

Nota: Nuestros socios de la aplicación de llamadas ya no necesitan crear y actualizar las interacciones de llamadas manualmente; HubSpot lo hará por ellos. Más información aquí.

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 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 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. Las propiedades de interacción son propiedad de HubSpot y ya no es necesario crearlas o actualizarlas manualmente (ver resaltado).
Nota: la propiedad hideWidget se ignorará cuando el usuario esté en una cola de tareas con el tipo de tarea Call.
// 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: 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.
Nota: en 2024, HubSpot está dejando en desuso el evento onEngagementCreated en favor de onCreateEngagementSucceeded.
/** @deprecated */ // Message indicating that HubSpot has created onEngagementCreated(data) { const { /* A HubSpot created engagement id. */ engagementId: number, } = data; ... }
  • onCreateEngagementSucceeded o onCreateEngagementFailed (NUEVO): HubSpot finaliza un mensaje para notificar al socio de la aplicación que llama que la actualización de la interacción tuvo éxito o falló.
onCreateEngagementSucceeded: event => { /* HubSpot has created an engagement for this call. */ }, onCreateEngagementFailed: event => { /* HubSpot has failed to create an engagement for this call. */ }
  • onUpdateEngagementSucceeded o onUpdateEngagementFailed (NUEVO): HubSpot finaliza un mensaje para notificar al socio de la aplicación que llama que la creación de la interacción tuvo éxito o falló.
onUpdateEngagementSucceeded: event => { /* HubSpot has updated an engagement for this call. */ }, onUpdateEngagementFailed: event => { /* HubSpot has failed to update an engagement for this call. */ }
  • 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); }

Probar la aplicació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 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 el punto de terminación de configuración de llamadas

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

Nota: la marca isReady indica si la aplicación está lista para la producción. Esta marca debe establecerse en false durante la prueba.
# 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

Anular la configuración de tu extensión con localStorage

Puedes anular cualquiera de los ajustes de tu extensión para fines de prueba. Abre la consola del desarrollador de tu navegador desde una pestaña de HubSpot, edita la configuración a continuación y ejecuta el comando:

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

Prepara tu aplicación para la producción

Si ya has utilizado el punto de terminación POST al probar tu aplicación, puedes utilizar el punto de terminación PATCH para cambiar isReady a true. De lo contrario, usando tu herramienta de API (por ejemplo, Postman), envía esta carga útil la API de configuración de HubSpot. Asegúrate de obtener el APP_ID de tu aplicación de llamadas y la 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 supports PATCH, GET and DELETE

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?

Sí. Puedes instalar el SDK de extensiones de llamada a través de jsDeliver. Por ejemplo, para instalar calling-extensions-sdk@0.2.2, puedes usar https://cdn.jsdelivr.net/npm/@hubspot/calling-extensions-sdk@0.2.2/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.