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 dopuszczamy każdy znak poza grawisem i ^~!@#$%^&*()+=[{}]\|:;,<>/?. Twoje własne imię, nazwy grup i imiona wirtualnych uczestników nie mogą też zawierać kropki. W firmach, działach i miastach dopuszczamy każdy znak.

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 poza email, którego przez API zmienić się nie da. Bierze za to password, od 6 do 64 znaków.

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ą. Inaczej niż panel sterowania, API nie chroni tu głównego moderatora, więc zostaw jego adres poza 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 trwające i nadchodzące 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ć.

Przyjmowane są też skype i position.

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, skype, company, department, city, born, creation_date, country i type. Jeśli podasz też alias, możesz dodać notified (ile zaproszeń poszło) oraz link (link uczestnika na wejście).

attendeesAddToWebinar i attendeesRemoveFromWebinar

Wiążą uczestników z zaplanowanym webinarem albo zdejmują ich z niego. Obie biorą alias i tablicę attendees z adresami e-mail. Wiązani są tylko uczestnicy, którzy już są na twojej liście i mogą dostawać e-maile, a pozostałe adresy komenda pomija bez błędu, więc nowych uczestników najpierw utwórz przez attendeesCreate.

$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.

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ć 1440, czyli dokładnie jednej doby.

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. Podaj którykolwiek z tych trzech, nawet z NO, 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 720p, płatne plany poniżej 500 uczestników do 1080p, 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. W odpowiedzi są alias, name, description, start, duration, close, language, google_id, yandex_id, created, status, records (liczba zrobionych nagrań) i blok settings z przełącznikami pokoju, motywem kolorów, polami strony wejścia i grupą.

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 do 2000 znaków 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, a bez alias nagrania całego konta. Każde ma id, name, status (recording, dopóki webinar się nagrywa, process, gdy plik jest przygotowywany, i ready, gdy można go pobrać), 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 pliki zapisane na twoim koncie, a z alias tylko pliki jednego webinaru. Podaj też type, bo bez niego lista przyjdzie pusta. PRESENTATION zwróci prezentacje i obrazki, a MEDIA zwróci pliki wideo i audio (.mp4, .mov, .webm, .mkv i .mp3) 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. Wiersz czatu ma godzinę, imię, treść wiadomości, znak G albo M dla gościa lub moderatora oraz adres e-mail gościa. Wpis obecności ma imię, ten sam znak G albo M, kraj, adres e-mail, adres IP, godzinę pierwszego wejścia i ostatniego wyjścia oraz uptime, czyli procent webinaru spędzony w pokoju. Przy stałym pokoju podaj jeszcze date w formacie YYYY-MM-DD.

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. Blokady czatu, slajdy, wideo i webinarsFinish działają przez wirtualnego moderatora, więc najpierw posadź go w pokoju przez webinarsAddModerToRoom. Bez niego te komendy zwracają błąd.

webinarsAddModerToRoom i webinarsRemoveModerFromRoom

webinarsAddModerToRoom sadza w pokoju wirtualnego moderatora. Komenda bierze alias i email moderatora utworzonego przez moderatorsCreate, a pokój pokazuje imię tego moderatora. 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--%',
  ],
] );

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 wyprowadza tego uczestnika z powrotem, a wskazujesz go przez alias i id, 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. webinarsStopPresentation 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. Odtworzy też nagranie, po jego id z webinarsRecordsList. webinarsStopVideo zatrzymuje odtwarzanie i bierze tylko alias.

webinarsFinish

Kończy webinar i odłącza wszystkich, którzy są w pokoju. Komenda bierze alias i tak jak komendy czatu, slajdów i wideo potrzebuje wirtualnego moderatora w pokoju.

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ć 1440, czyli dokładnie jednej doby. 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 720p, płatne plany poniżej 500 uczestników do 1080p, 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.