API Einführung

API Einführung

Übersicht

Diese kurze Anleitung zeigt die grundlegenden Schritte auf, die man durchführen muss, um neue Konten zu erstellen und Sitzungen im Namen von Konten zu planen.

Dieses Dokument verwendet "CURL" für die Beispiele. Natürlich kann auch eine andere Technologie für die REST-Aufrufe eingesetzt werden.

Voraussetzungen

API Schlüssel

Sie benötigen einen API Schlüssel (API-KEY) mit den Berechtigungen "Konten" und "Sitzungen".

Hinweis: Sie müssen den API-KEY geheim halten und die API Aufrufe mit diesem ausschliesslich von Servern aus starten. Alle mit Zugriff auf den API-KEY haben volle Kontrolle über Ihre Platform.

Hinweis: In den Beispielen weiter unten zeichnen wir die Platzhalter in eckigen Klammern aus, z.B. <API-KEY>. Die Platzhalter müssen Sie durch Ihre eigenen Werten ersetzen.

Terminologie

In dieser kurzen Dokumentation werden wir die folgenden Begriffe verwenden:

  • Domainname: Das ist der Domainname, unter dem Ihre Web-Meeting-Instanz läuft (<DOMAIN-NAME>).
  • Konto: Ein Konto ist eine Entität, unter der Sitzungsorganisatoren erstellt werden.
  • Sitzungsorganisatoren: Ein Sitzungsorganisator ist eine Person, die Sitzungen innerhalb eines Kontos planen darf. Ein Sitzungsorganisator wird durch eine E-Mail-Adresse definiert. Eine E-Mail-Adresse kann innerhalb einer Web-Meeting-Instanz nur einmal existieren.
  • Konto-ID: die interne ID eines Kontos (<ACCOUNT-ID>)
  • Benutzer-ID: die interne ID eines Sitzungsorganisatoren (<USER-ID>)
  • Benutzer-Email: die registrierte Emailadresse eines Sitzungsorganisatoren (<USER-EMAIL>)
  • Sitzung-ID: die interne ID einer Sitzung (<MEETING-ID>)

Konto erstellen

Bevor wir eine Sitzung planen können müssen wir ein Konto anlegen. Mit demselben Aufruf erstellen wir gleichzeitig auch den ersten Sitzungsorganisator unter diesem Konto:

Eingabedaten:

{ 
  "sendPassword": true, 
  "accountType": "trial", 
  "adminFirstname": "Test",
  "adminLastname": "User", 
  "adminEmail": "test-user@example.com", 
  "adminPreferredLanguage": "en", \
  "paidUntil": "2022-04-19T19:03:41.203Z" 
}

Beispiel:

curl 'https://<DOMAIN-NAME>/api/v6/account' \
  -X POST \
  -H 'X-API-KEY: <API-KEY>' \
  -H 'content-type: application/json' \
  --data-binary '{"sendPassword": true,"accountType": "trial","adminFirstname": "Test","adminLastname": "User","adminEmail": "test-user@example.com", "adminPreferredLanguage": "en","paidUntil": "2022-04-19T19:03:41.203Z"}'

Bei Erfolg antwortet das System mit dem folgenden Datensatz:

{
    "responseCode": 0,
    "data": {
        "name": "test-user@example.com",
        "accountType": "trial",
        "numberOfMeetings": 0,
        "numberOfMeetingOrganizers": 0,
        "numberOfMeetingRooms": 1,
        "paidUntil": "2022-04-27T12:23:33.852Z",
        "iceCandidatesToFilter": [],
        "customDialInNumbers": [],
        "displayStandardDialInNumbersInInvite": true,
        "defaultMeetingPermissions": null,
        "defaultMeetingType": "standard",
        "defaultMeetingHasDialin": false,
        "defaultMeetingHasRecording": false,
        "autoExtendMeetings": false,
        "autoDeleteMeetingsAfterXDays": 360,
        "id": "5e9459c5b863b82cefdddf4f",
        "canAddMeetingOrganizer": true,
        "accountRooms": []
    }
}

Beachten Sie die <ACCOUNT-ID> "5e9459c5b863b82cefdddf4f" in diesem Beispiel. Wir benötigen sie im nächsten Schritt.

Abruf des Kontoadministratoren

Sobald wir ein Konto haben, können wir die <USER-ID> des ersten Sitzungsorganisatoren abrufen::

