Publiczne API MyOwnConference

API MyOwnConference pozwala sterować kontem z własnego kodu. Zaplanujesz przez nie webinary, zajmiesz się moderatorami i uczestnikami, pobierzesz historię obecności i czatu, a automatyczny webinar przeprowadzisz od początku do końca. Panelu sterowania otwierać do tego nie trzeba.

Klucz dostępu

Każde zapytanie potwierdza unikalny klucz, który system wystawia osobiście tobie. Zaloguj się do panelu sterowania, otwórz sekcję «Profil» ("Profile") i znajdź pole «Klucz API» ("API Key").

Podejrzewasz, że klucz trafił w cudze ręce? Wygeneruj nowy. Przycisk odświeżania w postaci dwóch strzałek stoi obok pola «Klucz API» ("API Key"). Naciśnij go, a stary klucz przestanie działać w tej samej sekundzie, w której pojawi się nowy. Nikomu klucza nie oddawaj poza programistami i tymi, którym i tak powierzyłeś dostęp do panelu sterowania.

Wszystkie odwołania do API zapisujemy w dzienniku i trzymamy 365 dni. Jeśli twoim kluczem ktoś sięgnie po dane, które do konta nie należą, konto blokuje się automatycznie. W takim wypadku nie zwracamy pieniędzy i nie przyjmujemy reklamacji, więc traktuj klucz jak hasło.

Format zapytania

Zapytania idą po HTTPS na osobną domenę, https://api.mywebinar.com. Mają format JSON, a wysyłasz je metodą POST wewnątrz jednego pola danych o nazwie request. Każdy inny sposób za każdym razem zwraca błąd.

Wszystko, co w tym dokumencie zapisano jako %--text--%, to symbol zastępczy. Podstaw pod niego własną wartość, zanim wyślesz zapytanie.

Zapytanie niesie albo nazwane parametry.

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

Albo zwykłą listę wartości.

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

key i action są wymagane zawsze. Komenda nie bierze dodatkowych parametrów? Wtedy wyślij dla params pustą tablicę.

Format odpowiedzi

Odpowiedź zawsze przychodzi w JSON i obok wyniku powtarza pierwotne zapytanie. Ma trzy postaci.

Sukces z danymi.

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

Sukces bez danych.

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

Błąd i opis tego, co poszło nie tak.

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

Komunikaty o sukcesie i o błędzie przychodzą po angielsku, niezależnie od języka konta.

Przykład w 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 );

Przykład w 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();

Dalej wszystkie przykłady są w PHP.

Ograniczenia pól tekstowych

U większości komend ograniczenia są takie same, więc zebraliśmy je tutaj, zamiast powtarzać przy każdej.

W imionach, firmach, działach i miastach dopuszczamy każdy znak poza ^~!@#$%^&*()+=[{}]\|:;,<>/?.

Komendy profilu

profileGet

Zwraca cały profil albo tylko te pola, o które prosisz.

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

Chcesz dostać wszystko? Wyślij pustą tablicę params.

profileSet

Aktualizuje profil w całości albo częściami. Podaj kilka parametrów jedną tablicą, a zmienią się razem.

$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 przyjmuje te same pola co profileGet.

Komendy moderatorów

Moderatorzy to ludzie, którzy prowadzą twoje webinary. Moderator utworzony przy rejestracji jest głównym, nazywamy go też administratorem konta. W panelu sterowania ma gwiazdkę i usunąć go się nie da. Sięgnie do każdego webinaru i do każdego przesłanego pliku.

moderatorsCreate

Tworzy moderatora z imienia i adresu e-mail.

$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

Usuwa jednego moderatora albo od razu całą tablicę. Adresy podaj zwykłą listą.

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

moderatorsSet

Zmienia imię albo adres moderatora, a przy okazji wgrywa obrazek, który pokaże się zamiast kamery.

Zakodować obrazek ręcznie pomaga komenda cat /path/to/file/test.png | base64.

moderatorsList

Zwraca twoich moderatorów. Wszystkie parametry niżej są opcjonalne i łączą się w jednym zapytaniu.

W odpowiedzi bywają name, email, registered (data dodania moderatora z dokładnością do sekundy), main (YES u głównego moderatora) i avatar (YES, gdy kamerę zastępuje obrazek).

