Extensión de conferencia en video

ResumenPuntos de terminación

La API de conferencia en video ofrece a los integradores la capacidad de adaptarse al flujo de creación de reuniones dentro de HubSpot y agregar información de conferencias de video. El uso de esta API implicará los siguientes pasos: 

  1. Configurar tu aplicación con webhooks de Extensiones de conferencia en video. Ofrecerás URI a HubSpot que HubSpot utilizará para notificar en qué momento los clientes están creando o actualizando reuniones. 
  2. Manejar los webhooks de creación de reuniones y, opcionalmente, los webhooks de actualización de reuniones. 
  3. Manejar los webhooks de verificación de identidad de usuario, si es necesario. 

API de configuración 

Los desarrolladores usarán esta API de configuración para configurar una aplicación existente. Puedes usar el token de acceso de la app privada para autenticar la solicitud. 

 

Definición de objeto de configuración 

El objeto de configuración tiene los siguientes campos: 

createMeetingUri: la URI donde enviaremos solicitudes de conferencias en video nuevas. Esto debe usar el protocolo https. 

updateMeetingUri: (opcional) La URI donde enviaremos actualizaciones a las reuniones existentes. Por lo general, cuando el usuario cambia el tema o los horarios de una reunión. Esto debe usar el protocolo https. 

deleteMeetingUri: (opcional) La URI donde te notificaremos de reuniones que se han eliminado en HubSpot. 

userVerifyUri: (opcional) La URI que usaremos para verificar que un usuario existe en tu sistema. 

Crear o actualizar la configuración de la extensión de conferencia en video 

Solicitud de ejemplo:

PUT /crm/v3/extensions/videoconferencing/settings/{appId}

JSON 
//example request

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

Respuesta de ejemplo:

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

Respuesta de ejemplo:

Los valores opcionales deben excluir de la solicitud, proporcionar cadenas vacías u otros valores probablemente ocasionará comportamientos no deseados.

Obtener configuración de la extensión de conferencia en video

Solicitud de ejemplo:

GET /crm/v3/extensions/videoconferencing/settings/{appId}

Ejemplo de respuesta:

JSON 
// 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"
}

Webhook de crear reuniones

Cuando se crea una reunión, HubSpot enviará una solicitud a la createMeetingUri 

Solicitud de ejemplo:

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

Los campos de esta solicitud son:

  • portalId: el ID de la cuenta de HubSpot (llamada un portal).
  • userId: el ID único del usuario de HubSpot que posee la reunión.
  • userEmail: la dirección de correo electrónico del usuario de HubSpot que posee la reunión.
  • topic: el tema/título de la reunión.
  • source: MEETINGS o MANUAL, que indica la característica de reunión dentro de
    la aplicación HubSpot donde se ha creado la reunión. MEETINGS corresponde a
    la función «enlace de reunión» y MANUAL corresponde a una reunión creada en
    el Comunicador de CRM.
  • startTime: la hora de inicio de la reunión (en milisegundos de epoch)
  • endTime: la hora de finalización de la reunión (en milisegundos de epoch)

Para manejar correctamente este webhook, el desarrollador debe generar una conferencia en video para esta reunión (o enlace a una línea de conferencias existente) y responder con información sobre esta conferencia.


Ejemplo de respuesta:

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

Los campos previstos en esta respuesta son:

  • conferenceId: un ID único asociado con la conferencia en este evento.
    Este ID debe ser globalmente único dentro de tu sistema. Devolveremos este ID
    en el webhook de actualización.
  • conferenceUrl: el enlace para unirse a la conferencia creada. Esto puede estar
    en el campo de eventos «location».
  • conferenceDetails: información de "invitation" en texto sin formato. Esto debe describir
    cómo los asistentes del evento pueden acceder a la conferencia en video para este
    evento. Las nuevas líneas se mantendrán en representaciones de este texto dentro de nuestro
    sistema, pero no se admiten otros formatos.

Webhook de actualizar reuniones

Si especificaste un updateMeetingUri, 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 el tema o los horarios más actualizados para una conferencia en video.


Solicitud de ejemplo:

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

Los campos previstos en esta respuesta son:

  • conferenceId: el ID único de la conferencia proporcionado por tu integración en la respuesta al webhook de crear reunión.
  • userId: el ID único del usuario de HubSpot que posee la reunión. Esto siempre será el mismo userId que la solicitud de crear reunión.
  • userEmail: la dirección de correo electrónico del usuario de HubSpot que posee la reunión. Esto siempre será el mismo usuario que la solicitud de crear reunión.
  • topic: el tema/título de la reunión.
  • startTime: la hora de inicio de la reunión (en milisegundos de epoch)

endTime: la hora de finalización de la reunión (en milisegundos de epoch)

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

Webhook de eliminar reunión

Cuando se elimine una reunión en HubSpot, enviaremos una solicitud a la deleteMeetingUri.
Solicitud de ejemplo:

JSON 
//example request
{
"conferenceId": "some-unique-id"
}

Esta solicitud solo contiene la conferenceId de la reunión que fue eliminada.
No se requiere un cuerpo de respuesta al responder a estas solicitudes. Solo necesitamos
un código de respuesta 200 o 204 para informarnos 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. Existe la posibilidad de que un usuario en el sistema de HubSpot pueda existir en tu sistema con una dirección de correo electrónico o un identificador diferente.

Antes de hacer una llamada a tu sistema para crear, actualizar o eliminar un enlace de conferencia web, primero verificaremos tu configuración para un userVerifyUri, y si esa URI ha sido configurada, te haremos una llamada para recuperar el identificador de usuario nativo. Luego enviaremos ese identificador como la dirección de correo electrónico del usuario en la
llamada subsiguiente.

Hay lugares en la aplicación de HubSpot donde podríamos hacer esta llamada para validar que el usuario existe en tu sistema antes de que mostremos componentes de UI con los que puede interactuar, como un tipo de verificación previa. Si no configuras esta URI, siempre asumiremos que la identidad del usuario está verificada.

Depende de ti si admites esta función. Si necesitas mantener un mapeo de usuarios dentro de tu sistema, tal vez desees mapear el ID de usuario de HubSpot o el correo electrónico a tu ID de usuario interno en cada llamada.


La solicitud se verá así:

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

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

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

Firma de webhook

Todos los webhooks enviados por HubSpot están firmados por HMAC usando el "secreto de la aplicación" de tu aplicación. Consulta la sección «Seguridad» de esta página: (El resto de esta página Resumen de webhooks no se aplica a estos webhooks de la extensión de conferencia en video)

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