API publique de MyOwnConference

L'API MyOwnConference vous laisse piloter votre compte depuis votre propre code. Vous y programmez des webinaires, gérez modérateurs et participants, récupérez l'historique de présence et du chat, et menez un événement entièrement automatisé du début à la fin. Rien de tout cela ne demande d'ouvrir le panneau de contrôle.

Votre clé d'accès

Chaque requête passe par une clé unique que le système génère pour vous. Connectez-vous au panneau de contrôle, ouvrez la section «Profil» ("Profile") et cherchez le champ «Clé API» ("API Key").

Vous soupçonnez que quelqu'un d'autre détient votre clé ? Générez-en une nouvelle. Le bouton de rafraîchissement, en forme de deux flèches, se tient à côté du champ «Clé API» ("API Key"). Cliquez dessus et l'ancienne clé cesse de marcher à la seconde où la nouvelle apparaît. Ne confiez votre clé à personne d'autre que vos programmeurs et ceux à qui vous avez déjà ouvert votre panneau de contrôle.

Nous journalisons toutes les requêtes à l'API et les gardons 365 jours. Si votre clé sert à atteindre des données qui n'appartiennent pas à votre compte, le compte se bloque automatiquement. Nous ne remboursons rien dans ce cas et nous n'acceptons aucune réclamation, alors traitez la clé comme un mot de passe.

Format des requêtes

Les requêtes passent en HTTPS par un domaine dédié, https://api.mywebinar.com. Elles sont en JSON, et vous les envoyez par la méthode POST dans un seul champ de données nommé request. Toute autre approche renvoie une erreur à chaque fois.

Dans tout ce document, ce qui s'écrit %--text--% est un espace réservé. Remplacez-le par votre propre valeur avant d'envoyer la requête.

Une requête porte des paramètres nommés.

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

Ou bien une simple liste de valeurs.

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

key et action sont toujours obligatoires. La commande ne prend aucun paramètre supplémentaire ? Envoyez alors un tableau vide pour params.

Format des réponses

Les réponses arrivent toujours en JSON, et chacune renvoie la requête d'origine à côté du résultat. Elles prennent l'une des trois formes qui suivent.

Une réussite avec des données.

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

Une réussite sans rien à renvoyer.

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

Une erreur, avec la description de ce qui a échoué.

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

Les messages de réussite et d'erreur reviennent en anglais, quelle que soit la langue de votre compte.

Exemple en 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 );

Exemple en 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();

Les exemples qui suivent sont tous en PHP.

Limites des champs texte

La plupart des commandes partagent les mêmes limites. Les voici rassemblées ici, plutôt que répétées à chaque commande.

Les noms, les entreprises, les services et les villes acceptent n'importe quel caractère, sauf ^~!@#$%^&*()+=[{}]\|:;,<>/?.

Commandes de profil

profileGet

Renvoie le profil entier, ou seulement les champs que vous demandez.

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

Pour tout recevoir, envoyez un tableau params vide.

profileSet

Met à jour le profil en entier ou par morceaux. Passez plusieurs paramètres dans un même tableau et ils changent ensemble.

$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 accepte les mêmes champs que profileGet.

Commandes de modérateur

Les modérateurs sont les personnes qui animent vos webinaires. Celui que votre inscription a créé est le modérateur principal, que l'on appelle aussi l'administrateur du compte. Le panneau de contrôle le marque d'une étoile et interdit de le supprimer. Il atteint tous les webinaires et tous les fichiers chargés.

moderatorsCreate

Crée un modérateur à partir d'un nom et d'une adresse e-mail.

$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

Supprime un modérateur ou tout un tableau. Les adresses se passent en simple liste.

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

moderatorsSet

Change le nom ou l'adresse d'un modérateur, ou charge une image à montrer à la place de sa webcam.

Pour encoder une image à la main, lancez cat /path/to/file/test.png | base64.

moderatorsList

Renvoie vos modérateurs. Les paramètres ci-dessous sont tous facultatifs et se combinent dans une même requête.

