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 los nombres se admite cualquier carácter salvo la comilla invertida y ^~!@#$%^&*()+=[{}]\|:;,<>/?. Su propio nombre, los nombres de grupo y los de los participantes virtuales tampoco pueden llevar punto. En empresas, departamentos y ciudades se admite cualquier carácter.

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 salvo email, que no se puede cambiar por la API. Además toma password, de 6 a 64 caracteres.

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. A diferencia del panel de control, la API no protege aquí al moderador principal, así que deje su dirección fuera de la lista.

$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 en curso o próximos 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.

También se aceptan skype y position.

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, skype, company, department, city, born, creation_date, country y type. Si además pasa alias, puede añadir notified (cuántas invitaciones han salido) y link (el enlace de entrada del participante).

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. Solo se atan participantes que ya están en su lista y pueden recibir correos, y las demás direcciones se saltan sin error, así que cree antes los participantes nuevos 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

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.

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 1440, que es justo un día.

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 pasar cualquiera de los tres, incluso con NO, 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 720p, los planes de pago por debajo de 500 participantes hasta 1080p, y 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. La respuesta lleva alias, name, description, start, duration, close, language, google_id, yandex_id, created, status, records (el número de grabaciones hechas hasta ahora) y un bloque settings con los interruptores de la sala, el tema de color, los campos de la página de entrada y el grupo.

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 de hasta 2000 caracteres 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, o las de toda la cuenta si omite alias. Cada una lleva id, name, status (recording mientras el webinar se sigue grabando, process mientras se prepara el archivo y ready cuando ya se puede 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 archivos de su almacenamiento, o solo los de un webinar si pasa su alias. Pase también type, porque sin él la lista llega vacía. PRESENTATION devuelve presentaciones e imágenes, y MEDIA devuelve archivos de vídeo y audio (.mp4, .mov, .webm, .mkv y .mp3) 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. Una fila del chat lleva la hora, el nombre, el texto del mensaje, una marca G o M para invitado o moderador y el correo del invitado. Una entrada de asistencia lleva el nombre, la misma marca G o M, el país, el correo, la dirección IP, la hora de la primera entrada y la de la última salida, y uptime, la parte del webinar que la persona pasó en la sala, en porcentaje. En una sala permanente pase además date en formato YYYY-MM-DD.

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. Los bloqueos del chat, las diapositivas, el vídeo y webinarsFinish actúan a través de un moderador virtual, así que primero siente uno en la sala con webinarsAddModerToRoom. Sin él devuelven un error.

webinarsAddModerToRoom y webinarsRemoveModerFromRoom

webinarsAddModerToRoom sienta en la sala a un moderador virtual. Toma alias y el email de un moderador que haya creado con moderatorsCreate, y la sala muestra el nombre de ese moderador. 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--%',
  ],
] );

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 saca de nuevo a ese participante, y se dirige a él por alias e 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. webinarsStopPresentation 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. También reproduce una grabación por su id de webinarsRecordsList. webinarsStopVideo detiene la reproducción y toma solo alias.

webinarsFinish

Termina el webinar y desconecta a todos los que están en la sala. Toma alias y, igual que los comandos del chat, las diapositivas y el vídeo, necesita un moderador virtual en la sala.

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 1440, que es justo un día. 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 720p, los planes de pago por debajo de 500 participantes hasta 1080p, y 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.