curl 'https://<DOMAIN-NAME>/api/v6/account/admin/<ACCOUNT-ID>' \
  -X GET \
  -H 'X-API-KEY: <API-KEY>' \
  -H 'content-type: application/json'

Bei Erfolg antwortet das System mit dem folgenden Datensatz:

{
    "responseCode": 0,
    "data": [
        {
            "email": "test-user@example.com",
            "firstName": "Test",
            "lastName": "User",
            "externalUserId": null,
            "preferredLanguage": "en",
            "timezone": "Europe/Paris",
            "additionalTimezones": [],
            "id": "5e9459c5b863b82cefdddf4e",
            "icsToken": "ce5494bc-d691-4caf-906c-bfa6403fdc71-32a0633d-99e7-41ff-bfe9-e28fe2f10e73",
            "icsPath": "/api/v6/meeting/calender/user/ce5494bc-d691-4caf-906c-bfa6403fdc71-32a0633d-99e7-41ff-bfe9-e28fe2f10e73"
        }
    ]
}

Beachten Sie die <USER-ID> "5e9459c5b863b82cefdddf4e" in diesem Beispiel. Wir werden diese im nächsten Schritt benötigen.

Sitzung erstellen

Wir können jetzt eine Sitzung im Namen des Benutzers erstellen. Das minimale Datenset besteht aus den Folgenden Informationen:

{ 
  "topic":"My Meeting Topic",
  "startTime":"2022-04-07T09:00:00.000Z",
  "endTime":"2022-04-07T10:00:00.000Z", 
  "duration":60, 
  "type":"standard", 
  "isRecurring":false,
  "isRecorded":false,
  "isDialin":false,
  "invitedParticipants":[],
  "recurring":{},
  "meetingPermissionId":null
}

Wann immer wir ein API im Namen eines Sitzungsorganisators aufrufen, müssen wir im Aufruf den Benutzer auf identifizieren. Wir können dies entweder mit der <USER-ID> oder der <USER-EMAIL> machen.

In diesem Beispiel benutzen wir die <USER-ID> aus dem vorherigen Schritt benutzen

curl 'https://<DOMAIN-NAME>/api/v6/meeting' \
  -X POST \
  -H 'X-USER-ID: <USER-ID>' \
  -H 'X-API-KEY: <API-KEY>' \
  -H 'content-type: application/json' \
  --data-binary '{"topic":"My Meeting Topic","startTime":"2022-04-07T09:00:00.000Z", "endTime":"2022-04-07T10:00:00.000Z","duration":60,"type":"standard","isRecurring":false,"isRecorded":false,"isDialin":false,"invitedParticipants":[],"recurring":{},"meetingPermissionId":null}'  

Alternativ können wir auch die <USER-EMAIL> benutzen:

curl 'https://<DOMAIN-NAME>/api/v6/meeting' \
  -X POST \
  -H 'X-USER-EMAIL: <USER-EMAIL>' \
  -H 'X-API-KEY: <API-KEY>' \
  -H 'content-type: application/json' \
  --data-binary '{"topic":"My Meeting Topic","startTime":"2022-04-07T09:00:00.000Z", "endTime":"2022-04-07T10:00:00.000Z","duration":60,"type":"standard","isRecurring":false,"isRecorded":false,"isDialin":false,"invitedParticipants":[],"recurring":{},"meetingPermissionId":null}'  

Bei Erfolg antwortet das System mit dem folgenden Datensatz:

{
    "responseCode": 0,
    "data": {
        "invitedParticipants": [],
        "meetingId": "9974-7653-8886-0485",
        "id": "5e945c36b863b82cefdddf54",
        "topic": "My Meeting Topic",
        "startTime": "2022-04-07T09:00:00.000Z",
        "endTime": "2022-04-07T10:00:00.000Z",
        "duration": "60",
        "type": "standard",
        "roomId": "5e9459c5b863b82cefdddf50",
        "isRecurring": false,
        "isDialin": false,
        "recurring": {
            "frequencyType": "",
            "frequency": null,
            "monthlyPattern": "",
            "endsType": "",
            "endsOn": "2022-04-13T12:18:07.211Z",
            "endsAfter": 0
        },
        "isRecorded": false,
        "agenda": "",
        "documents": [],
        "meetingPermissionId": null,
        "videoResolution": "standard",
        "dtClosedAt": null,
        "whitelabelId": "5c737902b377b0f7fbf81fce",
        "addedByUserId": "5e9459c5b863b82cefdddf4e",
        "addedByUserEmail": "test-user@example.com",
        "accountId": "5e9459c5b863b82cefdddf4f",
        "addedByUserName": "Test User",
        "timezone": "Europe/Zurich",
        "privateDataVisible": true,
        "icalSequence": "0",
        "icsToken": "c89f842f-3295-4bf9-807d-a46841fbc2ec-25f722e4-70fc-4163-9cda-b4b7d8aec358",
        "isActive": false,
        "isClosed": true,
        "isOpen": false,
        "dialInConferenceRoom": null,
        "dialInNumbers": [],
        "dialInPin": null,
        "sipProxy": null,
        "sipDomain": null,
        "isDemo": false,
        "isPromo": false
    }
}

