Extension de vidéoconférence

PrésentationPoints de terminaison

L'API de vidéoconférence permet aux utilisateurs de se connecter au flux de création des réunions dans HubSpot et d'ajouter des informations de vidéoconférence. L'utilisation de cette API comprend les étapes suivantes : 

  1. Configurez votre application avec les webhooks d'extensions de vidéoconférence. Vous fournirez des URI que HubSpot utilisera pour vous informer lorsque les clients créent ou mettent à jour des réunions. 
  2. Gérez les webhooks de création de réunions et, éventuellement, les webhooks de mise à jour des réunions. 
  3. Le cas échéant, gérez les webhooks de vérification d'identité des utilisateurs. 

API de paramètres 

Les développeurs utiliseront l'API de paramètres pour configurer une application existante. Vous pouvez utiliser le jeton d'accès de votre application privée pour authentifier la demande. 

 

Définition d'objet de paramètres 

Les paramètres présentent les champs suivants : 

createMeetingUrl : l'URL où nous enverrons des demandes de nouvelles vidéoconférences. Le protocole HTTPS doit être utilisé. 

updateMeetingUrl (facultatif) : l'URL où nous enverrons des mises à jour de réunions existantes. Cet élément est généralement appelé lorsque l'utilisateur modifie le sujet ou les heures d'une réunion. Le protocole HTTPS doit être utilisé. 

deleteMeetingUrl (facultatif) : l'URL où nous vous informerons des réunions qui ont été supprimées dans HubSpot. 

userVerifyUrl (facultatif) : l'URL utilisée pour vérifier qu'un utilisateur existe dans votre système. 

Créer ou mettre à jour des paramètres d'extension de vidéoconférence 

Exemple de demande :

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

Exemple de réponse : 

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

Exemple de réponse :

Les valeurs facultatives doivent être exclues de la demande. Des chaînes vides ou d'autres valeurs déboucheront probablement sur un comportement non désiré.

Récupérer des paramètres d'extension de vidéoconférence

Exemple de demande :

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

Exemple de réponse :

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

Créer un webhook de réunion

Lorsqu'une réunion est créée, HubSpot enverra une demande à createMeetingUri 

Exemple de demande :

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

Les champs de cette demande sont :

  • portalId : l'ID du compte HubSpot (appelé portail).
  • userId : l'ID unique de l'utilisateur HubSpot qui possède la réunion.
  • userEmail : l'adresse e-mail de l'utilisateur HubSpot qui possède la réunion.
  • topic : le sujet/titre de la réunion.
  • source : MEETINGS ou MANUAL, indiquant la fonctionnalité de réunion dans
    l'application HubSpot où la réunion a été créée. MEETINGS correspond à
    la fonction Lien de réunion et MANUAL correspond à une réunion créée dans
    le communicateur CRM.
  • startTime : l'heure de début de la réunion (en millisecondes epoch).
  • endTime : l'heure de fin de la réunion (en millisecondes epoch).

Pour gérer ce webhook, le développeur doit générer une vidéoconférence pour cette réunion (ou le lien vers une ligne de conférence existante) et répondre avec des informations concernant cette conférence.


Exemple de réponse :

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

Les champs indiqués dans cette réponse sont les suivants :

  • conferenceId : un identifiant unique associé à la conférence sur cet événement.
    Cet ID doit être globalement unique dans votre système. Nous renverrons cet ID
    dans le webhook de mise à jour.
  • conferenceUrl : le lien de connexion pour la conférence créée. Il peut être
    placé dans le champ Localisation des événements.
  • conferenceDetails : informations d'invitation en texte brut. Elles doivent décrire
    l'accès des participants à l'événement à la vidéoconférence pour cet
    événement. Les nouvelles lignes seront conservées dans les représentations de ce texte dans
    notre système, mais aucun autre formatage n'est pris en charge.

Mettre à jour le webhook

Si vous avez défini une valeur updateMeetingUri, HubSpot enverra à cet URI une demande en cas de modification de détails pertinents de la réunion. Cette notification est nécessaire si vous devez mettre à jour le sujet ou les heures d'une vidéoconférence.


Exemple de demande :

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
}

Les champs indiqués dans cette réponse sont les suivants :

  • conferenceId : l'ID unique de la conférence fournie par votre intégration dans la réponse au webhook de création de réunion.
  • userId : l'ID unique de l'utilisateur HubSpot qui possède la réunion. La valeur userId sera toujours la même que la demande de création de réunion.
  • userEmail : l'adresse e-mail de l'utilisateur HubSpot qui possède la réunion. La valeur userEmail sera toujours la même que la demande de création de réunion.
  • topic : le sujet/titre de la réunion.
  • startTime : l'heure de début de la réunion (en millisecondes epoch).

endTime : l'heure de fin de la réunion (en millisecondes epoch).

Aucun corps de réponse n'est requis lors de la réponse à ces demandes. HubSpot exige uniquement
un code de réponse 200 ou 204 pour informer de la bonne réception
de ce webhook.

Supprimer le webhook de réunion

Lorsqu'une réunion est supprimée dans HubSpot, nous enverrons une demande à deleteMeetingUri.
Exemple de demande :

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

Cette demande ne contient que la valeur conferenceId de la réunion supprimée.
Aucun corps de réponse n'est requis lors de la réponse à ces demandes. HubSpot exige uniquement
un code de réponse 200 ou 204 pour informer de la bonne réception
de ce webhook.

Webhook de vérification d'utilisateur

Les systèmes HubSpot communiqueront toujours avec vous sur les utilisateurs concernant leurs ID d'utilisateur HubSpot et leurs adresses e-mail de compte HubSpot. Il est possible qu'un utilisateur dans le système HubSpot existe dans votre système avec une adresse e-mail ou un identifiant différent.

Avant de passer un appel à votre système pour créer, mettre à jour ou supprimer un lien de vidéoconférence, nous vérifierons tout d'abord vos paramètres pour une valeur userVerifyUri. Si cet URI a été défini, nous effectuerons un appel pour récupérer votre identifiant d'utilisateur natif. Nous enverrons alors cet identifiant en tant qu'adresse e-mail de l'utilisateur dans
l'appel suivant.

Il existe des endroits dans l'application HubSpot où nous pouvons effectuer cet appel pour vérifier que l'utilisateur existe dans votre système avant d'afficher les composants de l'interface utilisateur avec lesquels il peut interagir, comme une sorte de vérification préalable. Si vous ne configurez pas cet URI, nous supposerons que l'identité de l'utilisateur est vérifiée.

Il vous revient de prendre en charge cette fonctionnalité. Si vous devez mettre à jour un mappage d'utilisateur dans votre système, vous pouvez simplement mapper l'ID d'utilisateur ou l'adresse e-mail à votre ID d'utilisateur interne sur chaque appel.


La demande ressemblera à ceci :

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

Vous pouvez renvoyer une erreur 200 ou tout autre code d'erreur (404 serait approprié). Si vous renvoyez une erreur 200, vous devriez renvoyer une charge utile contenant le nouvel ID que nous utilisons au lieu de l'adresse e-mail :

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

Signature du webhook

Tous les webhooks envoyés par HubSpot sont signés en HMAC avec le secret de votre application. Consultez la section Sécurité de cette page (le reste de la page Vue d'ensemble des webhooks ne s'applique pas aux webhooks d'extension de vidéoconférence).

Cet article vous a-t-il été utile ?
Ce formulaire est destiné à recueillir les avis sur la documentation pour les développeurs. Si vous souhaitez faire part de votre avis sur les produits HubSpot, veuillez le partager sur le forum des idéesde la communauté.