API pubblica di MyOwnConference

L'API di MyOwnConference ti fa gestire l'account dal tuo codice. Con questa programmi webinar, gestisci moderatori e partecipanti, prendi la storia delle presenze e della chat, e conduci un evento automatizzato dall'inizio alla fine. Nessuna di queste cose chiede di tenere aperto il pannello di controllo.

La tua chiave di accesso

Ogni richiesta passa il controllo con una chiave unica, che il sistema genera per te. Entra nel pannello di controllo, apri la sezione «Profilo» ("Profile") e cerca il campo «Chiave API» ("API key").

Sospetti che la chiave sia finita in mani altrui? Generane una nuova. Il pulsante di aggiornamento, disegnato come due frecce, sta accanto al campo «Chiave API» ("API key"). Premilo e la vecchia chiave smette di funzionare nell'istante in cui compare la nuova. Non dare la chiave a nessuno, tranne ai programmatori e a chi ha già accesso al tuo pannello di controllo.

Tutte le chiamate all'API finiscono nel registro e restano lì per 365 giorni. Se con la tua chiave qualcuno chiede dati che non appartengono al tuo account, l'account si blocca da solo. In quel caso non restituiamo il denaro e non accettiamo reclami, quindi tratta la chiave come una password.

Formato della richiesta

Le richieste viaggiano in HTTPS verso un dominio dedicato, https://api.mywebinar.com. Il formato è JSON, e le mandi con il metodo POST dentro un solo campo dati di nome request. Qualsiasi altra strada restituisce un errore ogni volta.

Tutto quello che in questo documento è scritto come %--text--% è un segnaposto. Al suo posto metti il tuo valore prima di inviare la richiesta.

Una richiesta porta parametri con un nome.

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

Oppure porta un semplice elenco di valori.

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

key e action servono sempre. Il comando non prende parametri in più? Allora manda per params un array vuoto.

Formato della risposta

La risposta arriva sempre in JSON e accanto al risultato ripete la richiesta di partenza. Le forme sono tre.

Successo con dati.

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

Successo senza dati.

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

Errore, con la descrizione di quello che è andato storto.

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

I messaggi di successo e di errore tornano in inglese, qualunque lingua usi il tuo account.

Esempio in 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 );

Esempio in 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();

Gli esempi che seguono sono tutti in PHP.

Limiti dei campi di testo

Quasi tutti i comandi hanno gli stessi limiti, quindi li raccogliamo qui invece di ripeterli a ogni voce.

Nei nomi va bene qualsiasi carattere, tranne l'accento grave e ^~!@#$%^&*()+=[{}]\|:;,<>/?. Il tuo nome, i nomi dei gruppi e quelli dei partecipanti virtuali non possono contenere nemmeno il punto. In aziende, reparti e città va bene qualsiasi carattere.

Comandi del profilo

profileGet

Restituisce il profilo intero, oppure solo i campi che chiedi.

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

Per avere tutto, manda un array params vuoto.

profileSet

Aggiorna il profilo per intero o a pezzi. Passa più parametri in un solo array e cambiano insieme.

$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 accetta gli stessi campi tranne email, che dall'API non si può cambiare. In più prende password, da 6 a 64 caratteri.

Comandi dei moderatori

I moderatori sono le persone che conducono i tuoi webinar. Quello creato al momento della registrazione è il moderatore principale, chiamato anche amministratore dell'account. Nel pannello di controllo lo trovi con una stella accanto, e cancellarlo non si può. Arriva a ogni webinar e a ogni file caricato.

moderatorsCreate

Crea un moderatore da un nome e un indirizzo 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

Elimina un moderatore o un intero array. Gli indirizzi si passano come semplice elenco. A differenza del pannello di controllo, qui l'API non protegge il moderatore principale, quindi lascia il suo indirizzo fuori dall'elenco.

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

moderatorsSet

Cambia il nome o l'indirizzo di un moderatore, e carica anche un'immagine da mostrare al posto della webcam.

Per codificare un'immagine a mano, lancia cat /path/to/file/test.png | base64.

moderatorsList

Restituisce i tuoi moderatori. I parametri qui sotto sono tutti facoltativi e si combinano in una sola richiesta.

