Chapitre 4 GET

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 API invoqué directement dans le navigateur de l'utilisateur final (comme URL de redirection). Tous les autres appels API 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 3.0+

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.

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.
‎⚠ Non documenté La documentation officielle indique incorrectement cette valeur comme PARTICIPANTS_CHAT_ONLY (sans _AND_).
auth Boolean (conditionnel) ‎⚠ Non documenté Marquer l'utilisateur comme authentifié. Logique conditionnelle : si guest n'est pas spécifié, auth vaut par défaut true. Si guest=true est spécifié, auth vaut par défaut false sauf si cela est défini explicitement.
defaultLayout String — ‎⚠ Non documenté Mise en page par défaut pour cet utilisateur. Mêmes valeurs que meetingLayout dans l'appel create.
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.

Certaines clés userdata peuvent être bloquées côté serveur via une liste de blocage (getJoinUrlUserdataBlocklist).

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>
        <url>https://api-guide.bbbserver.com/client/BigBlueButton.html?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.

Sur bbbserver.de, l'URL de jonction est toujours générée côté serveur avec le bon checksum et les bons paramètres. Vous n'avez pas besoin de construire manuellement les URL de jonction.

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=true avec guestPolicy=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

Dans BBB 3.0 et les versions ultérieures, le paramètre 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.

Au lieu de rediriger le navigateur vers la réunion, le serveur renvoie une réponse XML contenant l'URL de jonction et le jeton de session. Cela est utile pour les intégrations côté serveur qui doivent inspecter la réponse ou gérer le jeton de session par programmation.

Oui. Utilisez le paramètre 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.

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

Les paramètres Userdata (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.

Cette erreur se produit lorsque la valeur 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.