Публічний API MyOwnConference

API MyOwnConference дозволяє керувати акаунтом із власного коду. Через нього планують вебінари, ведуть модераторів і учасників, забирають історію відвідувань і чату, а автовебінар проводять цілком від початку до кінця. Панель керування для цього відкривати не потрібно.

Ключ доступу

Кожен запит проходить перевірку за унікальним ключем, який система видає особисто вам. Увійдіть у панель керування, відкрийте розділ «Профіль» ("Profile") і знайдіть поле «Ключ API» ("API key").

Підозрюєте, що ключ потрапив у чужі руки? Випустіть новий. Кнопка оновлення у вигляді двох стрілок стоїть поряд із полем «Ключ API» ("API key"). Натисніть її, і старий ключ перестане працювати тієї ж миті, коли зʼявиться новий. Нікому не віддавайте ключ, крім програмістів і тих, кому ви й так довірили доступ до панелі керування.

Усі звернення до API пишуться в журнал і зберігаються 365 днів. Якщо за вашим ключем запросять дані, які акаунту не належать, акаунт блокується автоматично. Гроші в такому разі ми не повертаємо і претензій не приймаємо, тож ставтеся до ключа як до пароля.

Формат запиту

Запити йдуть через HTTPS на окремий домен, https://api.mywebinar.com. Формат у них JSON, а надсилати їх потрібно методом POST усередині одного поля даних з іменем request. Будь-який інший спосіб щоразу повертає помилку.

Усе, що записано в цьому документі як %--text--%, це заповнювач. Підставте замість нього своє значення, перш ніж надсилати запит.

Запит несе або іменовані параметри.

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

Або простий список значень.

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

key і action обовʼязкові завжди. Команда не бере додаткових параметрів? Тоді надішліть для params порожній масив.

Формат відповіді

Відповідь завжди приходить у JSON і поряд із результатом повторює вихідний запит. Форм у неї три.

Успіх із даними.

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

Успіх без даних.

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

Помилка і пояснення, що пішло не так.

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

Повідомлення про успіх і про помилку приходять англійською, хоч би якою мовою користувався акаунт.

Приклад на 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 );

Приклад на 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();

Далі всі приклади на PHP.

Обмеження текстових полів

У більшості команд обмеження однакові, тому вони зібрані тут, а не повторюються в кожної.

В іменах припустимий будь-який символ, крім зворотного апострофа і ^~!@#$%^&*()+=[{}]\|:;,<>/?. У вашому власному імені, у назвах груп і в іменах віртуальних учасників не можна ставити ще й крапку. У компаніях, відділах і містах припустимий будь-який символ.

Команди профілю

profileGet

Повертає профіль цілком або лише запитані поля.

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

Щоб отримати все, надішліть порожній масив params.

profileSet

Оновлює профіль цілком або частинами. Передайте кілька параметрів одним масивом, і вони зміняться разом.

$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 приймає ті самі поля, крім email, який через API не змінюється. Натомість він бере password, від 6 до 64 символів.

Команди модераторів

Модератори це люди, які ведуть ваші вебінари. Модератор, створений під час реєстрації, вважається головним, його ж називають адміністратором акаунта. У панелі керування він позначений зірочкою, і видалити його не можна. Йому відкриті всі вебінари і всі завантажені файли.

moderatorsCreate

Створює модератора за іменем і адресою пошти.

$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

Видаляє одного модератора або одразу масив. Адреси передавайте простим списком. На відміну від панелі керування, API тут не захищає головного модератора, тож його адресу до списку не включайте.

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

moderatorsSet

Змінює імʼя або адресу модератора, а ще завантажує картинку, яка показується замість камери.

Закодувати картинку руками допомагає команда cat /path/to/file/test.png | base64.

moderatorsList

Повертає ваших модераторів. Усі параметри нижче необовʼязкові й поєднуються в одному запиті.

У відповіді бувають name, email, registered (дата додавання модератора з точністю до секунди), main (YES у головного модератора) і avatar (YES, коли камеру замінює картинка).