Nella risposta trovi name, email e registered, la data in cui il moderatore è entrato, al secondo. Ci sono poi main (YES sul moderatore principale) e avatar (YES quando un'immagine sostituisce la camera).

moderatorsAddToWebinar

Lega uno o più moderatori a un webinar. Il moderatore legato diventa relatore di quell'evento e comincia a ricevere inviti e promemoria.

$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 è facoltativo. Mettilo a YES perché l'invito parta subito, oppure a NO perché segua il calendario normale.

moderatorsRemoveFromWebinar

Stacca i moderatori da un webinar e toglie loro i diritti di accesso. Non ricevono più i link di invito e perdono ogni altra via per entrare nell'evento. I parametri sono gli stessi del comando sopra, alias e email.

moderatorsRooms

Dall'indirizzo email restituisce tutti i webinar in corso o in arrivo a cui il moderatore è legato. Ogni voce porta alias, name, description, start, timezone, duration e moderatorLink.

Il link di un moderatore vale per una persona sola. I moderatori che girano il proprio link tornano con uno dei tre reclami. Li butta fuori dalla sala, non riescono a entrare, oppure dentro c'è già qualcuno con il loro nome. La causa dei tre è la stessa. Il secondo ingresso con lo stesso link chiude sempre la prima sessione, quindi nessuno dovrebbe aprire una sala con un link che non è suo.

Comandi dei partecipanti

attendeesCreate

Crea un partecipante da un indirizzo email e un 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--%',
  ],
] );

Negli indirizzi dei partecipanti vanno bene lettere inglesi e cifre.

attendeesSet

Aggiorna un partecipante che esiste già. Riconoscilo con email e manda i campi che vuoi cambiare.

Sono accettati anche skype e position.

attendeesDelete

Elimina un partecipante o un array di partecipanti, il riferimento è l'indirizzo email.

attendeesList

Restituisce i partecipanti che hai creato prima, con filtri, ordinamento e divisione in pagine.

In fields puoi chiedere name, email, phone, skype, company, department, city, born, creation_date, country e type. Se passi anche alias, puoi aggiungere notified (quanti inviti sono partiti) e link (il link di ingresso del partecipante).

attendeesAddToWebinar e attendeesRemoveFromWebinar

Legano i partecipanti a un webinar programmato, oppure li tolgono. Entrambi prendono alias e un array attendees di indirizzi email. Vengono legati solo i partecipanti già presenti nel tuo elenco che possono ricevere email, e gli altri indirizzi vengono saltati senza errore, quindi crea prima i nuovi partecipanti con 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

Dall'indirizzo del partecipante restituisce tutti i webinar a cui è stato invitato. Ogni voce porta alias, name, description, start, timezone, duration e attendeeLink.

Gruppi di partecipanti

attendeesUnbanned

Toglie il blocco a un partecipante bandito dalla sala di un webinar. In email passa un solo indirizzo.

Comandi dei webinar

Quasi tutto quello che segue si riferisce ad alias, l'identificatore unico del webinar. Lo restituisce webinarsCreate, ed è anche il codice che vedi nel link del webinar.

webinarsCreate

Programma un webinar e restituisce i link che ti servono.

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

Nella risposta arriva alias, insieme a webinarLink per la pagina pubblica e mainModeratorLink per il moderatore principale.

start si scrive nel formato YYYY-MM-DD HH:MM:SS e si legge nel fuso orario del tuo profilo. duration si conta in minuti e non può superare 1440, cioè esattamente un giorno.

webinarsSet

Cambia qualsiasi impostazione di un webinar programmato prima.

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

I parametri di primo livello sono questi.

E queste sono le impostazioni della sala.

La modalità di registrazione si imposta passando il nome della modalità come chiave con valore vuoto, per esempio recordWebCams => "".

Altri tre interruttori decidono cosa finisce nel file. recordUsers mette l'elenco dei partecipanti nella registrazione, recordModer stampa il nome di ogni moderatore sulla sua camera, e recordChat aggiunge la chat. Basta passare uno qualsiasi dei tre, anche con NO, e la modalità passa da sola a recordWhole.

recordQuality fissa la risoluzione. 0 registra in 480p (800x460), 1 in 720p (1280x720), 2 in 1080p (1920x1080), 3 in 2K (2048x1080) e 4 in 2160p. Quale livello il tuo account possa davvero usare lo decide il piano, non l'API. Lo Starter gratuito registra fino a 720p, i piani a pagamento sotto i 500 partecipanti fino a 1080p, mentre i piani da 500 partecipanti arrivano a 2160p. Cosa comprende ogni piano lo elenca la pagina dei prezzi.

