Die öffentliche API von MyOwnConference

Mit der API von MyOwnConference steuern Sie Ihr Konto aus eigenem Code. Sie planen Webinare, verwalten Moderatoren und Teilnehmer, holen sich Anwesenheits- und Chatverlauf und bringen ein vollautomatisches Event von Anfang bis Ende über die Bühne. Offen sein muss das Kontrollpanel dafür nie.

Ihr Zugangsschlüssel

Jede Anfrage bestätigt ein eigener Schlüssel, den das System für Sie erzeugt. Melden Sie sich im Kontrollpanel an, öffnen Sie den Bereich „Profil“ ("Profile") und suchen Sie das Feld „API key“ ("API Key").

Vermuten Sie, dass Ihr Schlüssel in fremde Hände geraten ist? Erzeugen Sie einen neuen. Der Knopf zum Auffrischen sieht aus wie zwei Pfeile und steht neben dem Feld „API key“. Drücken Sie ihn. Sobald der neue Schlüssel erscheint, hört der alte auf zu wirken. Geben Sie den Schlüssel niemandem außer Programmierern und Leuten, denen Sie den Zugang zum Kontrollpanel ohnehin anvertraut haben.

Alle Zugriffe auf die API schreiben wir mit und bewahren sie 365 Tage auf. Greift jemand mit Ihrem Schlüssel auf Daten zu, die dem Konto nicht gehören, sperrt sich das Konto automatisch. Geld erstatten wir dann nicht und Beschwerden nehmen wir nicht an, behandeln Sie den Schlüssel also wie ein Passwort.

Format der Anfrage

Anfragen gehen über HTTPS an eine eigene Domain, https://api.mywebinar.com. Ihr Format ist JSON. Schicken müssen Sie sie mit der Methode POST, in einem einzigen Datenfeld namens request. Jeder andere Weg liefert jedes Mal einen Fehler.

Alles, was in diesem Dokument als %--text--% steht, ist ein Platzhalter. Setzen Sie Ihren eigenen Wert ein, bevor Sie die Anfrage abschicken.

Eine Anfrage trägt entweder benannte Parameter.

"request":
{
  "key": "%--api-key-from-your-profile--%",
  "action": "%--required-api-command--%",
  "params":
  {
    "%--parameter--%": "%--value--%",
    "%--parameter--%": "%--value--%"
  }
}

Oder eine einfache Liste von Werten.

"request":
{
  "key": "%--api-key-from-your-profile--%",
  "action": "%--required-api-command--%",
  "params":
  [
    "%--value--%",
    "%--value--%"
  ]
}

key und action sind immer nötig. Nimmt ein Befehl keine weiteren Parameter? Dann schicken Sie für params ein leeres Array.

Format der Antwort

Antworten kommen immer als JSON, und jede wiederholt neben dem Ergebnis die ursprüngliche Anfrage. Sie bekommen eine von drei Formen.

Erfolg mit Daten.

{
  "request": { "action": "%--required-api-command--%", "params": { } },
  "response": { "%--parameter--%": "%--value--%" }
}

Erfolg ohne Daten.

{
  "request": { "action": "%--required-api-command--%", "params": { } },
  "response": { "success": "%--message--%" }
}

Ein Fehler mit der Beschreibung, was schiefging.

{
  "request": { "action": "%--required-api-command--%", "params": { } },
  "response": { "error": "%--message--%" }
}

Meldungen über Erfolg und Fehler kommen auf Englisch, unabhängig von der Sprache Ihres Kontos.

Beispiel in PHP

$data['request'] = json_encode( [
  'key'    => '%--api-key-from-your-profile--%',
  'action' => '%--required-api-command--%',
  'params' => [
    '%--parameters--%',
  ],
] );

$ch = curl_init();
curl_setopt_array( $ch, [
  CURLOPT_URL           => 'https://api.mywebinar.com',
  CURLOPT_POST          => 1,
  CURLOPT_TIMEOUT       => 30,
  CURLOPT_RETURNTRANSFER => 1,
  CURLOPT_POSTFIELDS    => $data,
] );

