Публичный 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 для каждого привязанного вебинара.