API pública da MyOwnConference

A API da MyOwnConference deixa-o gerir a conta a partir do seu próprio código. Com ela agenda webinars e trata dos moderadores e dos participantes. Retira o histórico de presenças e do chat, e conduz um evento automatizado do princípio ao fim. Para nada disto precisa do painel de controlo aberto.

A sua chave de acesso

Cada pedido passa por uma chave única, que o sistema gera só para si. Entre no painel de controlo, abra a secção «Perfil» ("Profile") e procure o campo «Chave API» ("API Key").

Desconfia que a chave foi parar a outras mãos? Gere uma nova. O botão de atualização, com o desenho de duas setas, fica ao lado do campo «Chave API» ("API Key"). Carregue nele e a chave antiga deixa de funcionar no instante em que a nova aparece. Não entregue a chave a ninguém, tirando programadores e quem já tem a sua confiança para entrar no painel de controlo.

Todos os pedidos à API ficam registados e guardados 365 dias. Se alguém usar a sua chave para chegar a informação que não pertence à conta, o sistema bloqueia-a automaticamente. Nesse caso não devolvemos dinheiro nem aceitamos reclamações, por isso trate a chave como uma senha.

Formato do pedido

Os pedidos vão por HTTPS para um domínio próprio, https://api.mywebinar.com. O formato é JSON, e tem de os enviar pelo método POST dentro de um único campo de dados com o nome request. Qualquer outra via devolve erro de todas as vezes.

Tudo o que neste documento aparece escrito como %--text--% é um marcador de posição. Ponha ali o seu valor antes de enviar o pedido.

O pedido leva parâmetros com nome.

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

Ou leva uma lista simples de valores.

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

key e action são sempre obrigatórios. O comando não leva parâmetros adicionais? Então envie um array vazio em params.

Formato da resposta

A resposta chega sempre em JSON e, ao lado do resultado, repete o pedido original. As formas são três.

Sucesso com dados.

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

Sucesso sem dados.

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

Erro, com a explicação do que correu mal.

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

As mensagens de sucesso e de erro chegam em inglês, seja qual for a língua da conta.

Exemplo em 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 );

Exemplo em 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();

Daqui em diante todos os exemplos vão em PHP.

Limites dos campos de texto

A maioria dos comandos partilha os mesmos limites, por isso ficam reunidos aqui em vez de se repetirem em cada um.

Nos nomes, empresas, departamentos e cidades cabe qualquer símbolo, tirando ^~!@#$%^&*()+=[{}]\|:;,<>/?.

Comandos de perfil

profileGet

Devolve o perfil inteiro, ou apenas os campos que pedir.

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

Para receber tudo, envie um array params vazio.

profileSet

Atualiza o perfil por inteiro ou às partes. Passe vários parâmetros num só array e mudam todos juntos.

$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 aceita os mesmos campos que profileGet.

Comandos de moderadores

Os moderadores são as pessoas que conduzem os seus webinars. O moderador criado no registo é o principal, a quem também se chama administrador da conta. No painel de controlo leva uma estrela e ninguém o consegue apagar. Chega a qualquer webinar e a qualquer ficheiro carregado.

moderatorsCreate

Cria um moderador a partir de um nome e de um endereço de email.

$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

Apaga um moderador ou um array inteiro deles. Os endereços vão numa lista simples.

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

moderatorsSet

Muda o nome ou o email de um moderador, e também carrega uma imagem para mostrar em vez da webcam.

Para codificar uma imagem à mão, use cat /path/to/file/test.png | base64.

moderatorsList

Devolve os seus moderadores. Os parâmetros abaixo são todos opcionais e juntam-se num só pedido.

Na resposta cabem name, email e registered, a data em que o moderador entrou, ao segundo. Há ainda main (YES no moderador principal) e avatar (YES quando uma imagem substitui a câmara).

moderatorsAddToWebinar

Liga um ou vários moderadores a um webinar. O moderador ligado torna-se apresentador desse evento e passa a receber convites e lembretes.

$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 é opcional. Ponha YES para o convite sair já, ou NO para sair pelo horário do costume.

moderatorsRemoveFromWebinar

Desliga moderadores de um webinar e retira-lhes os direitos de acesso. Deixam de receber links de convite e perdem qualquer outra entrada no evento. Os parâmetros são os mesmos alias e email do comando acima.

moderatorsRooms

Pelo endereço de email devolve todos os webinars a que um moderador está ligado. Em cada registo estão alias, name, description, start, timezone, duration e moderatorLink.

O link de um moderador serve uma pessoa só. Os moderadores que espalham o seu link voltam com uma de três queixas. São expulsos da sala, não conseguem entrar, ou já lá está alguém com o nome deles. As três têm a mesma causa. Uma segunda entrada pelo mesmo link corta sempre a primeira sessão, por isso ninguém deve abrir uma sala com um link passado a outra pessoa.

Comandos de participantes

attendeesCreate