La réponse peut porter name, email et registered, la date d'ajout du modérateur à la seconde près. S'y ajoutent main, qui vaut YES chez le modérateur principal, et avatar, qui vaut YES quand une image remplace la caméra.

moderatorsAddToWebinar

Rattache un ou plusieurs modérateurs à un webinaire. Le modérateur rattaché devient présentateur de cet événement et commence à recevoir invitations et rappels.

$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 est facultatif. Mettez-le à YES pour envoyer l'invitation tout de suite, ou à NO pour la laisser partir selon le calendrier habituel.

moderatorsRemoveFromWebinar

Détache les modérateurs d'un webinaire et leur retire les droits d'accès. Les liens d'invitation ne leur arrivent plus, et aucun autre chemin vers l'événement ne leur reste. Les paramètres sont les mêmes alias et email que pour la commande précédente.

moderatorsRooms

Renvoie tous les webinaires auxquels un modérateur est rattaché, à partir de son adresse e-mail. Chaque entrée porte alias, name, description, start, timezone, duration et moderatorLink.

Un lien de modérateur ne vaut que pour une personne. Les modérateurs qui font circuler le leur reviennent avec l'une des trois plaintes suivantes. On les éjecte de la salle, ils n'arrivent pas à entrer, ou quelqu'un est déjà là sous leur nom. Les trois ont la même cause. Une seconde entrée sur le même lien coupe toujours la première session. Personne ne devrait donc ouvrir une salle avec un lien qui ne lui revient pas.

Commandes de participant

attendeesCreate

Crée un participant à partir d'une adresse e-mail et d'un nom.

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

Les adresses des participants acceptent les lettres anglaises et les chiffres.

attendeesSet

Met à jour un participant existant. Reconnaissez-le par email, puis envoyez les champs que vous voulez changer.

Votre compte peut porter d'autres champs au-delà de cette liste.

attendeesDelete

Supprime un participant ou un tableau de participants, désignés par leur adresse e-mail.

attendeesList

Renvoie les participants créés plus tôt, avec filtres, tri et pagination.

Dans fields, vous pouvez demander name, email, phone, company, department, city, born, creation_date, country et type. Viennent en plus notified, le nombre d'invitations parties, et link, le lien d'entrée du participant, qui n'arrive qu'avec alias.

attendeesAddToWebinar et attendeesRemoveFromWebinar

Rattachent des participants à un webinaire programmé, ou les en retirent. Les deux prennent alias et un tableau attendees d'adresses e-mail.

$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

Renvoie tous les webinaires auxquels un participant a été invité, à partir de son adresse. Chaque entrée porte alias, name, description, start, timezone, duration et attendeeLink.

Groupes de participants

attendeesUnbanned

Lève le blocage d'un participant banni d'une salle de webinaire. Dans email, passez une adresse ou un tableau d'adresses.

Commandes de webinaire

Presque tout ce qui suit se désigne par alias, l'identifiant unique du webinaire. webinarsCreate le renvoie, et c'est aussi le code visible dans le lien du webinaire.

webinarsCreate

Programme un webinaire et renvoie les liens dont vous avez besoin.

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

La réponse renvoie alias, puis webinarLink pour la page publique et mainModeratorLink pour le modérateur principal.

start s'écrit au format YYYY-MM-DD HH:MM:SS et se lit dans le fuseau horaire de votre profil. duration se compte en minutes et ne peut pas dépasser 1439, soit une minute de moins qu'une journée entière.

webinarsSet

Change n'importe quel réglage d'un webinaire programmé plus tôt.

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

Voici les paramètres de premier niveau.

Et voici les réglages de la salle.

Le mode d'enregistrement se règle en passant son nom en clé, avec une valeur vide, par exemple recordWebCams => "".

Trois autres interrupteurs changent ce qui finit dans le fichier. recordUsers met la liste des participants dans l'enregistrement, recordModer imprime le nom de chaque modérateur sur sa caméra, et recordChat ajoute le chat. Activez recordUsers ou recordModer et le mode bascule tout seul sur recordWhole.