moderatorsAddToWebinar

Wiąże jednego albo kilku moderatorów z webinarem. Powiązany moderator zostaje prelegentem tego wydarzenia i zaczyna dostawać zaproszenia oraz przypomnienia.

$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 jest opcjonalny. Ustaw YES, żeby zaproszenie poszło od razu, albo NO, żeby wyszło w zwykłym terminie.

moderatorsRemoveFromWebinar

Odwiązuje moderatorów od webinaru i zdejmuje z nich prawa dostępu. Linki z zaproszeniem już do nich nie przychodzą, a innej drogi na wydarzenie też nie mają. Parametry są te same, alias i email, co u komendy wyżej.

moderatorsRooms

Po adresie e-mail zwraca wszystkie webinary, z którymi moderator jest powiązany. W każdym wpisie leżą alias, name, description, start, timezone, duration i moderatorLink.

Link moderatora jest przewidziany na jedną osobę. Moderatorzy, którzy rozdają swój link, wracają z jedną z trzech skarg. Wyrzuca ich z pokoju, nie mogą wejść albo w środku siedzi już ktoś pod ich imieniem. Przyczyna wszystkich trzech jest ta sama. Drugie wejście po tym samym linku zawsze zrywa pierwszą sesję, więc nikt nie powinien otwierać pokoju cudzym linkiem.

Komendy uczestników

attendeesCreate

Tworzy uczestnika z adresu e-mail i imienia.

$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--%',
  ],
] );

W adresach uczestników dopuszczamy angielskie litery i cyfry.

attendeesSet

Aktualizuje już utworzonego uczestnika. Rozpoznaj go po email i wyślij te pola, które chcesz zmienić.

Na twoim koncie mogą być jeszcze inne pola, poza wymienionymi.

attendeesDelete

Usuwa jednego uczestnika albo całą tablicę, a wskazujesz go adresem e-mail.

attendeesList

Zwraca wcześniej utworzonych uczestników, z filtrami, sortowaniem i podziałem na strony.

W fields poprosisz o name, email, phone, company, department, city, born, creation_date, country i type. Jest jeszcze notified (ile zaproszeń poszło) oraz link (link uczestnika na wejście, dostępny tylko razem z alias).

attendeesAddToWebinar i attendeesRemoveFromWebinar

Wiążą uczestników z zaplanowanym webinarem albo zdejmują ich z niego. Obie biorą alias i tablicę attendees z adresami e-mail.

$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

Po adresie uczestnika zwraca wszystkie webinary, na które go zaproszono. W każdym wpisie leżą alias, name, description, start, timezone, duration i attendeeLink.

Grupy uczestników

attendeesUnbanned

Zdejmuje blokadę z uczestnika, którego zablokowano w pokoju webinarowym. W email podaj jeden adres albo tablicę adresów.

Komendy webinarów

Prawie wszystko niżej wskazujesz przez alias, unikalny identyfikator webinaru. Zwraca go webinarsCreate, a widać go też jako kod w linku do webinaru.

webinarsCreate

Planuje webinar i zwraca potrzebne ci linki.

$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--%',
  ],
] );

W odpowiedzi przychodzi alias, a razem z nim webinarLink do strony publicznej i mainModeratorLink dla głównego moderatora.

start zapisujesz w formacie YYYY-MM-DD HH:MM:SS, a czytamy go w strefie czasowej z twojego profilu. duration liczy się w minutach i nie może przekroczyć 1439, czyli dokładnie o minutę mniej niż doba.

webinarsSet

Zmienia dowolne ustawienie wcześniej zaplanowanego webinaru.

$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--%',
    ],
  ],
] );

Parametry najwyższego poziomu są takie.

A to są ustawienia pokoju.

Tryb nagrania ustawiasz nazwą trybu w kluczu z pustą wartością, na przykład recordWebCams => "".

Jeszcze trzy przełączniki decydują, co trafi do pliku. recordUsers kładzie w nagraniu listę uczestników, recordModer drukuje imię każdego moderatora na jego kamerze, a recordChat dokłada czat. Ustaw recordUsers albo recordModer, a tryb sam przeskoczy na recordWhole.

