Publieke API van MyOwnConference

Met de API van MyOwnConference bestuur je je account vanuit je eigen code. Je plant webinars, beheert moderators en deelnemers, haalt de aanwezigheid en de chatgeschiedenis op en draait een geautomatiseerd evenement van begin tot eind. Daarvoor hoeft het dashboard niet open te staan.

Je toegangssleutel

Elk verzoek gaat langs een unieke sleutel die het systeem voor je aanmaakt. Log in op het dashboard, open het onderdeel «Profiel» ("Profile") en zoek het veld «API-sleutel» ("API key").

Vermoed je dat je sleutel in verkeerde handen is? Maak een nieuwe aan. De verversknop met de twee pijlen staat naast het veld «API-sleutel» ("API key"). Klik erop, en de oude sleutel stopt op het moment dat de nieuwe verschijnt. Geef je sleutel aan niemand, behalve aan programmeurs en aan mensen die je al toegang tot je dashboard gaf.

Alle API-verzoeken komen in een logboek en blijven 365 dagen bewaard. Wordt je sleutel gebruikt voor gegevens die niet van je account zijn, dan blokkeert het systeem het account automatisch. Geld krijg je in dat geval niet terug en klachten nemen we niet aan, dus behandel de sleutel als een wachtwoord.

De opbouw van een verzoek

Verzoeken gaan over HTTPS naar een apart domein, https://api.mywebinar.com. Ze zijn in JSON, en je stuurt ze met de POST-methode binnen één dataveld met de naam request. Elke andere aanpak levert steeds een fout op.

Alles wat in dit document als %--text--% staat, is een plaatshouder. Vul er je eigen waarde voor in voordat je het verzoek verstuurt.

Een verzoek draagt of benoemde parameters.

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

Of een gewone lijst met waarden.

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

key en action zijn altijd verplicht. Neemt een commando geen extra parameters? Stuur dan een lege array voor params.

De opbouw van een antwoord

Een antwoord komt altijd in JSON terug en herhaalt naast het resultaat je oorspronkelijke verzoek. Er zijn drie vormen.

Een succes met gegevens.

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

Een succes zonder gegevens.

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

Een fout, met uitleg over wat er misging.

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

Meldingen over succes en fouten komen altijd in het Engels terug, ook als je account een andere taal gebruikt.

Voorbeeld 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 );

Voorbeeld 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();

Alle verdere voorbeelden staan in PHP.

Limieten van tekstvelden

De meeste commando's delen dezelfde limieten, dus die staan hier bij elkaar in plaats van bij elk commando opnieuw.

In namen mag elk teken staan, behalve de backtick en ^~!@#$%^&*()+=[{}]\|:;,<>/?. Je eigen naam, groepsnamen en de namen van virtuele deelnemers mogen ook geen punt bevatten. In bedrijven, afdelingen en steden mag elk teken staan.

Profielcommando's

profileGet

Geeft het hele profiel terug, of alleen de velden waar je om vraagt.

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

Stuur een lege array params om alles te krijgen.

profileSet

Werkt het profiel bij, helemaal of gedeeltelijk. Geef meerdere parameters in één array mee en ze veranderen samen.

$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 accepteert dezelfde velden behalve email, dat je via de API niet kunt wijzigen. Daarnaast neemt het password, van 6 tot 64 tekens.

Moderatorcommando's

Moderators zijn de mensen die je webinars presenteren. De moderator die bij je registratie ontstond is de hoofdmoderator, ook wel de accountbeheerder. In het dashboard draagt hij een ster en verwijderen kun je hem niet. Hij bereikt elk webinar en elk geüpload bestand.

moderatorsCreate

Maakt een moderator aan uit een naam en een e-mailadres.

$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

Verwijdert één moderator of een hele array ervan. Geef de e-mailadressen als een gewone lijst mee. Anders dan het dashboard beschermt de API de hoofdmoderator hier niet, dus laat dat adres buiten de lijst.

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

moderatorsSet

Wijzigt de naam of het adres van een moderator, en uploadt ook een afbeelding die in plaats van zijn webcam verschijnt.

Wil je een afbeelding met de hand coderen, gebruik dan cat /path/to/file/test.png | base64.

moderatorsList

Geeft je moderators terug. De parameters hieronder zijn allemaal optioneel en je combineert ze in één verzoek.

Het antwoord kan name, email en registered dragen, de datum waarop de moderator erbij kwam, tot op de seconde. Verder main (YES bij de hoofdmoderator) en avatar (YES als een afbeelding de camera vervangt).

