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.
join – Rejoindre une réunion
Le point de terminaison join génère une URL qui permet à un utilisateur d'entrer dans une réunion BigBlueButton en cours. Par défaut, le navigateur redirige directement vers le client BBB. Lorsque redirect est défini sur false, une réponse XML contenant l'URL de jonction et le jeton de session est renvoyée à la place.
Point de terminaison
GET https://api-guide.bbbserver.com/bigbluebutton/api/join?<parameters>&checksum=replace-with-checksum L’appel join est le seul point de terminaison de l’API protégé par une somme de contrôle qui est invoqué directement dans le navigateur de l’utilisateur final (sous forme d’URL de redirection). Tous les autres appels à l’API protégés par une somme de contrôle sont effectués côté serveur.
Paramètres requis
| Paramètre | Type | Description |
|---|---|---|
meetingID | String | Requis. L'identifiant de la réunion à rejoindre. |
fullName | String | Requis. Le nom d'affichage de l'utilisateur dans la réunion. |
role | Enum | Requis. Le rôle de l'utilisateur : MODERATOR ou VIEWER (insensible à la casse). BBB 2.4+ |
Paramètres obsolètes
| Paramètre | Type | Description |
|---|---|---|
password | String | Obsolète
Obsolète depuis BBB 3.0. Attribution des rôles via mot de passe (attendeePW/moderatorPW depuis create). Remplacé par role. |
webVoiceConf | String | Obsolète Removed in 4.0 Extension vocale personnalisée pour l’ancien client Flash. La valeur n’est pas évaluée et n’a aucun effet. |
Paramètres facultatifs
| Paramètre | Type | Par défaut | Description |
|---|---|---|---|
createTime | Number (Long) | — | Horodatage provenant de la réponse create. Empêche de rejoindre une réunion qui a été recréée après la génération de l'URL de join. |
userID | String | — | ID utilisateur spécifique à l'application. Renvoyé dans getMeetingInfo et webhooks. |
avatarURL | String | — | URL vers une image d'avatar pour l'utilisateur. |
webcamBackgroundURL | String | — | URL vers une image d'arrière-plan personnalisée pour la webcam. |
firstName | String | — | Prénom (utilisé pour le tri, pas pour l'affichage). |
lastName | String | — | Nom de famille (utilisé pour le tri, pas pour l'affichage). |
redirect | Boolean | true | Lorsqu'il est défini sur false, une réponse XML est renvoyée au lieu d'une redirection du navigateur. |
errorRedirectUrl | String | — | URL alternative vers laquelle rediriger en cas d'erreurs (au lieu de la page d'erreur par défaut). |
logoutURL | String | — | URL vers laquelle rediriger après la déconnexion. Remplace la valeur de create. |
guest | Boolean | false | Marquer l'utilisateur comme invité. Soumis à la guestPolicy de la réunion. |
bot | Boolean | false | Marquer l'utilisateur comme agent automatisé. |
excludeFromDashboard | Boolean | false | Exclure l'utilisateur du tableau de bord d'analyse de l'apprentissage. |
enforceLayout | Enum | — | Forcer une mise en page spécifique pour cet utilisateur. Valeurs possibles : UNIFIED_LAYOUT, CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY. |
auth | Boolean | (conditionnel) | ⚠ Non documenté
Marquer l’utilisateur comme authentifié. Logique conditionnelle : si guest n’est pas spécifié, auth vaut true par défaut. Si guest est spécifié (avec n’importe quelle valeur, y compris false), auth vaut false par défaut, sauf si une valeur est explicitement définie. |
defaultLayout | String | — | ⚠ Non documenté
Supprimé de l’API officielle dans BBB 3.0. Le serveur accepte toujours la valeur, mais ne l’évalue jamais ; elle n’a donc aucun effet. Utilisez userdata-bbb_default_layout pour définir la disposition initiale du client. |
sessionName | String | — | ⚠ Non documenté
Nom de session personnalisé. Effectif uniquement en combinaison avec existingUserID. |
existingUserID | String | — | ⚠ Non documenté ID utilisateur interne pour rejoindre à nouveau ou se reconnecter avec une session existante. |
replaceSessionToken | String | — | ⚠ Non documenté
Jeton de la session à remplacer (lorsqu'utilisé avec existingUserID). |
Paramètres Userdata
Lors de l'appel de join, vous pouvez transmettre des données personnalisées sous forme de paramètres userdata-. Celles-ci sont mises à disposition dans le client et peuvent contrôler le comportement des plugins ou les paramètres du client par utilisateur.
La liste de blocage côté serveur getJoinUrlUserdataBlocklist ne s’applique qu’aux URL de participation générées via getJoinUrl. L’appel join lui-même accepte toutes les clés userdata.
La partie située après userdata- ne doit pas contenir d’autre trait d’union, sinon le paramètre est supprimé. Le préfixe userdata-bbb_ est réservé à BigBlueButton : utilisez votre propre préfixe pour les données d’intégration (par ex. userdata-myapp_cohort). Une liste complète est disponible dans le chapitre Paramètres client.
Exemple de requête
GET https://api-guide.bbbserver.com/bigbluebutton/api/join?meetingID=replace-with-meeting-id&fullName=John+Doe&role=VIEWER&redirect=false&checksum=replace-with-checksum Exemple de réponse (redirect=false)
<response>
<returncode>SUCCESS</returncode>
<messageKey>successfullyJoined</messageKey>
<message>You have joined successfully.</message>
<meeting_id>replace-with-internal-meeting-id</meeting_id>
<user_id>replace-with-user-id</user_id>
<auth_token>replace-with-auth-token</auth_token>
<session_token>replace-with-session-token</session_token>
<guestStatus>ALLOW</guestStatus>
<url>https://api-guide.bbbserver.com/html5client/?sessionToken=replace-with-session-token</url>
</response> Réponses d’erreur
| messageKey | Signification |
|---|---|
invalidMeetingIdentifier | La réunion n'existe pas. |
meetingForciblyEnded | La réunion a été terminée de force. |
maxParticipantsReached | La limite de participants a été atteinte. |
guestDeniedAccess | L'accès a été refusé à l'invité. |
invalidPassword | Le mot de passe est invalide. |
checksumError | Le checksum est invalide. |
mismatchCreateTimeParam | Le createTime ne correspond pas à la réunion. |
userNotFound | Aucun utilisateur actif trouvé avec cet ID (lors de l'utilisation de existingUserID). |
Utilisation de createTime pour la validation de l'URL de jonction
Le paramètre createTime sert de protection contre les URL de participation obsolètes :
Une réunion est créée et renvoie createTime: 1715261728123.
L'URL de participation est générée avec createTime=1715261728123.
La réunion se termine et est recréée avec un nouveau createTime.
L'ancienne URL de participation avec le createTime précédent est rejetée.
Cela empêche les utilisateurs disposant de liens d'invitation obsolètes d'entrer dans une nouvelle réunion qui réutilise le même meetingID.
join comme décrit ci-dessus.Conseils de sécurité
N'exposez jamais le shared secret côté client pour calculer les URL de jonction. Générez toujours les URL de jonction côté serveur et transmettez-les au client.
- L'URL de jonction générée contient le checksum et ne doit être utilisée qu'une seule fois.
- Les URL de participation doivent être générées côté serveur et transmises au client.
- Pour les réunions sensibles, utilisez
guest=trueavecguestPolicy=ASK_MODERATOR.
La transition de password à role est l'un des changements cassants les plus importants de BBB 3.0. Veillez à mettre à jour votre intégration en conséquence.
Foire aux questions
role (MODERATOR ou VIEWER) remplace l'attribution des rôles basée sur les mots de passe utilisée dans les versions antérieures. Le paramètre password est obsolète et ne doit plus être utilisé dans les nouvelles intégrations.existingUserID avec l'ID utilisateur interne de la session précédente pour vous reconnecter. Vous pouvez également transmettre replaceSessionToken pour remplacer l'ancienne session. Notez que ces paramètres ne sont pas documentés et peuvent changer sans préavis.guest est défini sur true, l'utilisateur est marqué comme invité et est soumis à la guestPolicy définie lors de la création de la réunion. Par exemple, avec ASK_MODERATOR, le modérateur doit approuver l'invité avant qu'il puisse entrer.userdata-= ) vous permettent de transmettre des données personnalisées au client de réunion par utilisateur. Ils peuvent être utilisés pour configurer le comportement du client, transmettre des informations aux plugins ou personnaliser l'expérience utilisateur.createTime dans votre URL de jonction ne correspond pas au createTime de la réunion actuellement en cours. Cela se produit généralement lorsqu'une réunion a été terminée et recréée avec le même meetingID, mais que l'URL de jonction contient encore l'ancien createTime.