moderatorsAddToWebinar

Привʼязує одного або кількох модераторів до вебінару. Привʼязаний модератор стає ведучим цього заходу і починає отримувати запрошення та нагадування.

$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 необовʼязковий. Поставте YES, щоб запрошення пішло одразу, або NO, щоб воно пішло за звичайним розкладом.

moderatorsRemoveFromWebinar

Відвʼязує модераторів від вебінару і знімає з них права доступу. Посилання-запрошення їм більше не приходять, іншого шляху на захід теж не лишається. Параметри ті самі, alias і email, що й у команди вище.

moderatorsRooms

За адресою пошти повертає всі поточні й майбутні вебінари, до яких привʼязаний модератор. У кожному записі лежать alias, name, description, start, timezone, duration і moderatorLink.

Посилання модератора розраховане на одну людину. Модератори, які роздають своє посилання, приходять з однією з трьох скарг. Їх викидає з кімнати, вони не можуть увійти, або всередині вже хтось сидить під їхнім імʼям. Причина у всіх трьох одна. Другий вхід за тим самим посиланням завжди обриває першу сесію, тому відкривати кімнату чужим посиланням не варто нікому.

Команди учасників

attendeesCreate

Створює учасника за адресою пошти та імʼям.

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

В адресах учасників припустимі англійські літери й цифри.

attendeesSet

Оновлює вже створеного учасника. Упізнайте його за email і надішліть ті поля, які хочете змінити.

Приймаються також skype і position.

attendeesDelete

Видаляє одного учасника або масив, звернення йде за адресою пошти.

attendeesList

Повертає раніше створених учасників з фільтрами, сортуванням і розбивкою на сторінки.

У fields можна просити name, email, phone, skype, company, department, city, born, creation_date, country і type. Якщо передати ще й alias, можна додати notified (скільки запрошень пішло) і link (посилання учасника на вхід).

attendeesAddToWebinar і attendeesRemoveFromWebinar

Привʼязують учасників до запланованого вебінару або знімають їх з нього. Обидві беруть alias і масив attendees з адресами пошти. Привʼязуються тільки учасники, які вже є у вашому списку й можуть отримувати листи, а решта адрес пропускається без помилки, тож нових учасників спершу створіть через 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

За адресою учасника повертає всі вебінари, на які його запросили. У кожному записі лежать alias, name, description, start, timezone, duration і attendeeLink.

Групи учасників

attendeesUnbanned

Знімає блокування з учасника, якого заблокували у вебінарній кімнаті. У email передайте одну адресу.

Команди вебінарів

Майже все, що нижче, звертається за alias, унікальним ідентифікатором вебінару. Його повертає webinarsCreate, і він же стоїть кодом у посиланні на вебінар.

webinarsCreate

Планує вебінар і повертає потрібні вам посилання.

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

У відповіді приходить alias, а разом з ним webinarLink для публічної сторінки і mainModeratorLink для головного модератора.

start записується у форматі YYYY-MM-DD HH:MM:SS і читається в часовому поясі з вашого профілю. duration рахується у хвилинах і не може бути більшим за 1440, це рівно доба.

webinarsSet

Змінює будь-яке налаштування раніше запланованого вебінару.

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

Параметри верхнього рівня такі.

А це налаштування кімнати.

Режим запису задають ключем з порожнім значенням, де ключ це імʼя самого режиму, наприклад recordWebCams => "".

Ще три перемикачі вирішують, що потрапить у файл. recordUsers кладе в запис список учасників, recordModer друкує імʼя кожного модератора на його камері, а recordChat додає чат. Варто передати будь-який із трьох, навіть зі значенням NO, і режим сам перемикається на recordWhole.

recordQuality задає роздільну здатність. 0 пише в 480p (800x460), 1 у 720p (1280x720), 2 у 1080p (1920x1080), 3 у 2K (2048x1080), а 4 у 2160p. Який рівень реально доступний акаунту, вирішує тариф, а не API. Безкоштовний Starter пише до 1080p, стільки ж дають платні тарифи менше ніж на 500 учасників, а тарифи від 500 учасників доходять до 2160p. Що входить у кожен тариф, перелічує сторінка тарифів.