moderatorsAddToWebinar

Koppelt een of meer moderators aan een webinar. Een gekoppelde moderator wordt presentator van dat evenement en krijgt vanaf dan uitnodigingen en herinneringen.

$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 is optioneel. Zet hem op YES om de uitnodiging meteen te sturen, of op NO om hem op het gewone schema mee te laten gaan.

moderatorsRemoveFromWebinar

Koppelt moderators los van een webinar en neemt hun toegangsrechten af. Uitnodigingslinks krijgen ze niet meer, en andere wegen naar het evenement blijven er niet over. De parameters zijn dezelfde alias en email als bij het commando hierboven.

moderatorsRooms

Geeft op basis van een e-mailadres elk lopend of komend webinar terug waaraan die moderator gekoppeld is. Elke regel draagt alias, name, description, start, timezone, duration en moderatorLink.

Een moderatorlink werkt voor één persoon. Moderators die hun link doorgeven komen met een van drie klachten terug. Ze vliegen de ruimte uit, ze komen er niet in, of er zit al iemand onder hun naam. Alle drie hebben dezelfde oorzaak. Een tweede binnenkomst op dezelfde link verbreekt altijd de eerste sessie, dus niemand hoort een ruimte te openen met een link die niet voor hem is uitgegeven.

Deelnemercommando's

attendeesCreate

Maakt een deelnemer aan uit een e-mailadres en een naam.

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

In e-mailadressen van deelnemers mogen Engelse letters en cijfers staan.

attendeesSet

Werkt een bestaande deelnemer bij. Herken hem aan email en stuur daarna de velden die je wilt wijzigen.

Ook skype en position worden geaccepteerd.

attendeesDelete

Verwijdert één deelnemer of een array ervan, aangesproken op e-mailadres.

attendeesList

Geeft eerder aangemaakte deelnemers terug, met filters, sortering en paginering.

In fields vraag je om name, email, phone, skype, company, department, city, born, creation_date, country en type. Stuur je ook alias mee, dan kun je notified (hoeveel uitnodigingen eruit gingen) en link (de toegangslink van de deelnemer) toevoegen.

attendeesAddToWebinar en attendeesRemoveFromWebinar

Koppelen deelnemers aan een gepland webinar, of halen ze eraf. Beide nemen alias plus een array attendees met e-mailadressen. Alleen deelnemers die al in je lijst staan en e-mails kunnen ontvangen worden gekoppeld, andere adressen worden zonder foutmelding overgeslagen. Maak nieuwe deelnemers dus eerst aan met 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

Geeft op basis van een adres elk webinar terug waarvoor die deelnemer is uitgenodigd. Elke regel draagt alias, name, description, start, timezone, duration en attendeeLink.

Deelnemersgroepen

attendeesUnbanned

Heft de blokkade op van een deelnemer die uit een webinarruimte is verbannen. Geef in email één adres mee.

Webinarcommando's

Bijna alles hieronder werkt via alias, het unieke webinar-id. webinarsCreate geeft het terug, en het is ook de code die je in de webinarlink ziet.

webinarsCreate

Plant een webinar en geeft de links terug die je nodig hebt.

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

Het antwoord geeft alias terug, plus webinarLink voor de publieke pagina en mainModeratorLink voor de hoofdmoderator.

start gebruikt het formaat YYYY-MM-DD HH:MM:SS, en die tijd leest het systeem in de tijdzone uit je profiel. duration telt in minuten en mag niet boven 1440 uitkomen, precies een etmaal.

webinarsSet

Wijzigt elke instelling van een webinar dat je eerder plande.

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

Dit zijn de parameters op het bovenste niveau.

En dit zijn de instellingen van de ruimte.

Een opnamemodus zet je door de naam van de modus als sleutel met een lege waarde mee te geven, bijvoorbeeld recordWebCams => "".

Nog drie schakelaars bepalen wat er in het bestand belandt. recordUsers zet de deelnemerslijst in de opname, recordModer drukt de naam van elke moderator op zijn camera, en recordChat neemt de chat mee. Geef je een van de drie mee, zelfs als NO, dan springt de modus vanzelf naar recordWhole.

recordQuality bepaalt de resolutie. 0 neemt op in 480p (800x460), 1 in 720p (1280x720), 2 in 1080p (1920x1080), 3 in 2K (2048x1080) en 4 in 2160p. Welk niveau je account echt aankan, hangt af van je abonnement en niet van de API. Het gratis Starter-abonnement neemt op tot 720p, de betaalde abonnementen onder 500 deelnemers tot 1080p. Abonnementen vanaf 500 deelnemers halen 2160p. Wat er in elk abonnement zit, staat op de tarievenpagina.

