API pública de MyOwnConference

La API de MyOwnConference le permite manejar su cuenta desde su propio código. Con ella se planifican webinars y se llevan moderadores y participantes. También se descarga el historial de asistencia y de chat. Un evento automatizado corre además entero de principio a fin. Para nada de eso hace falta abrir el panel de control.

Su clave de acceso

Cada petición se comprueba con una clave única que el sistema genera para usted. Inicie sesión en el panel de control, abra el apartado «Perfil» ("Profile") y busque el campo «Clave API» ("API Key").

¿Sospecha que la clave ha caído en otras manos? Genere una nueva. El botón de actualizar, con forma de dos flechas, está junto al campo «Clave API» ("API Key"). Púlselo y la clave vieja deja de funcionar en cuanto aparece la nueva. No entregue su clave a nadie salvo a programadores y a personas a las que ya confió el acceso a su panel de control.

Todas las peticiones a la API quedan registradas y se guardan 365 días. Si con su clave se piden datos que no pertenecen a su cuenta, la cuenta se bloquea automáticamente. En ese caso no devolvemos el dinero ni aceptamos reclamaciones, así que trate la clave como una contraseña.

Formato de la petición

Las peticiones van por HTTPS a un dominio propio, https://api.mywebinar.com. Su formato es JSON y hay que enviarlas con el método POST dentro de un único campo de datos llamado request. Cualquier otra vía devuelve un error siempre.

Todo lo que en este documento aparece como %--text--% es un marcador de posición. Sustitúyalo por su propio valor antes de enviar la petición.

La petición lleva o bien parámetros con nombre.

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

O bien una lista simple de valores.

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

key y action son obligatorios siempre. ¿El comando no toma parámetros adicionales? Entonces envíe un array vacío en params.

Formato de la respuesta

La respuesta llega siempre en JSON y, junto al resultado, repite la petición original. Tiene tres formas.

Éxito con datos devueltos.

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

Éxito sin nada que devolver.

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

Error, con la descripción de lo que salió mal.

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

Los mensajes de éxito y de error llegan en inglés, sea cual sea el idioma de su cuenta.

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

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

De aquí en adelante todos los ejemplos van en PHP.

Límites de los campos de texto

La mayoría de los comandos comparte los mismos límites, así que se recogen aquí en vez de repetirse en cada uno.

En nombres, empresas, departamentos y ciudades se admite cualquier carácter salvo ^~!@#$%^&*()+=[{}]\|:;,<>/?.

Comandos de perfil

profileGet

Devuelve el perfil entero, o solo los campos que pida.

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

Para recibirlo todo, envíe un array params vacío.

profileSet

Actualiza el perfil entero o por partes. Pase varios parámetros en un mismo array y cambiarán 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 acepta los mismos campos que profileGet.

Comandos de moderadores

Los moderadores son las personas que presentan sus webinars. El moderador creado al registrarse es el principal, y también se le llama administrador de la cuenta. En el panel de control lleva una estrella y no se puede borrar. Tiene acceso a cualquier webinar y a cualquier archivo subido.

moderatorsCreate

Crea un moderador a partir de un nombre y una dirección de correo.

$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

Borra un moderador o un array entero de ellos. Las direcciones van como lista simple.

$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 el nombre o la dirección de un moderador, y también sube una imagen que se muestra en lugar de su cámara.

Para codificar una imagen a mano, ejecute cat /path/to/file/test.png | base64.

moderatorsList

Devuelve sus moderadores. Los parámetros de abajo son todos opcionales y se combinan en una misma petición.

En la respuesta pueden venir name, email, registered, main y avatar. La fecha en que se añadió el moderador llega en registered, con precisión de segundos. El campo main vale YES en el moderador principal, y avatar vale YES cuando una imagen sustituye a la cámara.

moderatorsAddToWebinar

Ata uno o varios moderadores a un webinar. El moderador atado pasa a ser ponente de ese evento y empieza a recibir invitaciones y recordatorios.

$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 es opcional. Póngalo en YES para que la invitación salga al momento, o en NO para que salga en el horario normal.

moderatorsRemoveFromWebinar

Desata moderadores de un webinar y les quita los permisos de acceso. Dejan de recibir enlaces de invitación y pierden cualquier otra vía de entrada al evento. Los parámetros son los mismos alias y email que en el comando anterior.

moderatorsRooms

Por una dirección de correo devuelve todos los webinars a los que está atado ese moderador. Cada entrada lleva alias, name, description, start, timezone, duration y moderatorLink.

El enlace de moderador sirve para una sola persona. Los moderadores que reparten su enlace vuelven con una de tres quejas. Los echan de la sala, no consiguen entrar, o dentro ya hay alguien con su nombre. Las tres tienen la misma causa. Una segunda entrada por ese enlace siempre corta la primera sesión. Nadie debería abrir una sala con un enlace que no se le entregó.

Comandos de participantes

attendeesCreate

Crea un participante a partir de una dirección de correo y un nombre.

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