$result = json_decode( curl_exec( $ch ), true );
curl_close( $ch );

var_dump( $result );

Beispiel in Node.js

const https = require( 'https' );
const query = require( 'querystring' );

const data = query.stringify( {
  request: JSON.stringify( {
    key: '%--api-key-from-your-profile--%',
    action: '%--required-api-command--%',
    params: [
      '%--parameters--%',
    ],
  } ),
} );

const options = {
  hostname: 'api.mywebinar.com',
  port: 443,
  path: '/',
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Content-Length': Buffer.byteLength( data ),
  },
};

const request = https.request( options, response => {
  response.on( 'data', result => {
    process.stdout.write( result.toString() );
  } );
} );

request.on( 'error', error => console.error( error ) );
request.write( data );
request.end();

Die weiteren Beispiele stehen in PHP.

Grenzen der Textfelder

Bei den meisten Befehlen sind die Grenzen dieselben, deshalb stehen sie hier gesammelt statt bei jedem einzeln.

In Namen, Firmen, Abteilungen und Städten lassen wir jedes Zeichen zu außer ^~!@#$%^&*()+=[{}]\|:;,<>/?.

Befehle für das Profil

profileGet

Gibt das ganze Profil zurück oder nur die Felder, nach denen Sie fragen.

$data[ 'request' ] = json_encode( [
  'key'    => '%--api-key-from-your-profile--%',
  'action' => 'profileGet',
  'params' => [
    'name',
    'timezone',
  ],
] );

Wollen Sie alles bekommen? Schicken Sie ein leeres Array params.

profileSet

Aktualisiert das Profil ganz oder in Teilen. Geben Sie mehrere Parameter in einem Array an, dann ändern sie sich zusammen.

$data[ 'request' ] = json_encode( [
  'key'    => '%--api-key-from-your-profile--%',
  'action' => 'profileSet',
  'params' => [
    'name'      => '%--first-and-last-names--%',
    'timezone'  => '%--timezone-in-minutes--%',
    'subscribe' => '%--yes-or-no--%',
  ],
] );

profileSet nimmt dieselben Felder wie profileGet.

Befehle für Moderatoren

Moderatoren sind die Leute, die Ihre Webinare halten. Den Moderator, der bei der Registrierung entsteht, nennen wir den Hauptmoderator oder auch Kontoadministrator. Im Kontrollpanel trägt er einen Stern und lässt sich nicht löschen. Er erreicht jedes Webinar und jede hochgeladene Datei.

moderatorsCreate

Legt einen Moderator aus Namen und E-Mail-Adresse an.

$data[ 'request' ] = json_encode( [
  'key'    => '%--api-key-from-your-profile--%',
  'action' => 'moderatorsCreate',
  'params' => [
    'name'  => '%--first-and-last-names--%',
    'email' => '%--email-address-at-domain-com--%',
  ],
] );

moderatorsDelete

Löscht einen Moderator oder gleich ein ganzes Array davon. Die Adressen geben Sie als einfache Liste an.

$data[ 'request' ] = json_encode( [
  'key'    => '%--api-key-from-your-profile--%',
  'action' => 'moderatorsDelete',
  'params' => [
    '%--email-address-at-domain-com--%',
    '%--email-address-at-domain-com--%',
  ],
] );

moderatorsSet

Ändert Namen oder Adresse eines Moderators und lädt bei Bedarf ein Bild hoch, das statt seiner Webcam erscheint.

Von Hand kodieren Sie ein Bild mit dem Befehl cat /path/to/file/test.png | base64.

moderatorsList

Gibt Ihre Moderatoren zurück. Die Parameter unten sind alle freiwillig und lassen sich in einer Anfrage kombinieren.

In der Antwort stehen name, email und registered, das Datum, an dem der Moderator dazukam, auf die Sekunde genau. Dazu kommen main (YES beim Hauptmoderator) und avatar (YES, wenn ein Bild die Kamera ersetzt).

moderatorsAddToWebinar