recordQuality fixe la définition. 0 enregistre en 480p (800x460), 1 en 720p (1280x720), 2 en 1080p (1920x1080), 3 en 2K (2048x1080) et 4 en 2160p. Le niveau réellement ouvert à votre compte tient au forfait, pas à l'API. Le Starter gratuit enregistre jusqu'en 1080p, tout comme les forfaits payants sous 500 participants, et les forfaits à partir de 500 participants montent à 2160p. La page des tarifs détaille ce que chaque forfait comprend.

webinarsDelete

Supprime complètement un webinaire programmé, désigné par alias.

webinarsClone

Copie un webinaire à une nouvelle date au format YYYY-MM-DD, et renvoie les nouveaux alias, webinarLink et mainModeratorLink.

webinarsList

Renvoie vos webinaires.

Chaque entrée peut porter name, description, created, l'heure de création en GMT+0, puis alias, start et language.

webinarsGetInfo

Renvoie tout ce que le système sait d'un webinaire, dont son bloc settings, son status et records, le nombre d'enregistrements déjà faits. Le volume et la forme des données changent d'un compte à l'autre, ne figez donc pas la liste des champs dans votre code.

webinarsGetLettersInfo et webinarsSetLetters

webinarsGetLettersInfo renvoie les e-mails d'invitation réglés pour un webinaire, chacun avec enabled, status et text.

webinarsSetLetters les change. Elle prend alias, un type, un drapeau enabled valant YES ou NO, et text, une signature HTML ajoutée au message. Envoyez text vide et la signature disparaît.

Le message 1HOUR ne se désactive pas.

webinarsLettersOff et webinarsLettersOn

Arrêtent ou relancent tous les e-mails d'invitation d'un webinaire, désigné par alias.

webinarsOnlineList

Renvoie qui se trouve dans la salle en ce moment, réparti entre moderators et guests.

webinarsRecordsList et webinarsRecordDelete

webinarsRecordsList renvoie les enregistrements d'un webinaire. Chacun porte id, name, status (traitement en cours ou prêt au téléchargement), added, size en octets et duration en secondes. Viennent ensuite link pour regarder et download_link pour télécharger.

webinarsRecordDelete retire un enregistrement par l'id obtenu dans cette liste.

webinarsFilesList

Renvoie les supports chargés dans un webinaire. type est facultatif. PRESENTATION renvoie les présentations et les images, et MEDIA renvoie les fichiers mp3 et mp4 avec les vidéos YouTube et Vimeo. Chaque fichier porte id, name, added, size, duration (des secondes pour un média, ou le nombre de diapositives pour une présentation), link et download_link.

webinarsHistory

Renvoie le journal d'un webinaire. Mettez type à chats pour tous les messages du chat texte, ou à visits pour l'historique de présence. Chaque ligne porte l'horodatage, le nom du participant, le texte du message, une marque g ou m pour invité ou modérateur, et l'adresse du participant.

Commandes d'automatisation

Ces commandes sont la mécanique des webinaires automatisés. Elles peuplent une salle de modérateurs et de participants virtuels, écrivent dans le chat sous leurs noms, mènent les diapositives et la vidéo. Et quand vous avez fini, elles terminent l'événement. Tout suit votre minutage, pas celui d'un présentateur.

webinarsAddModerToRoom et webinarsRemoveModerFromRoom

webinarsAddModerToRoom installe un modérateur virtuel dans une salle. Elle prend alias, un email unique et un name. webinarsRemoveModerFromRoom le fait ressortir, en le désignant par alias et 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 et webinarsGetBotsList

webinarsAddBotToRoom installe un participant virtuel dans la salle. Elle prend alias, name et country, un code pays sur deux lettres comme US, DE, FR, PL ou UA. La réponse renvoie l'id dont vous aurez besoin ensuite.

webinarsRemoveBotFromRoom retire cet id, et webinarsGetBotsList renvoie tous les participants virtuels connectés à un webinaire en ce moment.

webinarsBotMessage

Envoie un message dans le chat au nom d'un modérateur virtuel ou d'un participant virtuel.