Cria um participante a partir de um endereço de email e de um nome.

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

Nos endereços dos participantes cabem letras inglesas e algarismos.

attendeesSet

Atualiza um participante já criado. Reconheça-o por email e envie os campos que quiser mudar.

A sua conta pode ter mais campos além dos que aqui estão.

attendeesDelete

Apaga um participante ou um array deles, tratados pelo endereço de email.

attendeesList

Devolve os participantes que criou antes, com filtros, ordenação e divisão por páginas.

Em fields pode pedir name, email, phone, company, department, city, born, creation_date, country e type. Há ainda notified (quantos convites saíram) e link (o link de entrada do participante, que só chega quando também passa alias).

attendeesAddToWebinar e attendeesRemoveFromWebinar

Ligam participantes a um webinar agendado, ou tiram-nos de lá. Ambos levam alias e um array attendees com endereços de email.

$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

Pelo endereço de um participante devolve todos os webinars para que o convidaram. Em cada registo estão alias, name, description, start, timezone, duration e attendeeLink.

Grupos de participantes

attendeesUnbanned

Levanta o bloqueio a um participante banido de uma sala de webinar. Em email passe um endereço ou um array de endereços.

Comandos de webinars

Quase tudo o que vem abaixo se trata por alias, o identificador único do webinar. webinarsCreate devolve-o, e é também o código que se vê no link do webinar.

webinarsCreate

Agenda um webinar e devolve os links de que precisa.

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

Na resposta chega alias, e com ele webinarLink para a página pública e mainModeratorLink para o moderador principal.

start escreve-se no formato YYYY-MM-DD HH:MM:SS e lê-se no fuso horário do seu perfil. duration conta-se em minutos e não pode passar de 1439, ou seja um minuto a menos do que um dia inteiro.

webinarsSet

Muda qualquer definição de um webinar que agendou antes.

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

Os parâmetros de topo são estes.

E estas são as definições da sala.

O modo de gravação define-se com o nome do modo na chave e o valor vazio, por exemplo recordWebCams => "".

Mais três interruptores decidem o que vai parar ao ficheiro. recordUsers põe a lista de participantes na gravação, recordModer imprime o nome de cada moderador na sua câmara, e recordChat junta o chat. Basta pôr recordUsers ou recordModer e o modo passa sozinho a recordWhole.

recordQuality define a resolução. 0 grava em 480p (800x460), 1 em 720p (1280x720), 2 em 1080p (1920x1080), 3 em 2K (2048x1080) e 4 em 2160p. Que nível a conta consegue mesmo usar, quem decide é o plano e não a API. O plano gratuito Starter grava até 1080p, tanto como os planos pagos abaixo de 500 participantes. Já os planos a partir de 500 participantes chegam a 2160p. O que entra em cada plano está na página de preços.

webinarsDelete

Apaga por completo um webinar agendado, tratado por alias.

webinarsClone

Copia um webinar para uma nova date no formato YYYY-MM-DD e devolve os novos alias, webinarLink e mainModeratorLink.

webinarsList

Devolve os seus webinars.

Cada registo pode levar name, description, created (hora de criação em GMT+0), alias, start e language.

webinarsGetInfo

Devolve tudo o que o sistema sabe sobre um webinar, incluindo o bloco settings, o campo status e records, o número de gravações feitas até agora. O volume e a forma dos dados mudam de conta para conta, por isso não fixe a lista de campos no código.

webinarsGetLettersInfo e webinarsSetLetters

webinarsGetLettersInfo devolve os emails de convite configurados num webinar, cada um com enabled, status e text.

webinarsSetLetters muda-os. Leva alias, um type, um sinalizador enabled com YES ou NO, e text, uma assinatura em HTML que se junta à mensagem. Envie text vazio e a assinatura desaparece.

A mensagem 1HOUR não se desliga.

webinarsLettersOff e webinarsLettersOn

Param ou voltam a lançar todos os emails de convite de um webinar, tratado por alias.

webinarsOnlineList

Devolve quem está na sala neste momento, separado em moderators e guests.

webinarsRecordsList e webinarsRecordDelete

webinarsRecordsList devolve as gravações de um webinar. Cada uma leva id, name, status (em processamento ou pronta a transferir), added, size em bytes, duration em segundos, link para ver e download_link para transferir.

webinarsRecordDelete retira uma gravação pelo id que veio dessa lista.

webinarsFilesList

Devolve o material carregado num webinar. type é opcional. PRESENTATION devolve apresentações e imagens, e MEDIA devolve ficheiros mp3 e mp4 juntamente com vídeos do YouTube e do Vimeo. Cada ficheiro leva id, name, added, size, duration (segundos no som e no vídeo, ou o número de diapositivos numa apresentação), link e download_link.

webinarsHistory

Devolve o registo de um webinar. Ponha chats em type para todas as mensagens do chat de texto, ou visits para o histórico de presenças. Cada linha guarda a marca de tempo, o nome do participante e o texto da mensagem. Junta-lhes uma marca g ou m para convidado ou moderador, e o email do participante.