Hängt einen oder mehrere Moderatoren an ein Webinar. Ein angehängter Moderator wird Referent dieses Events und bekommt von da an Einladungen und Erinnerungen.

$data[ 'request' ] = json_encode( [
  'key'    => '%--api-key-from-your-profile--%',
  'action' => 'moderatorsAddToWebinar',
  'params' => [
    'alias' => '%--webinar-alias-xxxx-xxxx-xxxx-xxxx--%',
    'email' => [
      '%--email-address-at-domain-com--%',
    ],
  ],
] );

sendInvite ist freiwillig. Setzen Sie YES, damit die Einladung sofort hinausgeht, oder NO, damit sie zum üblichen Termin kommt.

moderatorsRemoveFromWebinar

Löst Moderatoren von einem Webinar und nimmt ihnen die Zugriffsrechte. Einladungslinks bekommen sie nicht mehr, und jeden anderen Weg ins Event verlieren sie ebenfalls. Die Parameter sind dieselben alias und email wie beim Befehl darüber.

moderatorsRooms

Gibt zu einer E-Mail-Adresse jedes Webinar zurück, an dem der Moderator hängt. In jedem Eintrag stehen alias, name, description, start, timezone, duration und moderatorLink.

Ein Moderatorenlink ist für eine einzige Person gedacht. Moderatoren, die ihren Link weiterreichen, kommen mit einer von drei Klagen zurück. Man wirft sie aus dem Raum, sie kommen nicht hinein, oder drinnen sitzt schon jemand unter ihrem Namen. Alle drei haben dieselbe Ursache. Ein zweiter Eintritt über denselben Link trennt immer die erste Sitzung, niemand sollte also einen Raum mit einem fremden Link öffnen.

Befehle für Teilnehmer

attendeesCreate

Legt einen Teilnehmer aus E-Mail-Adresse und Namen an.

$data[ 'request' ] = json_encode( [
  'key'    => '%--api-key-from-your-profile--%',
  'action' => 'attendeesCreate',
  'params' => [
    'email' => '%--attendee-email-at-domain-dot-com--%',
    'name'  => '%--attendee-first-and-last-name--%',
  ],
] );

In Teilnehmeradressen lassen wir englische Buchstaben und Ziffern zu.

attendeesSet

Aktualisiert einen vorhandenen Teilnehmer. Erkennen Sie ihn an email und schicken Sie die Felder, die Sie ändern wollen.

Ihr Konto kann über diese Liste hinaus noch weitere Felder führen.

attendeesDelete

Löscht einen Teilnehmer oder ein Array davon, angesprochen über die E-Mail-Adresse.

attendeesList

Gibt früher angelegte Teilnehmer zurück, mit Filtern, Sortierung und Seiten.

In fields fragen Sie nach name, email, phone, company, department, city, born, creation_date, country und type. Dazu kommen notified, wie viele Einladungen hinausgingen, und link, der Eintrittslink des Teilnehmers, nur zusammen mit alias verfügbar.

attendeesAddToWebinar und attendeesRemoveFromWebinar

Hängen Teilnehmer an ein geplantes Webinar oder nehmen sie wieder herunter. Beide nehmen alias und dazu ein Array attendees mit E-Mail-Adressen.

$data[ 'request' ] = json_encode( [
  'key'    => '%--api-key-from-your-profile--%',
  'action' => 'attendeesAddToWebinar',
  'params' => [
    'alias'     => '%--webinar-alias-xxxx-xxxx-xxxx-xxxx--%',
    'attendees' => [
      '%--attendee-email-at-domain-dot-com--%',
    ],
  ],
] );

attendeesRooms

Gibt zu einer Teilnehmeradresse jedes Webinar zurück, zu dem er eingeladen wurde. In jedem Eintrag stehen alias, name, description, start, timezone, duration und attendeeLink.

Teilnehmergruppen

attendeesUnbanned

Hebt die Sperre eines Teilnehmers auf, den jemand aus einem Webinar-Raum gesperrt hat. Geben Sie in email eine Adresse oder ein Array von Adressen an.

Befehle für Webinare

