Публичный 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 принимает те же поля, что и profileGet.

Команды модераторов

Модераторы это люди, которые ведут ваши вебинары. Модератор, созданный при регистрации, считается главным, его же называют администратором аккаунта. В панели управления он отмечен звёздочкой, и удалить его нельзя. Ему открыт любой вебинар и любой загруженный файл.

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

Удаляет одного модератора или сразу массив. Адреса передаются простым списком.

$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 и отправьте те поля, которые хотите изменить.

В вашем аккаунте могут быть и другие поля, помимо перечисленных.

attendeesDelete

Удаляет одного участника или массив, обращение идёт по адресу почты.

attendeesList

Возвращает ранее созданных участников с фильтрами, сортировкой и разбивкой по страницам.

В fields можно просить name, email, phone, company, department, city, born, creation_date, country и type. Есть ещё notified (сколько приглашений ушло) и link (ссылка участника на вход, доступна только вместе с alias).

attendeesAddToWebinar и attendeesRemoveFromWebinar

Привязывают участников к запланированному вебинару или снимают их с него. Обе берут alias и массив attendees с адресами почты.

$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 считается в минутах и не может быть больше 1439, это ровно на минуту меньше суток.

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 добавляет чат. Стоит выставить recordUsers или recordModer, и режим сам переключается на 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

Возвращает всё, что система знает об одном вебинаре, включая блок settings, поле status и records, число сделанных записей. Объём и вид данных от аккаунта к аккаунту различаются, так что не зашивайте список полей в код.

webinarsGetLettersInfo и webinarsSetLetters

webinarsGetLettersInfo возвращает письма-приглашения, настроенные для вебинара, каждое с enabled, status и text.

webinarsSetLetters их меняет. Команда берёт alias, type, флаг enabled со значением YES или NO и text, подпись в HTML, которая добавляется к письму. Отправьте пустой text, и подпись пропадёт.

Письмо 1HOUR выключить нельзя.

webinarsLettersOff и webinarsLettersOn

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

webinarsOnlineList

Возвращает тех, кто сейчас в комнате, разделяя их на moderators и guests.

webinarsRecordsList и webinarsRecordDelete

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

webinarsRecordDelete убирает одну запись по id, полученному из этого списка.

webinarsFilesList

Возвращает материалы, загруженные в вебинар. type необязателен. PRESENTATION вернёт презентации и изображения, а MEDIA вернёт файлы mp3 и mp4 вместе с видео с YouTube и Vimeo. У каждого файла есть id, name, added, size, duration (секунды у медиа или число слайдов у презентации), link и download_link.

webinarsHistory

Возвращает журнал вебинара. Значение chats в type отдаёт все сообщения текстового чата, а visits отдаёт историю посещений. В строке лежат отметка времени, имя участника, текст сообщения, метка g или m для гостя или модератора и адрес участника.

Команды автоматизации

Эти команды и есть механика автовебинаров. Они наполняют комнату виртуальными модераторами и участниками, пишут в чат от их имени, ведут слайды и видео. А когда вы закончили, они завершают мероприятие. Всё идёт по вашему расписанию, а не по расписанию ведущего.

webinarsAddModerToRoom и webinarsRemoveModerFromRoom

webinarsAddModerToRoom сажает в комнату виртуального модератора. Команда берёт alias, уникальный email и name. 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--%',
    'name'  => '%--moderator-first-and-last-name--%',
  ],
] );

webinarsAddBotToRoom, webinarsRemoveBotFromRoom и webinarsGetBotsList

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

webinarsRemoveBotFromRoom убирает этот id обратно, а webinarsGetBotsList возвращает всех виртуальных участников, подключённых к вебинару прямо сейчас.

webinarsBotMessage

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

Управление чатом

webinarsLockChat запрещает живым участникам писать в чат, а webinarsUnlockChat снова разрешает. Модераторы и ведущие пишут всегда, так что запрет чата бьёт только по участникам.

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

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

webinarsStartPresentation показывает слайд живым участникам. Команда берёт alias, id презентации из webinarsFilesList и slide, номер страницы для показа. webinarStopPresentation убирает презентацию с экрана, достаточно одного alias.

webinarsStartVideo проигрывает видеофайл, ролик с YouTube или ролик с Vimeo, беря alias и id файла из webinarsFilesList. webinarsStopVideo ставит воспроизведение на паузу и берёт только alias.

webinarsFinish

Завершает вебинар и отключает всех, кто в комнате. Команда берёт alias и работает только с вебинаром, который уже начался.

Если здесь что-то не так

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

MyOwnConference может изменить или дополнить этот документ в любой момент. Работая по нему, вы с этим соглашаетесь.

Часто задаваемые вопросы

Что делать, если мой ключ API утёк?

Немедленно выпустите новый кнопкой обновления в виде двух стрелок, она стоит рядом с полем «Ключ API» ("API Key") в разделе «Профиль» ("Profile"). Старый ключ перестанет работать в ту же секунду, когда появится новый. Все обращения к API пишутся в журнал и хранятся 365 дней. Если по вашему ключу запросят данные, которые аккаунту не принадлежат, аккаунт блокируется автоматически, и тогда мы не возвращаем деньги и не принимаем претензии.

Каждый мой запрос возвращает ошибку. Что я делаю не так?

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

Можно ли запланировать вебинар длиннее суток?

Нет, duration считается в минутах и не может быть больше 1439, это ровно на минуту меньше суток. Заодно проверьте часовой пояс в профиле, ведь 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 для каждого привязанного вебинара.