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 cabe qualquer símbolo, tirando o acento grave e ^~!@#$%^&*()+=[{}]\|:;,<>/?. O seu próprio nome, os nomes de grupo e os dos participantes virtuais também não podem ter ponto. Nas empresas, departamentos e cidades cabe qualquer símbolo.

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, exceto email, que não se muda pela API. Leva ainda password, de 6 a 64 caracteres.

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. Ao contrário do painel de controlo, a API não protege aqui o moderador principal, por isso deixe o endereço dele fora da lista.

$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 decorrer ou por vir 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.

Também se aceitam skype e position.

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, skype, company, department, city, born, creation_date, country e type. Se passar também alias, pode juntar notified (quantos convites saíram) e link (o link de entrada do participante).

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. Só se ligam participantes que já estão na sua lista e podem receber emails, e os outros endereços são ignorados sem erro, por isso crie antes os participantes novos com 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

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.

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 1440, ou seja exatamente um dia.

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 passar qualquer um dos três, mesmo com NO, 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é 720p, os planos pagos abaixo de 500 participantes até 1080p. 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. A resposta traz alias, name, description, start, duration, close, language, google_id, yandex_id, created, status, records (o número de gravações feitas até agora) e um bloco settings com os interruptores da sala, o tema de cores, os campos da página de entrada e o grupo.

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 de até 2000 caracteres 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, ou as de toda a conta se omitir alias. Cada uma leva id, name, status (recording enquanto o webinar ainda está a ser gravado, process enquanto o ficheiro é preparado e ready quando já se pode 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 os ficheiros do seu armazenamento, ou só os de um webinar se passar o alias dele. Passe também type, porque sem ele a lista chega vazia. PRESENTATION devolve apresentações e imagens, e MEDIA devolve ficheiros de vídeo e áudio (.mp4, .mov, .webm, .mkv e .mp3) 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. Uma linha do chat guarda a hora, o nome, o texto da mensagem, uma marca G ou M para convidado ou moderador e o email do convidado. Uma entrada de presença guarda o nome, a mesma marca G ou M, o país, o email, o endereço IP, a hora da primeira entrada e a da última saída, e uptime, a parte do webinar que a pessoa passou na sala, em percentagem. Numa sala permanente passe ainda date no formato YYYY-MM-DD.

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. Os bloqueios do chat, os diapositivos, o vídeo e webinarsFinish atuam através de um moderador virtual, por isso sente primeiro um na sala com webinarsAddModerToRoom. Sem ele, estes comandos devolvem um erro.

webinarsAddModerToRoom e webinarsRemoveModerFromRoom

webinarsAddModerToRoom senta um moderador virtual numa sala. Leva alias e o email de um moderador criado com moderatorsCreate, e a sala mostra o nome desse moderador. 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--%',
  ],
] );

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 tirar esse participante, tratado por alias e 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. webinarsStopPresentation 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. Também toca uma gravação, pelo id que vem de webinarsRecordsList. webinarsStopVideo interrompe a reprodução e leva apenas alias.

webinarsFinish

Encerra o webinar e desliga toda a gente que está na sala. Leva alias e, tal como os comandos do chat, dos diapositivos e do vídeo, precisa de um moderador virtual na sala.

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 1440, ou seja exatamente um dia. 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é 720p, os planos pagos abaixo de 500 participantes até 1080p. 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.