Fast alles unten sprechen Sie über alias an, die eindeutige id des Webinars. webinarsCreate gibt sie zurück, und sie steht auch als Code im Link zum Webinar.

webinarsCreate

Plant ein Webinar und gibt die Links zurück, die Sie brauchen.

$data[ 'request' ] = json_encode( [
  'key'    => '%--api-key-from-your-profile--%',
  'action' => 'webinarsCreate',
  'params' => [
    'name'     => '%--webinar-name-or-topic--%',
    'start'    => '%--year-month-day-hours-minutes-seconds--%',
    'duration' => '%--webinar-duration-in-minutes--%',
  ],
] );

In der Antwort kommt alias, dazu webinarLink für die öffentliche Seite und mainModeratorLink für den Hauptmoderator.

start schreiben Sie im Format YYYY-MM-DD HH:MM:SS, und wir lesen es in der Zeitzone aus Ihrem Profil. duration zählt in Minuten und darf 1439 nicht überschreiten, also genau eine Minute weniger als ein voller Tag.

webinarsSet

Ändert jede Einstellung eines früher geplanten Webinars.

$data[ 'request' ] = json_encode( [
  'key'    => '%--api-key-from-your-profile--%',
  'action' => 'webinarsSet',
  'params' => [
    'alias'    => '%--webinar-alias-xxxx-xxxx-xxxx-xxxx--%',
    'name'     => '%--webinar-name-or-topic--%',
    'language' => '%--webinar-room-language--%',
    'settings' => [
      'cameraSize'    => '%--mini-middle-big--%',
      'userList'      => '%--yes-or-no--%',
      'loginfields'   => [
        'name',
        'email',
      ],
      'recordWhole'   => '',
      'recordUsers'   => '%--yes-or-no--%',
      'recordQuality' => '%--quality-level--%',
    ],
  ],
] );

Das sind die Parameter der obersten Ebene.

Und das sind die Einstellungen des Raums.

Den Aufnahmemodus setzen Sie mit dem Namen des Modus als Schlüssel und leerem Wert, zum Beispiel recordWebCams => "".

Drei weitere Schalter entscheiden, was in der Datei landet. recordUsers legt die Teilnehmerliste in die Aufnahme, recordModer druckt den Namen jedes Moderators auf seine Kamera, und recordChat nimmt den Chat dazu. Setzen Sie recordUsers oder recordModer, springt der Modus von selbst auf recordWhole.

recordQuality setzt die Auflösung. 0 nimmt in 480p (800x460) auf, 1 in 720p (1280x720), 2 in 1080p (1920x1080), 3 in 2K (2048x1080) und 4 in 2160p. Welche Stufe Ihr Konto wirklich nutzen kann, entscheidet Ihr Plan und nicht die API. Der kostenlose Starter nimmt bis 1080p auf, ebenso bezahlte Pläne unter 500 Teilnehmern, und Pläne ab 500 Teilnehmern reichen bis 2160p. Was in jedem Plan steckt, listet die Preisseite auf.

webinarsDelete

Löscht ein geplantes Webinar vollständig, angesprochen über alias.

webinarsClone

Kopiert ein Webinar auf ein neues date im Format YYYY-MM-DD und gibt neue alias, webinarLink und mainModeratorLink zurück.

webinarsList

Gibt Ihre Webinare zurück.

In einem Eintrag stehen name, description, created (Zeit der Anlage in GMT+0), alias, start und language.

webinarsGetInfo

Gibt alles zurück, was das System über ein Webinar weiß, dazu seinen Block settings, sein status und records, die Zahl der bisher gemachten Aufzeichnungen. Menge und Form der Daten unterscheiden sich von Konto zu Konto, verdrahten Sie die Feldliste also nicht fest im Code.

webinarsGetLettersInfo und webinarsSetLetters

webinarsGetLettersInfo gibt die Einladungsmails eines Webinars zurück, jede mit enabled, status und text.

webinarsSetLetters ändert sie. Der Befehl nimmt alias, einen type, ein Kennzeichen enabled mit YES oder NO und text, eine Signatur in HTML, die wir an die Nachricht hängen. Schicken Sie text leer, und die Signatur verschwindet.