webinarsDelete

Повністю видаляє запланований вебінар, звернення за alias.

webinarsClone

Копіює вебінар на нову date у форматі YYYY-MM-DD і повертає нові alias, webinarLink і mainModeratorLink.

webinarsList

Повертає ваші вебінари.

У записі бувають name, description, created (час створення в GMT+0), alias, start і language.

webinarsGetInfo

Повертає все, що система знає про один вебінар. У відповіді є alias, name, description, start, duration, close, language, google_id, yandex_id, created, status, records (число зроблених записів) і блок settings з перемикачами кімнати, колірною темою, полями сторінки входу і групою.

webinarsGetLettersInfo і webinarsSetLetters

webinarsGetLettersInfo повертає листи-запрошення, налаштовані для вебінару, кожен з enabled, status і text.

webinarsSetLetters їх змінює. Команда бере alias, type, прапорець enabled зі значенням YES або NO і text, підпис у HTML до 2000 символів, який додається до листа. Надішліть порожній text, і підпис зникне.

Лист 1HOUR вимкнути не можна.

webinarsLettersOff і webinarsLettersOn

Зупиняють або знову запускають усі листи-запрошення одного вебінару, звернення за alias.

webinarsOnlineList

Повертає тих, хто зараз у кімнаті, розділяючи їх на moderators і guests.

webinarsRecordsList і webinarsRecordDelete

webinarsRecordsList повертає записи вебінару, а без alias записи всього акаунта. У кожного є id, name, status (recording, поки вебінар ще записується, process, поки файл готується, і ready, коли його можна завантажити), added, size у байтах, duration у секундах, link для перегляду і download_link для завантаження.

webinarsRecordDelete прибирає один запис за id, отриманим з цього списку.

webinarsFilesList

Повертає файли з вашого сховища, а з alias тільки файли одного вебінару. Передайте й type, бо без нього список прийде порожнім. PRESENTATION поверне презентації та зображення, а MEDIA поверне відео- й аудіофайли (.mp4, .mov, .webm, .mkv і .mp3) разом з відео з YouTube і Vimeo. У кожного файлу є id, name, added, size, duration (секунди у медіа або число слайдів у презентації), link і download_link.

webinarsHistory

Повертає журнал вебінару. Значення chats у type віддає всі повідомлення текстового чату, а visits віддає історію відвідувань. У рядку чату лежать час, імʼя, текст повідомлення, мітка G або M для гостя чи модератора і пошта гостя. У записі про відвідування лежать імʼя, та сама мітка G або M, країна, пошта, IP-адреса, час першого входу й останнього виходу і uptime, частка вебінару у відсотках, яку людина провела в кімнаті. Для постійної кімнати передайте ще date у форматі YYYY-MM-DD.

Команди автоматизації

Ці команди і є механіка автовебінарів. Вони наповнюють кімнату віртуальними модераторами та учасниками, пишуть у чат від їхнього імені, ведуть слайди і відео. А коли ви закінчили, вони завершують захід. Усе йде за вашим розкладом, а не за розкладом ведучого. Блокування чату, слайди, відео і webinarsFinish працюють через віртуального модератора, тож спершу посадіть його в кімнату через webinarsAddModerToRoom. Без нього ці команди повернуть помилку.

webinarsAddModerToRoom і webinarsRemoveModerFromRoom

webinarsAddModerToRoom садить у кімнату віртуального модератора. Команда бере alias і email модератора, створеного через moderatorsCreate, а кімната показує імʼя цього модератора. webinarsRemoveModerFromRoom виводить цього модератора назад, звернення за alias і 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 і webinarsGetBotsList

webinarsAddBotToRoom садить у кімнату віртуального учасника. Команда бере alias, name і country, дволітерний код країни на кшталт US, DE, FR, PL або UA. У відповіді приходить id, який знадобиться далі.