webinarsDelete

Verwijdert een gepland webinar volledig, aangesproken op alias.

webinarsClone

Kopieert een webinar naar een nieuwe date in het formaat YYYY-MM-DD en geeft de nieuwe alias, webinarLink en mainModeratorLink terug.

webinarsList

Geeft je webinars terug.

Elke regel kan name, description, created (tijd van aanmaken in GMT+0), alias, start en language dragen.

webinarsGetInfo

Geeft alles terug wat het systeem van één webinar weet. Het antwoord bevat alias, name, description, start, duration, close, language, google_id, yandex_id, created, status, records (het aantal opnames tot nu toe) en een blok settings met de schakelaars van de ruimte, het kleurthema, de velden van de toegangspagina en de groep.

webinarsGetLettersInfo en webinarsSetLetters

webinarsGetLettersInfo geeft de uitnodigingsmails van een webinar terug, elk met enabled, status en text.

webinarsSetLetters wijzigt ze. Het commando neemt alias, een type, een vlag enabled met YES of NO, en text, een HTML-handtekening van hooguit 2000 tekens die aan het bericht vastgaat. Stuur text leeg en de handtekening verdwijnt.

De mail 1HOUR kun je niet uitzetten.

webinarsLettersOff en webinarsLettersOn

Stoppen of hervatten alle uitnodigingsmails van één webinar, aangesproken op alias.

webinarsOnlineList

Geeft terug wie er nu in de ruimte zit, gesplitst in moderators en guests.

webinarsRecordsList en webinarsRecordDelete

webinarsRecordsList geeft de opnames van een webinar terug, of die van het hele account als je alias weglaat. Elke opname draagt id, name en status, dus recording zolang het webinar nog wordt opgenomen, process terwijl het bestand wordt voorbereid en ready zodra het te downloaden is. Verder added, size in bytes, duration in seconden, link om te kijken en download_link om te downloaden.

webinarsRecordDelete haalt één opname weg met de id uit die lijst.

webinarsFilesList

Geeft de bestanden in je opslag terug, of alleen die van één webinar als je de alias meestuurt. Stuur ook type mee, want zonder komt de lijst leeg terug. PRESENTATION geeft presentaties en afbeeldingen, en MEDIA geeft video- en audiobestanden (.mp4, .mov, .webm, .mkv en .mp3) samen met video's van YouTube en Vimeo. Elk bestand draagt id, name, added, size, duration (seconden bij media, of het aantal slides bij een presentatie), link en download_link.

webinarsHistory

Geeft het logboek van een webinar terug. Zet type op chats voor elk bericht uit de tekstchat, of op visits voor de aanwezigheidsgeschiedenis. Een chatregel bevat het tijdstip, de naam, de tekst van het bericht, een G of M voor gast of moderator en het e-mailadres van de gast. Een aanwezigheidsregel bevat de naam, dezelfde G of M, het land, het e-mailadres, het IP-adres, de tijden van de eerste binnenkomst en het laatste vertrek, en uptime, het deel van het webinar dat iemand in de ruimte doorbracht, in procenten. Bij een vaste ruimte stuur je ook date mee in het formaat YYYY-MM-DD.

Automatiseringscommando's

Deze commando's zijn de machinerie achter geautomatiseerde webinars. Ze vullen een ruimte met virtuele moderators en virtuele deelnemers en plaatsen chatberichten onder hun naam. Ze sturen de slides en de video aan, en ze beëindigen het evenement als je klaar bent. Alles loopt op jouw timing en niet op die van een presentator. Chatblokkades, slides, video en webinarsFinish lopen via een virtuele moderator, dus zet er eerst een in de ruimte met webinarsAddModerToRoom. Zonder die moderator geven ze een foutmelding.

webinarsAddModerToRoom en webinarsRemoveModerFromRoom

webinarsAddModerToRoom zet een virtuele moderator in een ruimte. Het neemt alias en het email van een moderator die je met moderatorsCreate hebt aangemaakt, en de ruimte toont de naam van die moderator. webinarsRemoveModerFromRoom haalt die moderator er weer uit, aangesproken op alias en 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 en webinarsGetBotsList

webinarsAddBotToRoom zet een virtuele deelnemer in de ruimte. Het neemt alias, name en country, een landcode van twee letters zoals US, DE, FR, PL of UA. Het antwoord geeft de id terug die je later nodig hebt.