recordQuality ustawia rozdzielczość. 0 pisze w 480p (800x460), 1 w 720p (1280x720), 2 w 1080p (1920x1080), 3 w 2K (2048x1080), a 4 w 2160p. Który poziom naprawdę jest dostępny kontu, rozstrzyga plan, a nie API. Darmowy Starter pisze do 1080p, tyle samo dają płatne plany poniżej 500 uczestników, a plany od 500 uczestników sięgają 2160p. Co wchodzi w każdy plan, wylicza strona cennika.

webinarsDelete

Kasuje zaplanowany webinar w całości, a wskazujesz go przez alias.

webinarsClone

Kopiuje webinar na nową date w formacie YYYY-MM-DD i zwraca nowe alias, webinarLink i mainModeratorLink.

webinarsList

Zwraca twoje webinary.

We wpisie bywają name, description, created (czas utworzenia w GMT+0), alias, start i language.

webinarsGetInfo

Zwraca wszystko, co system wie o jednym webinarze, razem z blokiem settings, polem status i records, czyli liczbą zrobionych nagrań. Ilość i postać danych różnią się od konta do konta, więc nie zaszywaj listy pól w kodzie.

webinarsGetLettersInfo i webinarsSetLetters

webinarsGetLettersInfo zwraca maile z zaproszeniem ustawione dla webinaru, każdy z enabled, status i text.

webinarsSetLetters je zmienia. Komenda bierze alias, type, flagę enabled o wartości YES albo NO oraz text, podpis w HTML doklejany do wiadomości. Wyślij pusty text, a podpis zniknie.

Maila 1HOUR wyłączyć się nie da.

webinarsLettersOff i webinarsLettersOn

Zatrzymują albo znów uruchamiają wszystkie maile z zaproszeniem jednego webinaru, wskazanego przez alias.

webinarsOnlineList

Zwraca osoby, które są w pokoju teraz, dzieląc je na moderators i guests.

webinarsRecordsList i webinarsRecordDelete

webinarsRecordsList zwraca nagrania webinaru. Każde ma id, name, status (obróbka albo gotowość do pobrania), added, size w bajtach, duration w sekundach, link do obejrzenia i download_link do pobrania.

webinarsRecordDelete usuwa jedno nagranie po id, wziętym z tej listy.

webinarsFilesList

Zwraca materiały przesłane na webinar. type jest opcjonalny. PRESENTATION zwróci prezentacje i obrazki, a MEDIA zwróci pliki mp3 i mp4 razem z filmami z YouTube i Vimeo. Każdy plik ma id, name, added, size, duration (sekundy u mediów albo liczba slajdów u prezentacji), link i download_link.

webinarsHistory

Zwraca dziennik webinaru. Wartość chats w type odda wszystkie wiadomości czatu tekstowego, a visits odda historię obecności. W wierszu leżą znacznik czasu, imię uczestnika, treść wiadomości, znak g albo m dla gościa lub moderatora oraz adres uczestnika.

Komendy automatyzacji

Te komendy to cała mechanika automatycznych webinarów. Napełniają pokój wirtualnymi moderatorami i uczestnikami, piszą na czacie w ich imieniu, prowadzą slajdy i wideo. A gdy skończysz, zamykają wydarzenie. Wszystko idzie według twojego rozkładu, a nie rozkładu prelegenta.

webinarsAddModerToRoom i webinarsRemoveModerFromRoom

webinarsAddModerToRoom sadza w pokoju wirtualnego moderatora. Komenda bierze alias, unikalny email i name. webinarsRemoveModerFromRoom wyprowadza tego moderatora z powrotem, a wskazujesz go przez alias i 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 i webinarsGetBotsList

webinarsAddBotToRoom sadza w pokoju wirtualnego uczestnika. Komenda bierze alias, name i country, dwuliterowy kod kraju w rodzaju US, DE, FR, PL albo UA. W odpowiedzi przychodzi id, które przyda się dalej.

webinarsRemoveBotFromRoom zabiera to id z powrotem, a webinarsGetBotsList zwraca wszystkich wirtualnych uczestników podłączonych do webinaru w tej chwili.

webinarsBotMessage

Wysyła wiadomość na czat w imieniu wirtualnego moderatora albo wirtualnego uczestnika.

