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