Gestion du chat

webinarsLockChat empêche les participants réels d'écrire dans le chat, et webinarsUnlockChat les laisse écrire de nouveau. Les modérateurs et les présentateurs publient toujours, donc le verrou ne touche que les participants.

webinarsLinkLockInChat et webinarsLinkUnlockInChat font la même chose avec les liens, qu'elles bloquent ou autorisent entre participants réels. Les quatre ne prennent que alias.

Diapositives et vidéo

webinarsStartPresentation montre une diapositive aux participants réels. Elle prend alias, l'id de la présentation venu de webinarsFilesList, et slide, le numéro de page à afficher. webinarStopPresentation retire la présentation de l'écran avec le seul alias.

webinarsStartVideo joue un fichier vidéo, un clip YouTube ou un clip Vimeo, en prenant alias et l'id du fichier venu de webinarsFilesList. webinarsStopVideo met la lecture en pause et ne prend que alias.

webinarsFinish

Termine le webinaire et déconnecte tout le monde dans la salle. Elle prend alias et ne marche que sur un webinaire déjà commencé.

Si quelque chose ici cloche

Vous repérez une erreur ou une imprécision dans ce document ? Dites-le-nous dans le chat en ligne. Nous vérifierons et corrigerons la page.

MyOwnConference peut modifier ou compléter ce document à tout moment. En travaillant avec lui, vous l'acceptez.

Questions fréquentes

Que faire si ma clé API a fuité ?

Générez-en une nouvelle tout de suite, avec le bouton de rafraîchissement en forme de deux flèches, à côté du champ «Clé API» ("API Key") de la section «Profil» ("Profile"). L'ancienne clé cesse de marcher à la seconde où la nouvelle apparaît. Nous journalisons toutes les requêtes à l'API et les gardons 365 jours. Si votre clé sert à atteindre des données qui n'appartiennent pas à votre compte, le compte se bloque automatiquement. Nous ne remboursons rien dans ce cas et nous n'acceptons aucune réclamation.

Chacune de mes requêtes revient en erreur. Qu'est-ce que je fais mal ?

Vérifiez d'abord la façon d'envoyer, pas la commande. Les requêtes passent en HTTPS vers https://api.mywebinar.com par la méthode POST, et le JSON tient dans un seul champ de données nommé request. Toute autre approche renvoie une erreur à chaque fois. key et action sont toujours obligatoires, et quand une commande ne prend aucun paramètre supplémentaire, un tableau vide part quand même pour params.

Puis-je programmer un webinaire plus long qu'une journée ?

Non, duration se compte en minutes et ne peut pas dépasser 1439, soit une minute de moins qu'une journée entière. Vérifiez au passage le fuseau horaire de votre profil, car start s'écrit au format YYYY-MM-DD HH:MM:SS et se lit sur ce réglage. profileGet le renvoie comme timezone, sous forme de décalage par rapport à GMT en minutes, donc GMT+02:00 revient en 120.

Puis-je demander un enregistrement en 2160p sur n'importe quel forfait ?

Non, le niveau réellement ouvert à votre compte tient au forfait, pas à l'API. Le Starter gratuit enregistre jusqu'en 1080p, tout comme les forfaits payants sous 500 participants, et les forfaits à partir de 500 participants montent à 2160p. recordQuality prend lui-même 0 pour 480p, 1 pour 720p, 2 pour 1080p, 3 pour 2K et 4 pour 2160p. La page des tarifs détaille ce que chaque forfait comprend.

Mes présentateurs se font sans cesse éjecter de la salle. D'où cela vient-il ?

Un lien de modérateur ne vaut que pour une personne, donc une seconde entrée sur le même lien coupe toujours la première session. Cette seule cause explique les trois plaintes habituelles. On vous éjecte, on ne vous laisse pas entrer, ou quelqu'un est déjà là sous votre nom. Donnez à chaque présentateur le lien délivré à son nom, celui que moderatorsRooms renvoie en moderatorLink pour chaque webinaire auquel il est rattaché.