Beachten Sie die <MEETING-ID> "5e945c36b863b82cefdddf54" in diesem Beispiel. Wir verwenden die Sitzungs-ID, um zu einem späteren Zeitpunkt die Sitzungsdaten zu aktualisieren.

Sitzung aktualisieren

Wir können bis kurz vor Beginn der Sitzung die Details anpassen.

{ 
  "topic":"My Updated Meeting Topic",
  "id": "<MEETING-ID>",
  "startTime":"2022-04-07T09:30:00.000Z",
  "endTime":"2022-04-07T10:30:00.000Z", 
  "duration":60, 
  "type":"standard", 
  "isRecurring":false,
  "isRecorded":false,
  "isDialin":false,
  "invitedParticipants":[],
  "recurring":{},
  "meetingPermissionId":null
}

Beispiel mit <USER-ID>

curl 'https://<DOMAIN-NAME>/api/v6/meeting/<MEETING-ID>/false' \
  -X PUT \
  -H 'X-USER-ID: <USER-ID>' \
  -H 'X-API-KEY: <API-KEY>' \
  -H 'content-type: application/json' \
  --data-binary '{"topic":"My Updated Meeting Topic","id": "5e945c36b863b82cefdddf54","startTime":"2022-04-07T09:05:00.000Z","endTime":"2022-04-07T10:00:05.000Z","duration":60,"type":"standard","isRecurring":false,"isRecorded":false,"isDialin":false,"invitedParticipants":[],"recurring":{},"meetingPermissionId":null}'  

Dasselbe Beispiel mit <USER-EMAIL>

curl 'https://<DOMAIN-NAME>/api/v6/meeting/<MEETING-ID>/false' \
  -X PUT \
  -H 'X-USER-EMAIL: <USER-EMAIL>' \
  -H 'X-API-KEY: <API-KEY>' \
  -H 'content-type: application/json' \
  --data-binary '{"topic":"My Updated Meeting Topic","id": "5e945c36b863b82cefdddf54","startTime":"2022-04-07T09:05:00.000Z","endTime":"2022-04-07T10:00:05.000Z","duration":60,"type":"standard","isRecurring":false,"isRecorded":false,"isDialin":false,"invitedParticipants":[],"recurring":{},"meetingPermissionId":null}'  

Sitzungen schliessen

Alle Sitzungen werden nach Ablauf der Zeit automatisch geschlossen. Manchmal möchte man aber Sitzungen auch explizit schon vor dem offiziellen Ende schliessen. Teilnehmer, die immer noch im Sitzungsraum sind, werden automatisch aus dem Raum ausgeschlossen.

In diesem Beispiel benutzen wir die <USER-EMAIL>:

curl 'https://<DOMAIN-NAME>/api/v6/meeting/close' \
  -X POST \
  -H 'X-USER-EMAIL: <USER-EMAIL>' \
  -H 'X-API-KEY: <API-KEY>' \
  -H 'content-type: application/json' \
  --data-binary '{"meetingId": "5e945c36b863b82cefdddf54"}'  

Sitzungen löschen

Wir können wir folgt Sitzungen löschen:

curl 'https://<DOMAIN-NAME>/api/v6/meeting/5e945c36b863b82cefdddf54' \
  -X DELETE \
  -H 'X-USER-EMAIL: <USER-EMAIL>' \
  -H 'X-API-KEY: <API-KEY>' \
  -H 'content-type: application/json'  

Sind Sie nicht sicher, wie Sie Ihr Projekt am Besten umsetzen sollen?

Sprechen Sie mit unserem Team über Ihre Pläne.