Version de l’API: 4.x dernière version 3.x

Vous consultez la documentation de l’API pour BigBlueButton 3.x. La version actuelle est BigBlueButton 4.x. Vous prévoyez une mise à niveau ? Le guide de migration répertorie toutes les modifications à apporter à vos appels API.

Chapitre 7 GET POST

getJoinUrl – Générer l’URL de participation

Le point de terminaison getJoinUrl génère une nouvelle URL de jonction pour un utilisateur qui a déjà rejoint une réunion. Cela permet au même utilisateur d'ouvrir des sessions supplémentaires — par exemple sur un deuxième écran ou après un changement d'appareil — sans se réauthentifier via le flux standard join. BBB 3.0+

Point de terminaison

GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?<parameters>

Ce point de terminaison utilise l'authentification session-token au lieu du mécanisme standard de somme de contrôle shared-secret. L'utilisateur doit avoir déjà rejoint via le point de terminaison join et détenir un sessionToken valide.

Contrairement aux points de terminaison de l’API BigBlueButton protégés par une somme de contrôle, qui renvoient XML, ce point de terminaison renvoie du JSON.

Paramètres requis

Paramètre Type Obligatoire Par défaut Description
sessionToken String Oui — Le sessionToken de l'utilisateur pour lequel une nouvelle URL de jonction doit être générée.

Paramètres facultatifs

Paramètre Type Obligatoire Par défaut Description
replaceSession Boolean Non false Lorsqu’il est défini sur true, la session d’origine est invalidée et remplacée par la nouvelle (transfert de session).
sessionName String Non — Un nom descriptif pour la nouvelle session.
enforceLayout String Non — Remplacer la mise en page de la nouvelle session.
userdata-* String Non — Données utilisateur personnalisées pour la nouvelle session. Les clés doivent être préfixées par userdata-.

Cas d’usage

  • Scénarios hybrides — un modérateur utilise un écran pour la présentation et un second écran pour la vue participant.
  • Changement d’appareil — un utilisateur passe de son ordinateur de bureau à une tablette pendant une réunion.
  • Configurations multi-écrans — une salle de conférence avec plusieurs écrans affichant différentes mises en page.

Comportement

La nouvelle session partage l’identité de l’utilisateur avec la session d’origine. L’utilisateur n’apparaît qu’une seule fois dans la liste des participants.

Sans replaceSession, les deux sessions existent en parallèle.

Avec replaceSession=true, la session d’origine est invalidée et l’utilisateur est transféré de manière transparente vers la nouvelle session.

Exemple de requête

GET https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?sessionToken=replace-with-session-token&sessionName=SecondScreen&enforceLayout=PRESENTATION_FOCUS

Exemple de réponse (succès)

{
  "response": {
    "returncode": "SUCCESS",
    "message": "Join URL provided successfully.",
    "url": "https://api-guide.bbbserver.com/bigbluebutton/api/join?...&checksum=replace-with-checksum"
  }
}

Réponses d’erreur

Lorsqu'une requête échoue, le point de terminaison renvoie un objet JSON avec un message d'erreur descriptif :

{
  "response": {
    "returncode": "FAILED",
    "message": "<error message>"
  }
}
Message Signification
You must provide a session token Le paramètre sessionToken est manquant.
Invalid session token Le sessionToken est invalide ou a expiré.
Invalid Session La requête ne contient pas le cookie de session HTTP créé par join, et la réunion n’autorise pas les requêtes sans session (allowRequestsWithoutSession, valeur par défaut : false).
Access denied L’utilisateur est introuvable ou n’a pas l’autorisation requise.
Meeting not found La réunion n’existe pas ou n’est plus en cours.

Dans BigBlueButton 3.0, seul Meeting not found est renvoyé en tant qu’erreur JSON. Pour les autres erreurs répertoriées ci-dessus, le point de terminaison n’envoie aucune réponse JSON.

Liste de blocage Userdata

Lors de l'utilisation de paramètres userdata-* avec getJoinUrl, une liste de blocage configurable (getJoinUrlUserdataBlocklist) restreint certaines clés userdata pour les utilisateurs non modérateurs :

  • Si la liste de blocage contient la valeur "all", tous les paramètres userdata sont bloqués pour les observateurs.
  • Les modérateurs contournent la liste de blocage, sauf dans breakout rooms.
  • Le paramètre enforceLayout est toujours autorisé, quelle que soit la liste de blocage.

Le point de terminaison n'est disponible que lorsque l'utilisateur détient déjà un sessionToken valide — c'est-à-dire qu'il doit d'abord avoir rejoint la réunion via le point de terminaison standard join. Les jetons expirés sont rejetés.

Pour les cas d’utilisation de changement d’appareil, définissez replaceSession=true afin de transférer la session de manière transparente vers le nouvel appareil. Cela évite d’avoir une session obsolète sur l’ancien appareil qui pourrait prêter à confusion dans la liste des participants.

Foire aux questions

Non. Contrairement à la plupart des points de terminaison API BigBlueButton, getJoinUrl utilise l'authentification session-token. Vous transmettez le paramètre sessionToken au lieu de calculer une somme de contrôle avec le secret partagé.

Non. L'utilisateur doit avoir déjà rejoint via le point de terminaison standard join et détenir un sessionToken valide et actif. Ce point de terminaison ne peut pas être utilisé pour créer les URL de jonction initiales.

Les deux sessions — l’originale et la nouvelle — existeront en parallèle. L’utilisateur n’apparaît qu’une seule fois dans la liste des participants, mais les deux fenêtres du navigateur ou appareils restent actifs.

Comme les autres points de terminaison reposant sur un jeton de session et utilisés en interne par le client (stuns, learningDashboard), getJoinUrl renvoie JSON. Les points de terminaison de l’API protégés par une somme de contrôle renvoient XML.

Le point de terminaison getJoinUrl a été introduit dans BigBlueButton 3.0. Il n'est pas disponible dans les versions antérieures.

Pas nécessairement. Une liste de blocage configurable peut restreindre certaines clés userdata pour les utilisateurs non modérateurs. Si la liste de blocage est définie sur "all", aucun paramètre userdata n'est transmis aux observateurs. Les modérateurs contournent la liste de blocage sauf dans breakout rooms.