Die Nachricht 1HOUR lässt sich nicht abschalten.

webinarsLettersOff und webinarsLettersOn

Stoppen alle Einladungsmails eines Webinars oder starten sie wieder, angesprochen über alias.

webinarsOnlineList

Gibt zurück, wer gerade im Raum ist, getrennt nach moderators und guests.

webinarsRecordsList und webinarsRecordDelete

webinarsRecordsList gibt die Aufzeichnungen eines Webinars zurück. Jede trägt id, name, status (in Arbeit oder fertig zum Herunterladen), added, size in Bytes, duration in Sekunden, link zum Ansehen und download_link zum Herunterladen.

webinarsRecordDelete entfernt eine Aufzeichnung über die id, die Sie aus dieser Liste haben.

webinarsFilesList

Gibt das Material zurück, das auf einem Webinar liegt. type ist freiwillig. PRESENTATION gibt Präsentationen und Bilder zurück, MEDIA gibt mp3- und mp4-Dateien samt Videos von YouTube und Vimeo zurück. Jede Datei trägt id, name, added, size, duration (Sekunden bei Medien oder die Zahl der Folien bei einer Präsentation), link und download_link.

webinarsHistory

Gibt das Protokoll eines Webinars zurück. Setzen Sie type auf chats für jede Nachricht im Textchat oder auf visits für den Anwesenheitsverlauf. In einer Zeile stehen der Zeitstempel, der Name des Teilnehmers und der Text der Nachricht. Dazu kommen ein Zeichen g oder m für Gast oder Moderator und die Adresse des Teilnehmers.

Befehle für die Automatisierung

Diese Befehle sind die Mechanik hinter automatisierten Webinaren. Sie füllen einen Raum mit virtuellen Moderatoren und virtuellen Teilnehmern und schreiben unter deren Namen in den Chat. Sie führen Folien und Video und beenden das Event, wenn Sie fertig sind. Alles läuft nach Ihrem Takt und nicht nach dem eines Referenten.

webinarsAddModerToRoom und webinarsRemoveModerFromRoom

webinarsAddModerToRoom setzt einen virtuellen Moderator in einen Raum. Der Befehl nimmt alias, eine eindeutige email und einen name. webinarsRemoveModerFromRoom holt diesen Moderator wieder heraus, angesprochen über alias und email.

$data[ 'request' ] = json_encode( [
  'key'    => '%--api-key-from-your-profile--%',
  'action' => 'webinarsAddModerToRoom',
  'params' => [
    'alias' => '%--webinar-alias-xxxx-xxxx-xxxx-xxxx--%',
    'email' => '%--moderator-email-at-domain-dot-com--%',
    'name'  => '%--moderator-first-and-last-name--%',
  ],
] );

webinarsAddBotToRoom, webinarsRemoveBotFromRoom und webinarsGetBotsList

webinarsAddBotToRoom setzt einen virtuellen Teilnehmer in den Raum. Der Befehl nimmt alias, name und country, einen zweibuchstabigen Ländercode wie US, DE, FR, PL oder UA. In der Antwort kommt die id, die Sie später brauchen.

webinarsRemoveBotFromRoom nimmt diese id wieder heraus, und webinarsGetBotsList gibt jeden virtuellen Teilnehmer zurück, der gerade an einem Webinar hängt.

webinarsBotMessage

Schickt eine Chatnachricht im Namen eines virtuellen Moderators oder eines virtuellen Teilnehmers.

Steuerung des Chats

webinarsLockChat verbietet echten Teilnehmern das Schreiben im Chat, webinarsUnlockChat erlaubt es wieder. Moderatoren und Referenten schreiben immer, eine Chatsperre trifft also nur Teilnehmer.

webinarsLinkLockInChat und webinarsLinkUnlockInChat tun dasselbe mit Links, sie sperren oder erlauben Links zwischen echten Teilnehmern. Alle vier nehmen nur alias.

Folien und Video

