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.

C'est le seul point de terminaison API BigBlueButton qui renvoie du JSON au lieu de XML.

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-* ↗ undocumented 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>",
        "sessionToken": "replace-with-session-token"
  }
}
Message Signification
Invalid Session Le sessionToken est invalide ou a expiré.
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.

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.

Notes pour les utilisateurs de bbbserver.de

Le point de terminaison getJoinUrl est disponible sur toutes les instances bbbserver.de exécutant BigBlueButton 3.0 ou une version ultérieure. Si votre intégration doit prendre en charge des scénarios multi-écrans ou de changement d'appareil, ce point de terminaison fournit une manière propre de générer des URL de jonction supplémentaires sans nécessiter un second appel join avec des identifiants modérateur.

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.

Il s'agit d'un choix de conception fait par les développeurs de BigBlueButton lors de l'introduction de ce point de terminaison dans la version 3.0. C'est le seul point de terminaison API qui renvoie JSON. Tous les autres points de terminaison continuent de renvoyer 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.