En las direcciones de los participantes se admiten letras inglesas y dígitos.

attendeesSet

Actualiza un participante ya creado. Reconózcalo por email y envíe después los campos que quiera cambiar.

Su cuenta puede tener más campos además de los de esta lista.

attendeesDelete

Borra un participante o un array de ellos, y se dirige a cada uno por su dirección de correo.

attendeesList

Devuelve los participantes que creó antes, con filtros, orden y paginación.

En fields puede pedir name, email, phone, company, department, city, born, creation_date, country y type. Están además notified (cuántas invitaciones han salido) y link (el enlace de entrada del participante, disponible solo junto con alias).

attendeesAddToWebinar y attendeesRemoveFromWebinar

Atan participantes a un webinar programado, o los quitan de él. Los dos toman alias y un array attendees con direcciones de correo.

$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

Por la dirección de un participante devuelve todos los webinars a los que se le invitó. Cada entrada lleva alias, name, description, start, timezone, duration y attendeeLink.

Grupos de participantes

attendeesUnbanned

Levanta el bloqueo de un participante al que banearon en una sala de webinar. En email pase una dirección o un array de ellas.

Comandos de webinars

Casi todo lo de abajo se dirige por alias, el identificador único del webinar. Lo devuelve webinarsCreate, y es también el código que se ve en el enlace del webinar.

webinarsCreate

Programa un webinar y devuelve los enlaces que necesita.

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

En la respuesta llega alias, y con él webinarLink para la página pública y mainModeratorLink para el moderador principal.

start se escribe en formato YYYY-MM-DD HH:MM:SS y se lee en la zona horaria de su perfil. duration se cuenta en minutos y no puede pasar de 1439, que es justo un minuto menos que un día entero.

webinarsSet

Cambia cualquier ajuste de un webinar que programó 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--%',
    ],
  ],
] );

Estos son los parámetros de primer nivel.

Y estos son los ajustes de la sala.

El modo de grabación se fija poniendo el nombre del modo como clave con valor vacío, por ejemplo recordWebCams => "".

Otros tres interruptores deciden qué acaba en el archivo. recordUsers mete la lista de participantes en la grabación, recordModer imprime el nombre de cada moderador sobre su cámara y recordChat añade el chat. Basta con poner recordUsers o recordModer para que el modo cambie solo a recordWhole.

recordQuality fija la resolución. 0 graba en 480p (800x460), 1 en 720p (1280x720), 2 en 1080p (1920x1080), 3 en 2K (2048x1080) y 4 en 2160p. Qué nivel puede usar de verdad su cuenta lo decide el plan, no la API. El Starter gratuito graba hasta 1080p, igual que los planes de pago por debajo de 500 participantes, mientras que los planes desde 500 participantes llegan a 2160p. Lo que incluye cada plan lo detalla la página de precios.

webinarsDelete

Borra por completo un webinar programado, y se dirige a él por alias.

webinarsClone

Copia un webinar a una date nueva en formato YYYY-MM-DD, y devuelve los nuevos alias, webinarLink y mainModeratorLink.

webinarsList

Devuelve sus webinars.

Cada entrada puede llevar name, description, created (la hora de creación en GMT+0), alias, start y language.

webinarsGetInfo

Devuelve todo lo que el sistema sabe de un webinar, incluidos su bloque settings, su status y records, el número de grabaciones hechas hasta ahora. El volumen y la forma de los datos cambian de una cuenta a otra, así que no fije la lista de campos en el código.

webinarsGetLettersInfo y webinarsSetLetters

webinarsGetLettersInfo devuelve los correos de invitación configurados para un webinar, cada uno con enabled, status y text.

webinarsSetLetters los cambia. Toma alias, un type, un indicador enabled con valor YES o NO y text, una firma en HTML que se añade al mensaje. Envíe text vacío y la firma desaparece.

El mensaje 1HOUR no se puede apagar.

webinarsLettersOff y webinarsLettersOn

Paran o vuelven a poner en marcha todos los correos de invitación de un webinar, y se dirigen a él por alias.

webinarsOnlineList

Devuelve quién está en la sala ahora mismo, repartido en moderators y guests.

webinarsRecordsList y webinarsRecordDelete

webinarsRecordsList devuelve las grabaciones de un webinar. Cada una lleva id, name, status (en proceso o lista para descargar), added, size en bytes, duration en segundos, link para verla y download_link para descargarla.

webinarsRecordDelete quita una grabación por el id que sacó de esa lista.

webinarsFilesList

Devuelve los materiales subidos a un webinar. type es opcional. PRESENTATION devuelve presentaciones e imágenes, y MEDIA devuelve archivos mp3 y mp4 junto con vídeos de YouTube y Vimeo. Cada archivo lleva id, name, added, size, duration (segundos en los medios, o el número de diapositivas en una presentación), link y download_link.

webinarsHistory