webinarsRemoveBotFromRoom прибирає його з кімнати, звернення за alias і id, а webinarsGetBotsList повертає всіх віртуальних учасників, підключених до вебінару просто зараз.

webinarsBotMessage

Надсилає повідомлення в чат від імені віртуального модератора або віртуального учасника.

Керування чатом

webinarsLockChat забороняє живим учасникам писати в чат, а webinarsUnlockChat знову дозволяє. Модератори і ведучі пишуть завжди, тож заборона чату бʼє тільки по учасниках.

webinarsLinkLockInChat і webinarsLinkUnlockInChat роблять те саме з посиланнями, забороняючи або дозволяючи їх між живими учасниками. Усі чотири беруть тільки alias.

Слайди і відео

webinarsStartPresentation показує слайд живим учасникам. Команда бере alias, id презентації з webinarsFilesList і slide, номер сторінки для показу. webinarsStopPresentation прибирає презентацію з екрана, достатньо одного alias.

webinarsStartVideo програє відеофайл, ролик з YouTube або ролик з Vimeo, беручи alias та id файлу з webinarsFilesList. Команда програє і запис, за його id з webinarsRecordsList. webinarsStopVideo зупиняє відтворення і бере тільки alias.

webinarsFinish

Завершує вебінар і відключає всіх, хто в кімнаті. Команда бере alias і, як команди чату, слайдів і відео, потребує віртуального модератора в кімнаті.

Якщо тут щось не так

Помітили в цьому документі помилку чи неточність? Напишіть нам в онлайн-чат. Ми перевіримо і виправимо сторінку.

MyOwnConference може змінити або доповнити цей документ будь-коли. Працюючи за ним, ви з цим погоджуєтеся.

Часті питання

Що робити, якщо мій ключ API витік?

Негайно випустіть новий кнопкою оновлення у вигляді двох стрілок, вона стоїть поряд із полем «Ключ API» ("API key") у розділі «Профіль» ("Profile"). Старий ключ перестане працювати тієї ж миті, коли зʼявиться новий. Усі звернення до API пишуться в журнал і зберігаються 365 днів. Якщо за вашим ключем запросять дані, які акаунту не належать, акаунт блокується автоматично, і тоді ми не повертаємо гроші й не приймаємо претензій.

Кожен мій запит повертає помилку. Що я роблю не так?

Перевірте спочатку не команду, а спосіб надсилання. Запити йдуть через HTTPS на https://api.mywebinar.com методом POST, а JSON лежить усередині одного поля даних з іменем request. Будь-який інший спосіб щоразу повертає помилку. key і action обовʼязкові завжди, а коли команда не бере додаткових параметрів, для params усе одно йде порожній масив.

Чи можна запланувати вебінар довший за добу?

Ні, duration рахується у хвилинах і не може бути більшим за 1440, це рівно доба. Заодно перевірте часовий пояс у профілі, адже start записується у форматі YYYY-MM-DD HH:MM:SS і читається саме за цим налаштуванням. profileGet віддає його як timezone, зміщенням від GMT у хвилинах, тож GMT+02:00 приходить як 120.

Чи можна просити запис у 2160p на будь-якому тарифі?

Ні, який рівень реально доступний акаунту, вирішує тариф, а не API. Безкоштовний Starter пише до 1080p, стільки ж дають платні тарифи менше ніж на 500 учасників, а тарифи від 500 учасників доходять до 2160p. Сам recordQuality приймає 0 для 480p, 1 для 720p, 2 для 1080p, 3 для 2K і 4 для 2160p. Що входить у кожен тариф, перелічує сторінка тарифів.

Моїх ведучих постійно викидає з кімнати. Чому так?

Посилання модератора розраховане на одну людину, тому другий вхід за тим самим посиланням завжди обриває першу сесію. Одна ця причина стоїть за всіма трьома звичними скаргами. Ведучого викидає з кімнати, не пускає всередину, або всередині вже сидить хтось під його імʼям. Дайте кожному ведучому те посилання, що виписане особисто йому, його повертає moderatorsRooms полем moderatorLink для кожного привʼязаного вебінару.