webinarsDelete

Elimina del tutto un webinar programmato, il riferimento è alias.

webinarsClone

Copia un webinar su una nuova date in formato YYYY-MM-DD e restituisce i nuovi alias, webinarLink e mainModeratorLink.

webinarsList

Restituisce i tuoi webinar.

Ogni voce può portare name, description, created (l'ora di creazione in GMT+0), alias, start e language.

webinarsGetInfo

Restituisce tutto quello che il sistema sa di un webinar. La risposta contiene alias, name, description, start, duration, close, language, google_id, yandex_id, created, status, records (il numero di registrazioni fatte finora) e un blocco settings con gli interruttori della sala, il tema, i campi della pagina di ingresso e il gruppo.

webinarsGetLettersInfo e webinarsSetLetters

webinarsGetLettersInfo restituisce le email di invito impostate per un webinar, ognuna con enabled, status e text.

webinarsSetLetters le cambia. Prende alias, un type, il flag enabled con valore YES o NO e text, una firma in HTML fino a 2000 caratteri che si aggiunge al messaggio. Manda text vuoto e la firma sparisce.

Il messaggio 1HOUR non si può spegnere.

webinarsLettersOff e webinarsLettersOn

Fermano o riavviano tutte le email di invito di un webinar, il riferimento è alias.

webinarsOnlineList

Restituisce chi è nella sala in questo momento, diviso in moderators e guests.

webinarsRecordsList e webinarsRecordDelete

webinarsRecordsList restituisce le registrazioni di un webinar, oppure quelle di tutto l'account se ometti alias. Ognuna porta id, name, status (recording mentre il webinar è ancora in registrazione, process mentre il file viene preparato e ready quando si può scaricare), added, size in byte, duration in secondi, link per guardarla e download_link per scaricarla.

webinarsRecordDelete toglie una registrazione con l'id preso da quell'elenco.

webinarsFilesList

Restituisce i file del tuo archivio, oppure solo quelli di un webinar se passi il suo alias. Passa anche type, perché senza di esso l'elenco arriva vuoto. PRESENTATION restituisce presentazioni e immagini, mentre MEDIA restituisce i file video e audio (.mp4, .mov, .webm, .mkv e .mp3) insieme ai video di YouTube e Vimeo. Ogni file porta id, name, added, size, duration (secondi per un media, oppure il numero di slide per una presentazione), link e download_link.

webinarsHistory

Restituisce il registro di un webinar. In type il valore chats dà tutti i messaggi della chat testuale, visits dà la storia delle presenze. Una riga della chat porta l'orario, il nome, il testo del messaggio, la marca G o M per ospite o moderatore e l'indirizzo email dell'ospite. Una voce delle presenze porta il nome, la stessa marca G o M, il paese, l'indirizzo email, l'indirizzo IP, l'ora del primo ingresso e quella dell'ultima uscita, e uptime, la quota del webinar passata nella sala, in percentuale. Per una sala permanente passa anche date nel formato YYYY-MM-DD.

Comandi di automazione

Questi comandi sono la meccanica dietro i webinar automatizzati. Riempiono la sala di moderatori e partecipanti virtuali, scrivono in chat a loro nome, guidano le slide e il video. E quando hai finito, chiudono l'evento. Tutto va sui tuoi tempi, non su quelli di un relatore. I blocchi della chat, le slide, il video e webinarsFinish passano da un moderatore virtuale, quindi prima mettine uno nella sala con webinarsAddModerToRoom. Senza di lui questi comandi restituiscono un errore.

webinarsAddModerToRoom e webinarsRemoveModerFromRoom

webinarsAddModerToRoom mette nella sala un moderatore virtuale. Prende alias e l'email di un moderatore creato con moderatorsCreate, e la sala mostra il nome di quel moderatore. webinarsRemoveModerFromRoom lo porta di nuovo fuori, il riferimento sono 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 mette nella sala un partecipante virtuale. Prende alias, name e country, un codice paese di due lettere come US, DE, FR, PL o UA. Nella risposta arriva l'id, che ti servirà dopo.

webinarsRemoveBotFromRoom porta di nuovo fuori quel partecipante, il riferimento sono alias e id, mentre webinarsGetBotsList restituisce tutti i partecipanti virtuali collegati in quel momento a un webinar.

webinarsBotMessage

Manda un messaggio in chat a nome di un moderatore virtuale o di un partecipante virtuale.

Controlli della chat

webinarsLockChat vieta ai partecipanti veri di scrivere in chat, webinarsUnlockChat glielo permette di nuovo. Moderatori e relatori scrivono sempre, quindi il blocco colpisce solo i partecipanti.

webinarsLinkLockInChat e webinarsLinkUnlockInChat fanno lo stesso con i link, vietandoli o permettendoli tra i partecipanti veri. Tutti e quattro prendono solo alias.

Slide e video

webinarsStartPresentation mostra una slide ai partecipanti veri. Prende alias, l'id della presentazione da webinarsFilesList e slide, il numero della pagina da mostrare. webinarsStopPresentation toglie la presentazione dallo schermo, gli basta alias.

webinarsStartVideo riproduce un file video, un filmato di YouTube o uno di Vimeo, prendendo alias e l'id del file da webinarsFilesList. Riproduce anche una registrazione, con il suo id da webinarsRecordsList. webinarsStopVideo ferma la riproduzione e prende solo alias.

webinarsFinish

Chiude il webinar e disconnette tutti quelli che stanno nella sala. Prende alias e, come i comandi per chat, slide e video, ha bisogno di un moderatore virtuale nella sala.

Se qui c'è qualcosa che non va

Hai notato un errore o un'imprecisione in questo documento? Scrivicelo nella chat online. Controlliamo e correggiamo la pagina.

MyOwnConference può cambiare o ampliare questo documento in qualsiasi momento. Lavorando su questo testo, lo accetti.

Domande frequenti

Cosa faccio se la mia chiave API finisce in giro?

Generane subito una nuova con il pulsante di aggiornamento, disegnato come due frecce, accanto al campo «Chiave API» ("API key") nella sezione «Profilo» ("Profile"). La vecchia chiave smette di funzionare nell'istante in cui compare la nuova. Tutte le chiamate all'API finiscono nel registro e restano lì per 365 giorni. Se con la tua chiave qualcuno chiede dati che non appartengono al tuo account, l'account si blocca da solo. In quel caso non restituiamo il denaro e non accettiamo reclami.

Ogni richiesta che mando torna come errore. Cosa sbaglio?

Controlla prima il modo di inviare, non il comando. Le richieste viaggiano in HTTPS verso https://api.mywebinar.com con il metodo POST, e il JSON sta dentro un solo campo dati di nome request. Qualsiasi altra strada restituisce un errore ogni volta. key e action servono sempre, e quando un comando non prende parametri in più, per params parte comunque un array vuoto.

Posso programmare un webinar più lungo di un giorno?

No, duration si conta in minuti e non può superare 1440, cioè esattamente un giorno. Controlla anche il fuso orario nel profilo, perché start si scrive nel formato YYYY-MM-DD HH:MM:SS e si legge proprio su quell'impostazione. profileGet lo restituisce come timezone, scarto da GMT in minuti, quindi GMT+02:00 arriva come 120.

Posso chiedere una registrazione in 2160p su qualsiasi piano?

No, quale livello il tuo account possa davvero usare lo decide il piano, non l'API. Lo Starter gratuito registra fino a 720p, i piani a pagamento sotto i 500 partecipanti fino a 1080p, mentre i piani da 500 partecipanti arrivano a 2160p. recordQuality da parte sua prende 0 per 480p, 1 per 720p, 2 per 1080p, 3 per 2K e 4 per 2160p. Cosa comprende ogni piano lo elenca la pagina dei prezzi.

I miei relatori vengono buttati fuori dalla sala in continuazione. Da cosa dipende?

Il link di un moderatore vale per una persona sola, quindi il secondo ingresso con lo stesso link chiude sempre la prima sessione. Quell'unica causa sta dietro tutti e tre i reclami soliti. Il relatore viene buttato fuori, non riesce a entrare, oppure dentro c'è già qualcuno con il suo nome. Dai a ogni relatore il link scritto per lui, quello che moderatorsRooms restituisce come moderatorLink per ogni webinar a cui è legato.