Devuelve el registro de un webinar. Ponga type en chats para recibir todos los mensajes del chat de texto, o en visits para el historial de asistencia. En cada fila están la marca de tiempo, el nombre del participante y el texto del mensaje. Van también una marca g o m para invitado o moderador, y la dirección del participante.

Comandos de automatización

Estos comandos son la maquinaria de los webinars automatizados. Llenan la sala de moderadores y participantes virtuales, y escriben en el chat en su nombre. Llevan las diapositivas y el vídeo, y terminan el evento cuando usted ha acabado. Todo va con su horario, no con el de un ponente.

webinarsAddModerToRoom y webinarsRemoveModerFromRoom

webinarsAddModerToRoom sienta en la sala a un moderador virtual. Toma alias, un email único y un name. webinarsRemoveModerFromRoom saca de nuevo a ese moderador, y se dirige a él por alias y 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 y webinarsGetBotsList

webinarsAddBotToRoom sienta en la sala a un participante virtual. Toma alias, name y country, un código de país de dos letras como US, DE, FR, PL o UA. En la respuesta llega el id que le hará falta después.

webinarsRemoveBotFromRoom retira de nuevo ese id, y webinarsGetBotsList devuelve todos los participantes virtuales conectados ahora mismo a un webinar.

webinarsBotMessage

Envía un mensaje al chat en nombre de un moderador virtual o de un participante virtual.

Control del chat

webinarsLockChat impide a los participantes reales escribir en el chat y webinarsUnlockChat se lo permite de nuevo. Los moderadores y los ponentes escriben siempre, así que cerrar el chat solo afecta a los participantes.

webinarsLinkLockInChat y webinarsLinkUnlockInChat hacen lo propio con los enlaces, bloqueándolos o permitiéndolos entre los participantes reales. Los cuatro toman solo alias.

Diapositivas y vídeo

webinarsStartPresentation enseña una diapositiva a los participantes reales. Toma alias, el id de la presentación que da webinarsFilesList, y slide, el número de página que mostrar. webinarStopPresentation quita la presentación de la pantalla con solo alias.

webinarsStartVideo reproduce un archivo de vídeo, un clip de YouTube o uno de Vimeo, y toma alias y el id del archivo que da webinarsFilesList. webinarsStopVideo pone la reproducción en pausa y toma solo alias.

webinarsFinish

Termina el webinar y desconecta a todos los que están en la sala. Toma alias y funciona solo con un webinar que ya haya empezado.

Si algo aquí no cuadra

¿Ha visto en este documento un error o una imprecisión? Díganoslo por el chat en línea. Lo comprobamos y corregimos la página.

MyOwnConference puede cambiar o ampliar este documento en cualquier momento. Al trabajar con él, usted lo acepta.

Preguntas frecuentes

¿Qué hago si mi clave API se filtra?

Genere otra al momento con el botón de actualizar, con forma de dos flechas, que está junto al campo «Clave API» ("API Key") en el apartado «Perfil» ("Profile"). La clave vieja deja de funcionar en cuanto aparece la nueva. Todas las peticiones a la API quedan registradas y se guardan 365 días. Si con su clave se piden datos que no pertenecen a su cuenta, la cuenta se bloquea automáticamente, y entonces no devolvemos el dinero ni aceptamos reclamaciones.

Cada petición que envío vuelve como error. ¿Qué hago mal?

Compruebe primero cómo la envía, y solo después el comando. Las peticiones van por HTTPS a https://api.mywebinar.com con el método POST, y el JSON va dentro de un único campo de datos llamado request. Cualquier otra vía devuelve un error siempre. key y action son obligatorios siempre, y cuando el comando no toma parámetros adicionales, params va igualmente como array vacío.

¿Puedo programar un webinar más largo que un día?

No, duration se cuenta en minutos y no puede pasar de 1439, que es justo un minuto menos que un día entero. Compruebe de paso la zona horaria de su perfil, porque start se escribe en formato YYYY-MM-DD HH:MM:SS y se lee con ese ajuste. profileGet la devuelve como timezone, en forma de desfase respecto a GMT en minutos, así que GMT+02:00 llega como 120.

¿Puedo pedir una grabación en 2160p en cualquier plan?

No, qué nivel puede usar de verdad su cuenta lo decide el plan, no la API. El Starter gratuito graba hasta 1080p, igual que los planes de pago por debajo de 500 participantes, mientras que los planes desde 500 participantes llegan a 2160p. El propio recordQuality acepta 0 para 480p, 1 para 720p, 2 para 1080p, 3 para 2K y 4 para 2160p. Lo que incluye cada plan lo detalla la página de precios.

A mis ponentes los echa de la sala una y otra vez. ¿Por qué pasa?

El enlace de moderador sirve para una sola persona, así que una segunda entrada por ese enlace siempre corta la primera sesión. Esa única causa está detrás de las tres quejas habituales. Al ponente lo echan de la sala, no le dejan entrar, o dentro ya hay alguien con su nombre. Dé a cada ponente el enlace que se le entregó a él, y que moderatorsRooms devuelve como moderatorLink para cada webinar al que está atado.