Extensión de videoconferencia

Run in Postman

Con la API de videoconferencias, puedes configurar una aplicación pública para dar a los usuarios de HubSpot la capacidad de agregar un enlace a una videoconferencia al crear una reunión, similar a la integración con Google Meet y con Zoom. El uso de esta API implicará lo siguiente:

Debes configurar tu aplicación pública con los webhooks de la extensión de videoconferencias. Tendrás que configurar tu aplicación con las URI que HubSpot usará para notificarte cuando se estén creando, actualizando o eliminando reuniones.
Debes ajustar un back-end personalizado para gestionar la creación de reuniones y actualizar los webhooks.
Si fuera necesario, debes hacer ajustes en tu back-end para gestionar los webhooks de verificación de la identidad del usuario.

Todas las solicitudes a la API de videoconferencias deben autenticarse usando la clave de la API de desarrollador de tu cuenta. Puedes incluir la clave en un parámetro hapikey de consulta al final de la URL de la solicitud. Puedes encontrar la clave de la API de desarrollador en tu cuenta de desarrollador.

Requisitos previos

Antes de comenzar, asegúrate de haber creado una cuenta de desarrollador y una aplicación pública dentro de ella.

Configurar URLs de webhooks

Para que HubSpot sepa dónde enviar notificaciones cuando se creen, actualicen o eliminen reuniones, primero debes configurar las URL de los webhooks de la extensión. Para ello, envía una solicitud PUT a /crm/v3/extensions/videoconferencing/settings/{appId}?hapikey=YOUR_HUBSPOT_DEVELOPER_API_KEY. En el cuerpo de la solicitud, deberás incluir el campo createMeetingUrl para definir la URL que HubSpot enviará a las cargas útiles de creación de reuniones del webhook. Opcionalmente, puedes incluir URLs de webhooks adicionales. Estos valores pueden actualizarse posteriormente usando la misma URL de solicitud.

// Example request

{
  "createMeetingUrl": "https://example.com/create-meeting",
  "updateMeetingUrl": "https://example.com/update-meeting",
  "deleteMeetingUrl": "https://example.com/delete-meeting"
}

Campo	Tipo	Descripción
`createMeetingUrl`	Cadena	La URL que HubSpot notificará cuando se cree una nueva reunión. Esta incluirá una carga útil JSON con los detalles de la reunión. La URL debe usar el protocolo `https`.
`updateMeetingUrl`	Cadena	La URL que HubSpot notificará cuando se actualice una reunión existente. Esta acción incluirá una carga útil JSON con los detalles actualizados de la reunión. La URL debe usar el protocolo `https`.
`deleteMeetingUrl`	Cadena	La URL que HubSpot notificará cuando se elimine una reunión existente. Incluirá un `conferenceId` de las reuniones eliminadas. La URL debe usar el protocolo `https`.
`userVerifyUrl`	Cadena	La URL que HubSpot utilizará para verificar que un usuario está en el sistema externo de videoconferencia.

Respuesta de ejemplo:

// Example 200 response
{
  "createMeetingUrl": "https://example.com/create-meeting",
  "updateMeetingUrl": "https://example.com/update-meeting",
  "deleteMeetingUrl": "https://example.com/delete-meeting"
}

Recuperar URLs de webhooks

Para recuperar URLs de webhook configuradas para una aplicación existente, haz una solicitud GET a /crm/v3/extensions/videoconferencing/settings/{appId}. La respuesta incluirá las URL de webhooks configuradas en ese momento.

// Example 200 response
{
  "createMeetingUrl": "https://example.com/create-meeting",
  "updateMeetingUrl": "https://example.com/update- meeting",
  "deleteMeetingUrl": "https://example.com/delete-meeting",
  "userVerifyUrl": "https://example.com/user-verify"
}

Cargas útiles de webhooks

Una vez que se configuran las URL de los webhook, HubSpot enviará cargas útiles a esas URL cuando ocurra un evento de creación, actualización o eliminación de reuniones.

Todos los webhooks enviados por HubSpot están firmados por HMAC usando el secreto de tu aplicación. Puedes obtener más información a este respecto en la documentación de seguridad de webhooks (el resto de la página no hace referencia a estos webhooks de la extensión de videoconferencia).

Webhook de creación de reuniones

Cuando se crea una reunión, HubSpot enviará una solicitud a la URL especificada en el campo createMeetingUrl. La carga útil de la solicitud incluye información sobre la cuenta de HubSpot, el usuario asociado de HubSpot y los detalles de la reunión.

// Example payload
{
  "portalId": 123123,
  "userId": 123,
  "userEmail": "test.user@example.com",
  "topic": "A Test Meeting",
  "source": "MEETINGS",
  "startTime": 1534197600000,
  "endTime": 1534201200000
}

Campo	Tipo	Descripción
`portalId`	Número	El ID de la cuenta de HubSpot de la que proviene la solicitud.
`userId`	Número	El ID del usuario de HubSpot asignado a la reunión.
`userEmail`	Cadena	La dirección de correo electrónico del usuario de HubSpot asignado a la reunión.
`topic`	Cadena	El título de la reunión.
`source`	Cadena	Indica dónde se creó la reunión. Puede ser cualquiera de las siguientes opciones: `MEETINGS`: la reunión se creó a partir de una página de programación de reuniones. `MANUAL`: la reunión se creó manualmente a partir de un registro del CRM.
`startTime`	Número	La hora de inicio de la reunión. en milisegundos epoch.
`endTime`	Número	La hora de finalización de la reunión, en milisegundos epoch.

Para gestionar correctamente este webhook, debes generar una videoconferencia de esta reunión (o vincularla a una línea de conferencias existente) y responder con información sobre dicha conferencia. Los campos previstos en la respuesta son:

conferenceId: un ID único asociado con la conferencia en este evento. Este ID debe ser globalmente único dentro de tu sistema. HubSpot devolverá este ID en el webhook de actualización.
conferenceUrl: la URL que los usuarios pueden utilizar para unirse a la conferencia.
conferenceDetails: invitación en texto sin formato. Debe describir cómo los asistentes pueden acceder a la videoconferencia de este evento. Las nuevas líneas se mantendrán en las representaciones de este texto, pero no puede usarse ningún otro formato.

Por ejemplo, la respuesta podría tener el siguiente aspecto:

//example response
{
  "conferenceId": "some-unique-id",
  "conferenceUrl": "https://example.com/join",
  "conferenceDetails": "Click here to join: https://example.com/join"
}

Webhook de actualización de reuniones

Si especificaste un updateMeetingUrl, HubSpot enviará esta URI a una solicitud cuando se hayan modificado detalles relevantes de una reunión. Esta notificación es necesaria si necesitas mantener siempre al día el tema o los horarios de una videoconferencia. La carga útil de la solicitud incluye información sobre la cuenta de HubSpot, el usuario asociado de HubSpot y los detalles de la reunión.

//example request
{
  "conferenceId": "some-unique-id",
  "userId": 123,
  "userEmail": "test.user@example.com",
  "portalId": 123123,
  "topic": "A Test Meeting (updated)",
  "startTime": 1534197600000,
  "endTime": 1534201200000
}

Campo	Tipo	Descripción
`conferenceId`	Cadena	El identificador único de la conferencia, proporcionado por la integración en la respuesta al webhook de creación de la reunión.
`userId`	Número	El ID del usuario de HubSpot asignado a la reunión. Siempre será el mismo usuario que el de la carga útil de la creación de la reunión.
`userEmail`	Cadena	La dirección de correo electrónico del usuario de HubSpot asignado a la reunión. Siempre será el mismo usuario que el de la carga útil de la creación de la reunión.
`portalId`	Número	El ID de la cuenta de HubSpot de la que proviene la solicitud.
`topic`	Cadena	El título de la reunión.
`startTime`	Número	La hora de inicio de la reunión, en milisegundos epoch.
`endTime`	Número	La hora de finalización de la reunión, en milisegundos epoch.

No se requiere un cuerpo de respuesta al responder a estas solicitudes. Solo se requiere un código de respuesta 200 o 204 para indicar a HubSpot que este webhook se recibió correctamente.

Webhook de eliminación de una reunión

Cuando se elimine una reunión en HubSpot, se enviará una solicitud a la URL especificada en el campo deleteMeetingUrl. La carga incluirá el conferenceId de la reunión eliminada.

// Example payload
{
  "conferenceId": "some-unique-id"
}

No se requiere un cuerpo de respuesta al responder a estas solicitudes. Solo se requiere un código de respuesta 200 o 204 para indicar a HubSpot que este webhook se recibió correctamente.

Webhook de verificación de usuario

Los sistemas de HubSpot siempre se comunican contigo sobre sus usuarios en términos de su ID de usuario de HubSpot y su dirección de correo electrónico de cuenta de HubSpot. Puede darse el caso de que un usuario del sistema de HubSpot pueda estar en tu sistema con una dirección de correo electrónico o un identificador diferente. Antes de que HubSpot haga una llamada a tu sistema para crear, actualizar o eliminar un enlace de conferencia de video, primero verificará la configuración de la aplicación en un campo userVerifyUrl. Si esa URL ha sido definida, HubSpot la llamará para obtener tu identificador de usuario nativo. Luego enviará ese identificador como la dirección de correo electrónico del usuario en la llamada subsiguiente. Si no configuras esta URL, HubSpot asumirá siempre que la identidad del usuario está verificada. Este ajuste es opcional y tú debes determinar si es necesario. Si necesitas mantener un mapeo de usuarios dentro de tu sistema, quizá lo mejor sea asociar el ID del usuario de HubSpot o su correo electrónico a tu ID de usuario interno en cada llamada. La carga útil de este webhook contiene el ID de la cuenta de HubSpot y la dirección de correo electrónico del usuario.

//example request
{
  "portalId": 123123,
  "userEmail": "test.user@example.com"
}

Puedes volver a usar una respuesta 200 o cualquier código de error (por ejemplo, 404 sería un código adecuado). Si devuelves una respuesta 200, debes devolver una carga que contenga la nueva identificación que debemos usar en lugar de la dirección de correo electrónico:

//example response
{
  "id": "any-string-id"
}

Cuenta y configuración

Gestión de aplicaciones

Autenticación

Automatización

CMS

Preferencias de comunicación

Conversaciones

CRM

Eventos

Archivos

Marketing

Programador

Webhooks

Extensión de videoconferencia

Run in Postman

Requisitos previos

Configurar URLs de webhooks

Recuperar URLs de webhooks

Cargas útiles de webhooks

Webhook de creación de reuniones

Webhook de actualización de reuniones

Webhook de eliminación de una reunión

Webhook de verificación de usuario

Run in Postman

​Requisitos previos

​Configurar URLs de webhooks

​Recuperar URLs de webhooks

​Cargas útiles de webhooks

​Webhook de creación de reuniones

​Webhook de actualización de reuniones

​Webhook de eliminación de una reunión

​Webhook de verificación de usuario

Requisitos previos

Configurar URLs de webhooks

Recuperar URLs de webhooks

Cargas útiles de webhooks

Webhook de creación de reuniones

Webhook de actualización de reuniones

Webhook de eliminación de una reunión

Webhook de verificación de usuario