Sterowanie czatem

webinarsLockChat zabrania żywym uczestnikom pisać na czacie, a webinarsUnlockChat znów pozwala. Moderatorzy i prelegenci piszą zawsze, więc blokada czatu bije tylko w uczestników.

webinarsLinkLockInChat i webinarsLinkUnlockInChat robią to samo z linkami, zakazując ich albo pozwalając na nie między żywymi uczestnikami. Wszystkie cztery biorą tylko alias.

Slajdy i wideo

webinarsStartPresentation pokazuje slajd żywym uczestnikom. Komenda bierze alias, id prezentacji z webinarsFilesList i slide, numer strony do pokazania. webinarStopPresentation zdejmuje prezentację z ekranu, wystarczy jeden alias.

webinarsStartVideo odtwarza plik wideo, film z YouTube albo film z Vimeo, biorąc alias i id pliku z webinarsFilesList. webinarsStopVideo wstrzymuje odtwarzanie i bierze tylko alias.

webinarsFinish

Kończy webinar i odłącza wszystkich, którzy są w pokoju. Komenda bierze alias i działa tylko z webinarem, który już się zaczął.

Jeśli coś tu się nie zgadza

Zauważyłeś w tym dokumencie błąd albo nieścisłość? Napisz do nas na czacie online. Sprawdzimy i poprawimy stronę.

MyOwnConference może zmienić albo uzupełnić ten dokument w każdej chwili. Pracując według niego, zgadzasz się na to.

Często zadawane pytania

Co robić, gdy mój klucz API wycieknie?

Natychmiast wygeneruj nowy przyciskiem odświeżania w postaci dwóch strzałek, stoi on obok pola «Klucz API» ("API Key") w sekcji «Profil» ("Profile"). Stary klucz przestanie działać w tej samej sekundzie, w której pojawi się nowy. Wszystkie odwołania do API zapisujemy w dzienniku i trzymamy 365 dni. Jeśli twoim kluczem ktoś sięgnie po dane, które do konta nie należą, konto blokuje się automatycznie, a wtedy nie zwracamy pieniędzy i nie przyjmujemy reklamacji.

Każde moje zapytanie wraca z błędem. Co robię źle?

Sprawdź najpierw nie komendę, a sposób wysyłki. Zapytania idą po HTTPS na https://api.mywebinar.com metodą POST, a JSON leży wewnątrz jednego pola danych o nazwie request. Każdy inny sposób za każdym razem zwraca błąd. key i action są wymagane zawsze, a gdy komenda nie bierze dodatkowych parametrów, dla params i tak wychodzi pusta tablica.

Czy mogę zaplanować webinar dłuższy niż doba?

Nie, duration liczy się w minutach i nie może przekroczyć 1439, czyli dokładnie o minutę mniej niż doba. Sprawdź przy okazji strefę czasową w profilu, bo start zapisujesz w formacie YYYY-MM-DD HH:MM:SS, a czytamy go właśnie według tego ustawienia. profileGet oddaje ją jako timezone, przesunięciem od GMT w minutach, więc GMT+02:00 przychodzi jako 120.

Czy mogę prosić o nagranie w 2160p na dowolnym planie?

Nie, który poziom naprawdę jest dostępny kontu, rozstrzyga plan, a nie API. Darmowy Starter pisze do 1080p, tyle samo dają płatne plany poniżej 500 uczestników, a plany od 500 uczestników sięgają 2160p. Sam recordQuality przyjmuje 0 dla 480p, 1 dla 720p, 2 dla 1080p, 3 dla 2K i 4 dla 2160p. Co wchodzi w każdy plan, wylicza strona cennika.

Moich prelegentów ciągle wyrzuca z pokoju. Dlaczego?

Link moderatora jest przewidziany na jedną osobę, więc drugie wejście po tym samym linku zawsze zrywa pierwszą sesję. Ta jedna przyczyna stoi za wszystkimi trzema zwykłymi skargami. Prelegenta wyrzuca z pokoju, nie wpuszcza do środka albo w środku siedzi już ktoś pod jego imieniem. Daj każdemu prelegentowi ten link, który wystawiono właśnie jemu, zwraca go moderatorsRooms polem moderatorLink dla każdego powiązanego webinaru.