Comandos de automação

Estes comandos são a mecânica por trás dos webinars automatizados. Enchem a sala de moderadores e participantes virtuais, escrevem no chat em nome deles, conduzem os diapositivos e o vídeo. E quando terminar, encerram o evento. Tudo corre pelo seu horário, não pelo de um apresentador.

webinarsAddModerToRoom e webinarsRemoveModerFromRoom

webinarsAddModerToRoom senta um moderador virtual numa sala. Leva alias, um email único e um name. webinarsRemoveModerFromRoom tira esse moderador de lá, tratado por alias e 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 e webinarsGetBotsList

webinarsAddBotToRoom senta um participante virtual na sala. Leva alias, name e country, um código de país de duas letras como US, DE, FR, PL ou UA. Na resposta chega o id de que vai precisar depois.

webinarsRemoveBotFromRoom volta a retirar esse id, e webinarsGetBotsList devolve todos os participantes virtuais ligados a um webinar neste momento.

webinarsBotMessage

Envia uma mensagem para o chat em nome de um moderador virtual ou de um participante virtual.

Controlo do chat

webinarsLockChat impede os participantes ao vivo de escrever no chat e webinarsUnlockChat volta a deixá-los escrever. Os moderadores e os apresentadores escrevem sempre, por isso trancar o chat só atinge os participantes.

webinarsLinkLockInChat e webinarsLinkUnlockInChat tratam assim dos links, bloqueando-os ou libertando-os entre participantes ao vivo. Os quatro levam apenas alias.

Diapositivos e vídeo

webinarsStartPresentation mostra um diapositivo aos participantes ao vivo. Leva alias, o id da apresentação vindo de webinarsFilesList, e slide, o número da página a mostrar. webinarStopPresentation tira a apresentação do ecrã só com alias.

webinarsStartVideo toca um ficheiro de vídeo, um clipe do YouTube ou um clipe do Vimeo, levando alias e o id do ficheiro de webinarsFilesList. webinarsStopVideo põe a reprodução em pausa e leva apenas alias.

webinarsFinish

Encerra o webinar e desliga toda a gente que está na sala. Leva alias e só funciona num webinar que já começou.

Se aqui houver algo errado

Encontrou um erro ou uma imprecisão neste documento? Diga-nos no chat online. Vamos verificar e corrigir a página.

A MyOwnConference pode alterar ou completar este documento a qualquer momento. Ao trabalhar a partir dele, aceita isso.

Perguntas frequentes

E se a minha chave API for parar a outras mãos?

Gere já uma nova, com o botão de atualização em forma de duas setas, ao lado do campo «Chave API» ("API Key") na secção «Perfil» ("Profile"). A chave antiga deixa de funcionar no instante em que a nova aparece. Todos os pedidos à API ficam registados e guardados 365 dias. Se alguém usar a sua chave para chegar a informação que não pertence à conta, o sistema bloqueia-a automaticamente. Nesse caso não devolvemos dinheiro nem aceitamos reclamações.

Todos os pedidos que envio voltam com erro. O que estou a fazer mal?

Verifique primeiro a via de envio, não o comando. Os pedidos vão por HTTPS para https://api.mywebinar.com pelo método POST, com o JSON dentro de um único campo de dados chamado request. Qualquer outra via devolve erro de todas as vezes. key e action são sempre obrigatórios, e quando um comando não leva parâmetros adicionais, sai na mesma um array vazio em params.

Posso agendar um webinar mais longo do que um dia?

Não, duration conta-se em minutos e não pode passar de 1439, ou seja um minuto a menos do que um dia inteiro. Verifique já agora o fuso horário do perfil, porque start escreve-se no formato YYYY-MM-DD HH:MM:SS e lê-se por essa definição. profileGet devolve-a como timezone, em desvio do GMT em minutos, por isso GMT+02:00 chega como 120.

Posso pedir uma gravação em 2160p em qualquer plano?

Não, quem decide o nível que a conta consegue mesmo usar é o plano, não a API. O plano gratuito Starter grava até 1080p, tanto como os planos pagos abaixo de 500 participantes. Já os planos a partir de 500 participantes chegam a 2160p. O próprio recordQuality aceita 0 para 480p, 1 para 720p, 2 para 1080p, 3 para 2K e 4 para 2160p. O que entra em cada plano está na página de preços.

Os meus apresentadores são expulsos da sala a toda a hora. Porquê?

O link de um moderador serve uma pessoa só, por isso uma segunda entrada pelo mesmo link corta sempre a primeira sessão. Essa causa única está por trás das três queixas do costume. O apresentador é expulso da sala, não consegue entrar, ou já lá está alguém com o nome dele. Dê a cada apresentador o link passado em seu nome, que moderatorsRooms devolve como moderatorLink para cada webinar a que está ligado.