webinarsRemoveBotFromRoom haalt die deelnemer er weer uit, aangesproken op alias en id, en webinarsGetBotsList geeft elke virtuele deelnemer terug die nu met een webinar verbonden is.

webinarsBotMessage

Stuurt een chatbericht namens een virtuele moderator of een virtuele deelnemer.

Chat besturen

webinarsLockChat verbiedt levende deelnemers om in de chat te schrijven en webinarsUnlockChat laat ze weer schrijven. Moderators en presentatoren mogen altijd posten, dus een slot op de chat raakt alleen deelnemers.

webinarsLinkLockInChat en webinarsLinkUnlockInChat doen hetzelfde met links, die ze tussen levende deelnemers blokkeren of toestaan. Alle vier nemen alleen alias.

Slides en video

webinarsStartPresentation toont een slide aan levende deelnemers. Het neemt alias, de id van de presentatie uit webinarsFilesList, en slide, het paginanummer dat op het scherm moet. webinarsStopPresentation haalt de presentatie van het scherm met alleen alias.

webinarsStartVideo speelt een videobestand, een YouTube-clip of een Vimeo-clip af, en neemt alias en de id van het bestand uit webinarsFilesList. Het speelt ook een opname af, via de id uit webinarsRecordsList. webinarsStopVideo stopt het afspelen en neemt alleen alias.

webinarsFinish

Beëindigt het webinar en verbreekt de verbinding van iedereen in de ruimte. Het neemt alias en heeft, net als de commando's voor chat, slides en video, een virtuele moderator in de ruimte nodig.

Als hier iets niet klopt

Zie je een fout of een onnauwkeurigheid in dit document? Vertel het ons in de online chat. Wij controleren het en corrigeren de pagina.

MyOwnConference mag dit document op elk moment wijzigen of aanvullen. Werk je ermee, dan ga je daarmee akkoord.

Veelgestelde vragen

Wat moet ik doen als mijn API-sleutel uitlekt?

Maak meteen een nieuwe aan met de verversknop met de twee pijlen, naast het veld «API-sleutel» ("API key") in het onderdeel «Profiel» ("Profile"). De oude sleutel stopt op het moment dat de nieuwe verschijnt. Alle API-verzoeken komen in een logboek en blijven 365 dagen bewaard. Wordt je sleutel gebruikt voor gegevens die niet van je account zijn, dan blokkeert het systeem het account automatisch. Geld krijg je dan niet terug en klachten nemen we niet aan.

Elk verzoek dat ik stuur komt terug als fout. Wat doe ik verkeerd?

Controleer eerst hoe je verstuurt en pas daarna het commando. Verzoeken gaan over HTTPS naar https://api.mywebinar.com met de POST-methode, en de JSON hoort in één dataveld met de naam request. Elke andere aanpak levert steeds een fout op. key en action zijn altijd verplicht, en neemt een commando geen extra parameters, dan gaat er voor params toch een lege array mee.

Kan ik een webinar plannen dat langer dan een dag duurt?

Nee, duration telt in minuten en mag niet boven 1440 uitkomen, precies een etmaal. Controleer meteen de tijdzone in je profiel, want start gebruikt het formaat YYYY-MM-DD HH:MM:SS en het systeem leest die tijd op die instelling. profileGet geeft hem terug als timezone, als afwijking van GMT in minuten, dus GMT+02:00 komt terug als 120.

Kan ik op elk abonnement om een opname in 2160p vragen?

Nee, welk niveau je account echt aankan hangt af van je abonnement en niet van de API. Het gratis Starter-abonnement neemt op tot 720p, de betaalde abonnementen onder 500 deelnemers tot 1080p, terwijl abonnementen vanaf 500 deelnemers 2160p halen. recordQuality zelf neemt 0 voor 480p, 1 voor 720p, 2 voor 1080p, 3 voor 2K en 4 voor 2160p. Wat er in elk abonnement zit, staat op de tarievenpagina.

Mijn presentatoren vliegen steeds de ruimte uit. Hoe komt dat?

Een moderatorlink werkt voor één persoon, dus een tweede binnenkomst op dezelfde link verbreekt altijd de eerste sessie. Die ene oorzaak zit achter alle drie de gewone klachten, namelijk eruit vliegen, er niet in komen, en al iemand onder je eigen naam aantreffen. Geef elke presentator de link die voor hem is uitgegeven, en die geeft moderatorsRooms terug als moderatorLink bij elk webinar waaraan hij gekoppeld is.