RéférenceAPI du serveur RTC
URL de base : https://api.rtc.champrep.com
Cette référence couvre les voies d’intégration prises en charge avec les clésAPI de projet RTC. La connexion à la console, la configuration de l’organisation, l’administration des clés et les opérations d’administration de la plateforme ne constituent pas des voies d’intégration par clé de serveur. Gérez-les via l’ interface utilisateur appropriée plutôt que de copier des jetons de session de navigateur dans des scripts.
Envoyer Authorization: Bearer YOUR_RTC_API_KEY et, pour les corps JSON,
Content-Type: application/json. Les exemples utilisent des espaces réservés, jamais de identifiants fonctionnels. Les clés restent limitées à leur projet et à l’accès de la formule en cours.
Conventions relatives aux requêtes et aux réponses
Section intitulée « Conventions relatives aux requêtes et aux réponses »- Les identifiants sont des chaînes UUID. Utilisez les identifiants renvoyés par RTC, et non les noms d’affichage.
- Les noms sont tronqués et acceptent entre 1 et 80 caractères.
- Les corps JSON sont limités à 64 KiB et rejettent les champs inconnus.
- Les points de terminaison de liste renvoient des tableaux JSON, les plus récents en premier.
?limit(1-200) définit la taille de la page ; lorsqu’il existe davantage d’éléments, leX-Next-CursorL’en-tête de réponse contient le curseur à renvoyer en tant que?cursor. - Ne vous fiez pas aux champs de réponse non documentés et ne construisez pas d’URL de médias ou de stockage.
- Les mutations n’offrent pas de contrat général de clé idempotente. Réconciliez les résultats avant de réessayer après un délai d’expiration ou une perte de connexion.
Résumé des méthodes
Section intitulée « Résumé des méthodes »| Méthode et chemin d’accès | Portée requise | Résultat |
|---|---|---|
GET /v1/projects | Toute clé de projet valide | Tableau filtré par projet |
GET /v1/rooms | rooms:read | Tableau de salles |
POST /v1/rooms | rooms:write | 201, salle créée |
POST /v1/rooms/{roomId}/end | rooms:write | { "ended": true } |
POST /v1/rooms/{roomId}/tokens | tokens:write | Ensemble d’informations d’identification des participants |
GET /v1/recordings | recordings:read | Tableau d’enregistrements |
POST /v1/recordings | recordings:write | 202, enregistrement mis en file d’attente |
POST /v1/recordings/{recordingId}/stop | recordings:write | { "stopping": true } |
POST /v1/recordings/{recordingId}/tracks/{trackId}/download | recordings:read | URL de téléchargement temporaire |
POST /v1/recordings/{recordingId}/transcript | recordings:write | 202, la transcription est demandée (transcription) |
GET /v1/recordings/{recordingId}/transcript | recordings:read | La transcription au format JSON, ou un fichier contenant ?format=vtt, srt ou txt |
GET /v1/transcripts | recordings:read | Vos transcriptions et leur statut, sans texte |
GET /v1/usage | Toute clé de projet valide | Utilisation et quotas écoulés |
GET /v1/webhooks/endpoints, GET /v1/webhooks/deliveries | webhooks:read | Points de terminaison et journal de livraison (webhooks) |
POST, PATCH /v1/webhooks/endpoints…, rediffusions et tests | webhooks:write | Gérer les points de terminaison (webhooks) |
POST /v1/join | Aucun (un jeton de connexion) | Ensemble d’identifiants du participant (jetons de connexion) |
GET /v1/error-codes | Aucun | Le Catalogue des codes d’erreur |
Les réponses réussies utilisent 200 Sauf indication contraire. Les deux routes de lecture sans portée nommée nécessitent toujours une clé de projet valide et non expirée, ainsi qu’un accès au service.
Projets et salles
Section intitulée « Projets et salles »GET /v1/projects renvoie uniquement le projet associé à la clé. La création du projet s’effectue dans la console.
Pour POST /v1/rooms, envoyez :
{ "projectId": "00000000-0000-4000-8000-000000000001", "name": "Customer conversation", "maxParticipants": 4}projectId et name sont obligatoires. maxParticipants est facultatif, sa valeur par défaut est 8, et il doit s’agir d’un nombre entier d’au moins 2 dans les limites de votre forfait. Définissez explicitement une valeur inférieure si votre forfait n’autorise pas la valeur par défaut. La réponse inclut la nouvelle salle id, projectId, name, maxParticipants, status
(open), et createdAt.
GET /v1/rooms répertorie les salles du projet associées à la clé. Mettez fin à une salle avec
POST /v1/rooms/{roomId}/end, sans corps. La commande « Ending » bloque les nouvelles connexions et déconnecte les sessions actives. Elle demande également l’arrêt des tâches d’enregistrement en cours. La répétition de l’opération sur une salle fermée renvoie 404; il ne s’agit pas d’une réponse de réussite idempotente. Il n’existe actuellement aucune méthode permettant de renommer, de rouvrir ou de supprimer une salle.
Émission des identifiants des participants
Section intitulée « Émission des identifiants des participants »POST /v1/rooms/{roomId}/tokens accepte un objet JSON facultatif :
{ "canPublish": false }canPublish La valeur par défaut est true. Définissez-le sur false pour un client en mode réception uniquement. La salle doit être ouverte et faire partie du projet de la clé. La réponse contient :
| Champ | Signification |
|---|---|
token | Jeton de participant sensible et à durée de vie limitée |
participantId | Identifiant attribué à cette connexion |
expiresIn | Durée de validité des identifiants de connexion en secondes, actuellement 300 |
url | URL de signalisation pour le client |
iceServers | Configuration ICE, y compris les identifiants de relais temporaires |
Demandez de nouvelles informations d’identification à chaque connexion et reconnexion. Ne déduisez pas qu’une admission a abouti de la simple émission d’un jeton : l’état de la salle, sa capacité et l’autorisation sont également vérifiés au moment de la connexion. Voir le flux client complet.
Tâches d’enregistrement et téléchargements
Section intitulée « Tâches d’enregistrement et téléchargements »Commencez par POST /v1/recordings et { "roomId": "ROOM_UUID" }. Le 202
La réponse comprend un enregistrement id et status: "queued"; cela ne signifie pas qu’ un fichier téléchargeable existe déjà. Un enregistrement actif en double pour la même salle renvoie 409.
GET /v1/recordings renvoie les tâches filtrées par projet, y compris leurs id,
roomId, status, et tracks. Les métadonnées des pistes comprennent id, kind,
source, participantId, et bytes. Utilisez les identifiants de piste renvoyés par RTC.
Arrêtez une tâche en file d’attente ou un enregistrement à l’aide de
POST /v1/recordings/{recordingId}/stop, sans corps de requête. Interrogez la liste ou utilisez un
recording.ready webhook pour déterminer si l’opération est terminée. Une tâche déjà en cours de traitement, prête ou ayant échoué n’est pas une cible d’arrêt active et renvoie 404.
Pour une piste prête, publiez sur sa /download acheminement. La réponse est
{ "url": "TEMPORARY_DOWNLOAD_URL", "expiresIn": 300 }. Récupérez l’URL renvoyée telle quelle pour télécharger les octets de la pièce jointe. L’URL elle-même autorise l’accès jusqu’à son expiration ; traitez-la comme un identifiant. Elle est pas un lien public permanent. Voir sécurité et formats d’enregistrement.
Utilisation
Section intitulée « Utilisation »GET /v1/usage renvoie :
| Champ | Signification |
|---|---|
participantSeconds | Somme des durées des sessions des participants terminées et entrant dans le champ d’application |
sessions | Nombre de connexions établies dans le champ d’application |
period | all-time pour ces compteurs d’activité |
billingStatus | Indique une facturation gérée de manière centralisée |
quotas | Décisions actuelles en matière de droits d’accès pour les fonctionnalités RTC de l’espace de travail |
Divisez les secondes des participants par 60 pour afficher les minutes des participants. Ces compteurs d’activité ne constituent ni une facture ni un décompte en temps réel des participants. Une clé de projet filtre l’activité vers son projet, tandis que les quotas appartiennent à l’espace de travail propriétaire. L’utilisation facturable peut être mise à jour de manière asynchrone ; utilisez la facturation centrale pour obtenir les informations relatives à l’abonnement et à la facturation.
Les erreurs renvoient un JSON error chaîne de caractères et une valeur stable code, également envoyé dans le
X-Error-Code en-tête. Envoyez RTC-Version: 2026-11-01 pour l’enveloppe d’erreur structurée. Voir erreurs Pour les formes et le catalogue de code,
limites de débit pour 429, et gestion des versions pour ce qui est susceptible de changer sous /v1. Ne vous fiez pas au texte exact du message.
| Statut | Vérification ou action |
|---|---|
400 | Champs obligatoires, UUID, champs inconnus ou plages de valeurs d’entrée |
401 | Identifiants manquants, non valides, révoqués ou périmés |
403 | Portée de la clé, accès au projet, droits liés au forfait ou quota |
404 | Ressource absente, hors du champ d’application ou ne se trouvant pas dans l’état requis |
409 | Opération en conflit, telle qu’un enregistrement en cours |
413 | Le corps de la requête dépasse la limite de taille |
429 | Limitation de débit ; appliquez un délai d’attente et respectez la limite Retry-After lorsqu’elles sont fournies |
5xx | Panne temporaire du service ; réessayez les lectures en respectant un délai d’attente et synchronisez les écritures |
Ne jamais interroger les ressources d’un autre client pour distinguer un refus d’accès d’une absence. Suivez consignes de dépannage.