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, bedrijven, afdelingen en steden mag elk teken staan, behalve ^~!@#$%^&*()+=[{}]\|:;,<>/?.

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 als profileGet.

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.

$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 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.

Je account kan meer velden dragen dan deze lijst noemt.

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, company, department, city, born, creation_date, country en type. Er is ook notified (hoeveel uitnodigingen eruit gingen) en link (de toegangslink van de deelnemer, alleen beschikbaar als je ook alias meestuurt).

attendeesAddToWebinar en attendeesRemoveFromWebinar

Koppelen deelnemers aan een gepland webinar, of halen ze eraf. Beide nemen alias plus een array attendees met e-mailadressen.

$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 of een array ervan 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 1439 uitkomen, precies één minuut minder dan 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. Zet je recordUsers of recordModer aan, 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 1080p, net als de betaalde abonnementen onder 500 deelnemers. 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, inclusief het blok settings, het veld status en records, het aantal opnames tot nu toe. Omvang en vorm van die gegevens verschillen per account, dus zet de lijst met velden niet vast in je code.

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 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. Elke opname draagt id, name en status, dus in verwerking of klaar om te downloaden. 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 het materiaal terug dat naar een webinar is geüpload. type is optioneel. PRESENTATION geeft presentaties en afbeeldingen, en MEDIA geeft mp3- en mp4-bestanden 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. In elke regel staan het tijdstip, de naam van de deelnemer en de tekst van het bericht. Daarnaast een g of m voor gast of moderator, en het adres van de deelnemer.

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.

webinarsAddModerToRoom en webinarsRemoveModerFromRoom

webinarsAddModerToRoom zet een virtuele moderator in een ruimte. Het neemt alias, een uniek email en een name. 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--%',
    'name'  => '%--moderator-first-and-last-name--%',
  ],
] );

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 id er weer af, 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. webinarStopPresentation 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. webinarsStopVideo pauzeert het afspelen en neemt alleen alias.

webinarsFinish

Beëindigt het webinar en verbreekt de verbinding van iedereen in de ruimte. Het neemt alias en werkt alleen bij een webinar dat al begonnen is.

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 1439 uitkomen, precies één minuut minder dan 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 1080p, net als de betaalde abonnementen onder 500 deelnemers, 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.