webinarsStartPresentation zeigt echten Teilnehmern eine Folie. Der Befehl nimmt alias, die id der Präsentation aus webinarsFilesList und slide, die Nummer der Seite, die erscheinen soll. webinarStopPresentation nimmt die Präsentation vom Bildschirm, dafür reicht alias.

webinarsStartVideo spielt eine Videodatei, einen Clip von YouTube oder einen von Vimeo ab und nimmt dafür alias und die id der Datei aus webinarsFilesList. webinarsStopVideo hält die Wiedergabe an und nimmt nur alias.

webinarsFinish

Beendet das Webinar und trennt jeden, der im Raum sitzt. Der Befehl nimmt alias und wirkt nur bei einem Webinar, das schon begonnen hat.

Wenn hier etwas nicht stimmt

Ist Ihnen in diesem Dokument ein Fehler oder eine Ungenauigkeit aufgefallen? Sagen Sie es uns im Online-Chat. Wir prüfen das und bessern die Seite nach.

MyOwnConference kann dieses Dokument jederzeit ändern oder erweitern. Wer danach arbeitet, nimmt das in Kauf.

Häufig gestellte Fragen

Was tue ich, wenn mein API-Schlüssel nach außen gerät?

Erzeugen Sie sofort einen neuen, mit dem Knopf zum Auffrischen aus zwei Pfeilen neben dem Feld „API key“ ("API Key") im Bereich „Profil“ ("Profile"). Der alte Schlüssel hört auf zu wirken, sobald der neue erscheint. Alle Zugriffe auf die API schreiben wir mit und bewahren sie 365 Tage auf. Greift jemand mit Ihrem Schlüssel auf Daten zu, die dem Konto nicht gehören, sperrt sich das Konto automatisch. Geld erstatten wir dann nicht und Beschwerden nehmen wir nicht an.

Jede Anfrage kommt als Fehler zurück. Was mache ich falsch?

Prüfen Sie zuerst den Weg und erst dann den Befehl. Anfragen gehen über HTTPS an https://api.mywebinar.com, mit der Methode POST, und das JSON liegt in einem einzigen Datenfeld namens request. Jeder andere Weg liefert jedes Mal einen Fehler. key und action sind immer nötig, und nimmt ein Befehl keine weiteren Parameter, geht für params trotzdem ein leeres Array hinaus.

Kann ich ein Webinar planen, das länger als einen Tag läuft?

Nein, duration zählt in Minuten und darf 1439 nicht überschreiten, also genau eine Minute weniger als ein voller Tag. Prüfen Sie bei der Gelegenheit die Zeitzone im Profil, denn start schreiben Sie im Format YYYY-MM-DD HH:MM:SS, und gelesen wird es nach dieser Einstellung. profileGet gibt sie als timezone zurück, als Abstand zu GMT in Minuten, GMT+02:00 kommt also als 120 an.

Kann ich auf jedem Plan eine Aufnahme in 2160p verlangen?

Nein, welche Stufe Ihr Konto wirklich nutzen kann, entscheidet Ihr Plan und nicht die API. Der kostenlose Starter nimmt bis 1080p auf, ebenso bezahlte Pläne unter 500 Teilnehmern, und Pläne ab 500 Teilnehmern reichen bis 2160p. recordQuality selbst nimmt 0 für 480p, 1 für 720p, 2 für 1080p, 3 für 2K und 4 für 2160p. Was in jedem Plan steckt, listet die Preisseite auf.

Meine Referenten fliegen ständig aus dem Raum. Woran liegt das?

Ein Moderatorenlink ist für eine einzige Person gedacht, ein zweiter Eintritt über denselben Link trennt also immer die erste Sitzung. Diese eine Ursache steckt hinter allen drei üblichen Klagen. Man fliegt aus dem Raum, man kommt nicht hinein, oder drinnen sitzt schon jemand unter dem eigenen Namen. Geben Sie jedem Referenten den Link, der für ihn ausgestellt wurde, moderatorsRooms liefert ihn als moderatorLink für jedes Webinar, an dem er hängt.