RTC-Server-ReferenzAPI
Basis-URL: https://api.rtc.champrep.com
Diese Referenz behandelt Integrationswege, die mit RTC-ProjektschlüsselnAPI unterstützt werden. Die Anmeldung in der Konsole, die Organisationseinrichtung, die Schlüsselverwaltung und Plattform-Admin- Vorgänge sind keine Integrationswege mit Serverschlüsseln. Verwalten Sie diese über die entsprechende Benutzeroberfläche, anstatt Browser-Sitzungstoken in Skripte zu kopieren.
Senden Authorization: Bearer YOUR_RTC_API_KEY und, bei JSON-Inhalten,
Content-Type: application/json. In den Beispielen werden Platzhalter verwendet, niemals funktionierende Zugangsdaten. Die Schlüssel sind weiterhin auf das jeweilige Projekt und den Zugriff des aktuellen Tarifs beschränkt.
Konventionen für Anfragen und Antworten
Abschnitt betitelt „Konventionen für Anfragen und Antworten“- IDs sind UUID-Zeichenfolgen. Verwenden Sie die von RTC zurückgegebenen IDs, nicht die Anzeigenamen.
- Namen werden gekürzt und dürfen 1 bis 80 Zeichen lang sein.
- JSON-Inhalte sind auf 64 KiB begrenzt und lehnen unbekannte Felder ab.
- Listen-Endpunkte geben JSON-Arrays zurück, wobei die neuesten Einträge an erster Stelle stehen.
?limit(1–200) legt die Seitengröße fest; wenn mehr Elemente vorhanden sind, wird dieX-Next-CursorDer Antwort-Header enthält den Cursor, der als Rückgabewert übergeben werden soll?cursor. - Verlassen Sie sich nicht auf undokumentierte Antwortfelder und erstellen Sie keine Medien-/Speicher-URLs.
- Mutationen bieten keinen allgemeinen Idempotenz-Schlüssel-Vertrag. Gleichen Sie die Ergebnisse ab, bevor Sie nach einem Timeout oder Verbindungsabbruch einen erneuten Versuch unternehmen.
Zusammenfassung der Methoden
Abschnitt betitelt „Zusammenfassung der Methoden“| Methode und Pfad | Erforderlicher Geltungsbereich | Ergebnis |
|---|---|---|
GET /v1/projects | Jeder gültige Projektschlüssel | Projektgefiltertes Array |
GET /v1/rooms | rooms:read | Raum-Array |
POST /v1/rooms | rooms:write | 201, erstellter Raum |
POST /v1/rooms/{roomId}/end | rooms:write | { "ended": true } |
POST /v1/rooms/{roomId}/tokens | tokens:write | Anmeldeinformationen der Teilnehmer |
GET /v1/recordings | recordings:read | Array mit Aufzeichnungen |
POST /v1/recordings | recordings:write | 202, Aufzeichnung in der Warteschlange |
POST /v1/recordings/{recordingId}/stop | recordings:write | { "stopping": true } |
POST /v1/recordings/{recordingId}/tracks/{trackId}/download | recordings:read | Temporäre Download-URL |
POST /v1/recordings/{recordingId}/transcript | recordings:write | 202wird das Transkript angefordert (Transkription) |
GET /v1/recordings/{recordingId}/transcript | recordings:read | Das Transkript als JSON oder eine Datei mit ?format=vtt, srt oder txt |
GET /v1/transcripts | recordings:read | Ihre Transkripte und deren Status, ohne Text |
GET /v1/usage | Jeder gültige Projektschlüssel | Abgeschlossene Nutzung und Kontingente |
GET /v1/webhooks/endpoints, GET /v1/webhooks/deliveries | webhooks:read | Endpunkte und das Zustellungsprotokoll (Webhooks) |
POST, PATCH /v1/webhooks/endpoints…, Wiederholungen und Tests | webhooks:write | Endpunkte verwalten (Webhooks) |
POST /v1/join | Keine (ein Beitrittstoken) | Zugangsdaten-Set des Teilnehmers (Beitritts-Token) |
GET /v1/error-codes | Keine | Die Fehlercodekatalog |
Erfolgreiche Antworten verwenden 200 sofern nicht anders angegeben. Beide Lesezugriffe mit keinem benannten Geltungsbereich erfordern weiterhin einen gültigen, nicht abgelaufenen Projektschlüssel sowie Zugriff auf den Dienst.
Projekte und Räume
Abschnitt betitelt „Projekte und Räume“GET /v1/projects gibt nur das mit dem Schlüssel verknüpfte Projekt zurück. Die Projekterstellung erfolgt in der Konsole.
Für POST /v1/rooms, senden Sie:
{ "projectId": "00000000-0000-4000-8000-000000000001", "name": "Customer conversation", "maxParticipants": 4}projectId und name sind erforderlich. maxParticipants ist optional, beträgt standardmäßig 8 und muss eine ganze Zahl von mindestens 2 innerhalb Ihres Tarifkontingents sein. Legen Sie explizit einen kleineren Wert fest, falls Ihr Tarif den Standardwert nicht zulässt. Die Antwort enthält den neuen Raum- id, projectId, name, maxParticipants, status
(open) sowie createdAt.
GET /v1/rooms listet die Projekträume des Schlüssels auf. Beenden Sie einen Raum mit
POST /v1/rooms/{roomId}/end, ohne Hauptteil. „Ending“ blockiert neue Beitritte und trennt aktive Sitzungen. Außerdem wird damit die Beendigung aktiver Aufzeichnungsaufträge angefordert. Die Wiederholung des Vorgangs für einen beendeten Raum gibt 404; es handelt sich nicht um eine idempotente Erfolgsantwort. Derzeit gibt es keine Methode zum Umbenennen, Wiederöffnen oder Löschen von Räumen.
Ausstellung von Teilnehmerzugangsdaten
Abschnitt betitelt „Ausstellung von Teilnehmerzugangsdaten“POST /v1/rooms/{roomId}/tokens akzeptiert ein optionales JSON-Objekt:
{ "canPublish": false }canPublish Standardmäßig ist true. Setzen Sie diese auf false für einen reinen Empfangs-Client. Der Raum muss geöffnet sein und zum Projekt des Schlüssels gehören. Die Antwort enthält:
| Feld | Bedeutung |
|---|---|
token | Sensible, kurzlebige Teilnehmer-Token |
participantId | Dieser Teilnahme zugewiesene Identifikator |
expiresIn | Gültigkeitsdauer der Zugangsdaten in Sekunden, derzeit 300 |
url | Signalisierungs-URL für den Client |
iceServers | ICE-Konfiguration, einschließlich temporärer Relay-Anmeldedaten |
Fordern Sie bei jedem Beitritt und jeder erneuten Verbindung neue Anmeldedaten an. Leiten Sie aus der Ausgabe eines Tokens nicht automatisch auf eine erfolgreiche Zulassung ab: Der Raumstatus, die Kapazität und die Berechtigung werden ebenfalls zum Zeitpunkt des Beitritts überprüft. Siehe den vollständigen Client-Ablauf.
Aufzeichnungsaufträge und Downloads
Abschnitt betitelt „Aufzeichnungsaufträge und Downloads“Beginnen Sie mit POST /v1/recordings und { "roomId": "ROOM_UUID" }. Die 202
Die Antwort enthält eine Aufzeichnung id und status: "queued"; dies bedeutet nicht, dass bereits eine herunterladbare Datei vorhanden ist. Eine doppelte aktive Aufzeichnung für denselben Raum gibt 409.
GET /v1/recordings gibt projektgefilterte Aufträge zurück, einschließlich ihrer id,
roomId, status, und tracks. Zu den Metadaten der Titel gehören id, kind,
source, participantId, und bytes. Verwenden Sie die von RTC zurückgegebenen Track-IDs.
Beenden Sie einen in der Warteschlange stehenden oder laufenden Aufzeichnungsauftrag mit
POST /v1/recordings/{recordingId}/stop, ohne Hauptteil. Abfragen Sie die Liste oder verwenden Sie ein
recording.ready Webhook zur Feststellung des Abschlusses. Ein Auftrag, der bereits in Bearbeitung, bereit oder fehlgeschlagen ist, stellt kein aktives Stoppziel dar und gibt 404.
Für einen bereiten Track senden Sie an dessen /download Route. Die Antwort lautet
{ "url": "TEMPORARY_DOWNLOAD_URL", "expiresIn": 300 }. Rufen Sie die zurückgegebene URL unverändert ab, um die Bytes des Anhangs herunterzuladen. Die URL selbst autorisiert den Zugriff bis zum Ablauf; behandeln Sie sie wie eine Zugangsberechtigung. Sie ist nicht ein öffentlicher, permanenter Link. Siehe Sicherheit und Formate von Aufzeichnungen.
Nutzung
Abschnitt betitelt „Nutzung“GET /v1/usage gibt Folgendes zurück:
| Feld | Bedeutung |
|---|---|
participantSeconds | Summe der abgeschlossenen Teilnehmer-Sitzungsdauern im Geltungsbereich |
sessions | Anzahl der abgeschlossenen Verbindungen im Geltungsbereich |
period | all-time für diese Aktivitätszähler |
billingStatus | Weist auf eine zentral verwaltete Abrechnung hin |
quotas | Aktuelle Berechtigungsentscheidungen für die RTC-Funktionen des Arbeitsbereichs |
Teilen Sie die Teilnehmersekunden durch 60, um die Teilnehmerminuten anzuzeigen. Diese Aktivitätszähler stellen weder eine Rechnung noch eine aktuelle Teilnehmerzahl dar. Ein Projektenschlüssel filtert die Aktivitäten auf das jeweilige Projekt, während Kontingente zum jeweiligen Arbeitsbereich gehören. Die Abrechnungsdaten können asynchron aktualisiert werden; nutzen Sie die zentrale Abrechnung für Informationen zu Abonnements und Rechnungen.
Fehler werden als JSON zurückgegeben error Zeichenkette und ein stabiler code, das ebenfalls in der
X-Error-Code Header. Senden Sie RTC-Version: 2026-11-01 für den strukturierten Fehler- Umschlag. Siehe Fehler Für die Formen und den Code-Katalog,
Ratenbegrenzungen für 429, und Versionierung für mögliche Änderungen unter /v1. Verlassen Sie sich nicht auf den genauen Wortlaut der Nachricht.
| Status | Prüfung oder Maßnahme |
|---|---|
400 | Pflichtfelder, UUIDs, unbekannte Felder oder Eingabebereiche |
401 | Fehlende, ungültige, widerrufene oder abgelaufene Anmeldedaten |
403 | Schlüsselbereich, Projektzugriff, Planberechtigung oder Kontingent |
404 | Ressource fehlt, liegt außerhalb des Gültigkeitsbereichs oder befindet sich nicht im erforderlichen Zustand |
409 | Konflikthaltige Operation, z. B. eine aktive Aufzeichnung |
413 | Der Request-Body überschreitet die Größenbeschränkung |
429 | Ratenbegrenzung; Backoff anwenden und die Vorgabe einhalten Retry-After , wenn angegeben |
5xx | Vorübergehender Dienstausfall; wiederholen Sie Lesevorgänge mit Backoff und gleichen Sie Schreibvorgänge ab |
Überprüfen Sie niemals die Ressourcen eines anderen Kunden, um eine Zugriffsverweigerung von einer Nichtverfügbarkeit zu unterscheiden. Befolgen Sie Anleitung zur Fehlerbehebung.