Documentación de la API de usuario de Loomio

/api/user0 es la API orientada a usuarios para integraciones con Loomio. Utiliza la clave de API de una cuenta de usuario y cada acción se realiza como ese usuario.

Las operaciones de grupo utilizan las membresías y los permisos de grupo del usuario de la clave de API. Ser administrador de la instancia no amplía el acceso de una clave de API a grupos o contenido; usa la API de servidor para administrar la instancia.

Usa la clave de API de la cuenta de usuario de Loomio que realizará las acciones. Una cuenta dedicada para un bot resulta útil cuando una integración no debe recibir invitaciones a encuestas ni notificaciones.

Los usuarios que han iniciado sesión pueden encontrar la clave de API y los ID de grupo en la página de acceso a la API.

Envía la clave de API en una cabecera Authorization: Bearer. Las claves de API en cadenas de consulta se rechazan porque los proxies y los registros de acceso pueden guardar las URL.

Authorization: Bearer YOUR_API_KEY

Los ejemplos utilizan YOUR_API_KEY, el ID de grupo 123 y https://www.loomio.com/. Sustitúyelos por tu clave de API, el ID de tu grupo y la URL de tu instalación de Loomio.

Enviar cuerpos de solicitud

Envía JSON con Content-Type: application/json. Los ejemplos de cURL utilizan --json, que establece esta cabecera automáticamente. Los endpoints de creación y edición de discusiones, comentarios y encuestas aceptan tanto un objeto plano como un objeto anidado bajo el nombre del recurso, como {"poll": {...}}.

Envía los arrays como arrays JSON, por ejemplo, "options": ["foo", "bar"]. Si utilizas codificación de formulario, los arrays necesitan nombres de campo con corchetes, como options[]=foo&options[]=bar; repetir options=foo&options=bar conserva solo el último valor.

Comprueba el estado HTTP y el cuerpo de la respuesta después de cada solicitud. Un fallo de validación devuelve 422 con un objeto errors; la creación correcta de una encuesta devuelve la encuesta en polls y las opciones en poll_options.

Resumen de endpoints

Método Endpoint Finalidad
POST /api/user0/comments Crear un comentario o una respuesta
PATCH /api/user0/comments/:id Editar un comentario
DELETE /api/user0/comments/:id Eliminar un comentario conservando el registro
POST /api/user0/discussions Crear una discusión
GET /api/user0/discussions/:id Obtener una discusión
GET /api/user0/discussions Listar las discusiones de un grupo
PATCH /api/user0/discussions/:id Editar una discusión
DELETE /api/user0/discussions/:id Eliminar una discusión conservando el registro
GET /api/user0/groups Listar los grupos del usuario de la clave de API
GET /api/user0/groups/:id_or_key_or_handle Obtener un grupo visible
GET /api/user0/memberships Listar las membresías de un grupo
POST /api/user0/memberships Añadir miembros y, opcionalmente, eliminar los miembros ausentes de la lista
GET /api/user0/reports Generar un informe de participación
POST /api/user0/polls Crear una encuesta
GET /api/user0/polls/:id Obtener una encuesta
GET /api/user0/polls Listar las encuestas de un grupo
PATCH /api/user0/polls/:id Editar una encuesta
DELETE /api/user0/polls/:id Eliminar una encuesta conservando el registro
GET /api/user0/search Buscar discusiones, comentarios, encuestas, votos y conclusiones visibles
GET /api/user0/threads Listar los hilos visibles de discusión y de encuestas independientes
GET /api/user0/threads/:topic_id Obtener un hilo
GET /api/user0/threads/:topic_id/items Obtener los elementos ordenados de un hilo
GET /api/user0/threads/:topic_id/markdown Obtener un hilo completo en Markdown
GET /api/user0/chatbots Listar las integraciones de chat y los webhooks de un grupo
POST /api/user0/chatbots Crear una integración de chat o un webhook
PATCH /api/user0/chatbots/:id Actualizar una integración de chat o un webhook
DELETE /api/user0/chatbots/:id Eliminar una integración de chat o un webhook
POST /api/user0/chatbots/check Enviar una prueba de conexión de un webhook

Paginación

Las discusiones, los grupos, las membresías, las encuestas, los hilos, los elementos de los hilos y los webhooks aceptan limit (valor predeterminado: 50) y offset (valor predeterminado: 0). Los grupos, los elementos de los hilos y los webhooks limitan limit a 500.

Incrementa offset en el número de registros principales devueltos para obtener la página siguiente. meta.total es el número total de coincidencias; los registros relacionados no cuentan para el tamaño de la página.

Los informes de participación devuelven todos los datos solicitados y la búsqueda devuelve hasta 20 resultados. Ninguno admite paginación.

Las discusiones, las encuestas y las membresías también aceptan los alias heredados per para limit y from para offset. Usa limit y offset para las nuevas integraciones.

Las respuestas de la API de usuario utilizan un formato compuesto: los registros principales van acompañados de registros relacionados, como temas, grupos, usuarios, encuestas y reacciones. Esto permite que un cliente complete un almacén local de registros con una sola solicitud, pero puede incluir más datos de los que necesita una integración sencilla.

Pasa compact=1 para omitir los registros relacionados voluminosos de temas, grupos, grupos principales, membresías, reacciones, etiquetas y traducciones. Los registros principales y los registros relacionados necesarios para interpretar el contenido siguen presentes.

curl 'https://www.loomio.com/api/user0/threads/123/items?compact=1' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Para tener un control directo, pasa exclude_types con los tipos de registro en singular separados por espacios. Por ejemplo, exclude_types=group reaction omite los grupos y las reacciones relacionados. Los valores habituales son topic, group, parent, membership, reaction, tag, translation, user, discussion, poll, poll_option, stance, stance_choice, outcome y topic_item. Las exclusiones se aplican a los registros relacionados, no al recurso principal solicitado al endpoint.

Las respuestas de colecciones incluyen meta.total cuando se define un tamaño exacto de la colección. El total se calcula antes de aplicar limit y offset. Los endpoints, como el de búsqueda, que devuelven intencionadamente un conjunto limitado de resultados omiten meta.total en lugar de devolver null.

Comentarios

Crear un comentario

Crea un comentario en una discusión como el usuario de la clave de API.

POST /api/user0/comments

Parámetros

Nombre Descripción
discussion_id Entero, obligatorio. ID de la discusión en la que comentar
body Cuerpo del comentario, obligatorio salvo que se proporcione un archivo adjunto
body_format md o html, opcional, valor predeterminado: md

Ejemplo

curl https://www.loomio.com/api/user0/comments \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "discussion_id": 123,
    "body": "example comment",
    "body_format": "md"
  }'

Editar un comentario

Edita un comentario como el usuario de la clave de API. Se aplican los mismos permisos que en Loomio: el usuario debe tener permiso para editar ese comentario.

PATCH /api/user0/comments/:id

Parámetros

Nombre Descripción
body Cuerpo actualizado del comentario
body_format md o html, opcional, valor predeterminado: md

Ejemplo

curl https://www.loomio.com/api/user0/comments/123 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "body": "updated comment",
    "body_format": "md"
  }'

Eliminar un comentario de forma lógica

Elimina un comentario de forma lógica como el usuario de la clave de API. Esto descarta el comentario, oculta el cuerpo del comentario y conserva el registro del comentario.

DELETE /api/user0/comments/:id

Ejemplo

curl https://www.loomio.com/api/user0/comments/123 \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_API_KEY'

Discusiones

Crear una discusión

Crea una discusión como el usuario de la clave de API.

POST /api/user0/discussions

Parámetros

Nombre Descripción
group_id Grupo en el que estará el hilo
title Título del hilo, obligatorio
description Contexto del hilo, opcional
description_format md o html, opcional, por defecto md
recipient_audience group o null. Si es group, se notificará a todo el grupo sobre el nuevo hilo
recipient_user_ids Array de ID de usuarios a los que notificar o invitar al hilo
recipient_emails Array de direcciones de correo electrónico de las personas a las que invitar al hilo
recipient_message Mensaje que se incluye en la invitación por correo electrónico

Ejemplo

curl https://www.loomio.com/api/user0/discussions \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "title": "example thread",
    "recipient_emails": [
      "person@example.com"
    ]
  }'

Mostrar una discusión

Obtén una discusión usando el ID de la discusión, un número entero, o la clave, una cadena de texto.

GET /api/user0/discussions/:id

Ejemplo

curl https://www.loomio.com/api/user0/discussions/abc123 \
  -H 'Authorization: Bearer YOUR_API_KEY'

Listar discusiones

Lista las discusiones de un grupo visibles para el usuario de la clave API. En un grupo visible públicamente, una persona que no sea miembro puede listar las discusiones públicas del grupo; las discusiones privadas siguen restringidas a los usuarios que pueden leerlas en Loomio.

GET /api/user0/discussions

Parámetros

Nombre Descripción
group_id Número entero, obligatorio. ID del grupo cuyas discusiones se van a listar
status Cadena de texto, opcional, valor predeterminado open. Valores: open, closed, all
limit Número entero, opcional, valor predeterminado 50. Tamaño de página
offset Número entero, opcional, valor predeterminado 0. Desplazamiento para la paginación

Compatibilidad con versiones anteriores: per y from se aceptan como alias de limit y offset y seguirán funcionando.

Ejemplo

curl 'https://www.loomio.com/api/user0/discussions?group_id=123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Editar una discusión

Edita una discusión como el usuario de la clave API. Se aplican los mismos permisos que en Loomio: el usuario debe tener permiso para editar esa discusión.

PATCH /api/user0/discussions/:id

Parámetros

Nombre Descripción
title Título actualizado
description Contexto actualizado
description_format md o html, opcional, valor predeterminado md
recipient_audience group o null. Si es group, se notificará a todo el grupo sobre la edición
recipient_user_ids Lista de IDs de usuarios a los que notificar o invitar al hilo
recipient_emails Lista de direcciones de correo electrónico de las personas a las que invitar al hilo
recipient_message Mensaje que se incluirá en la invitación por correo electrónico

Ejemplo

curl https://www.loomio.com/api/user0/discussions/123 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "title": "updated thread title",
    "description": "updated context",
    "description_format": "md"
  }'

Eliminar una discusión de forma lógica

Elimina una discusión de forma lógica como el usuario de la clave de API. Esto descarta la discusión y conserva el registro de la discusión.

DELETE /api/user0/discussions/:id

Ejemplo

curl https://www.loomio.com/api/user0/discussions/123 \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_API_KEY'

Grupos

Listar grupos

Devuelve los grupos en los que el usuario de la clave de API tiene una membresía activa.

GET /api/user0/groups

Nombre Descripción
limit Entero, opcional, valor predeterminado 50, máximo 500. Tamaño de página
offset Entero, opcional, valor predeterminado 0. Desplazamiento para la paginación
curl 'https://www.loomio.com/api/user0/groups?limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

La respuesta contiene una página de groups ordenada por ID de grupo ascendente, con el número total de grupos coincidentes en meta.total. Incluye grupos principales y subgrupos, incluidos los grupos cuya suscripción no está activa actualmente. Comprueba el campo enabled cuando una integración deba operar solo en grupos habilitados.

Entre los campos importantes de los grupos se incluyen:

Campo Descripción
id ID numérico del grupo utilizado por otros endpoints de la API de usuario
key Clave corta y estable utilizada en las URL de Loomio
handle Identificador del grupo legible para las personas
name Nombre del grupo
full_name Nombre del grupo que incluye el contexto del grupo principal
parent_id ID numérico del grupo principal de un subgrupo; en los demás casos, null
enabled Indica si el grupo y la suscripción están activos
memberships_count Número de membresías activas y pendientes
accepted_memberships_count Número de membresías aceptadas
pending_memberships_count Número de invitaciones pendientes
admin_memberships_count Número de administradores del grupo
discussions_count Número de discusiones directamente en el grupo
polls_count Número de encuestas directamente en el grupo
subgroups_count Número de subgrupos

La respuesta puede incluir ajustes adicionales del grupo, registros relacionados del grupo principal y las membresías del usuario de la API. Los clientes deben ignorar los campos que no utilizan.

Obtener un grupo

Devuelve un grupo visible para el usuario de la clave de API.

GET /api/user0/groups/:id_or_key_or_handle

El identificador puede ser el ID numérico, la clave o el identificador legible del grupo.

curl https://www.loomio.com/api/user0/groups/123 \
  -H 'Authorization: Bearer YOUR_API_KEY'

curl https://www.loomio.com/api/user0/groups/example-group \
  -H 'Authorization: Bearer YOUR_API_KEY'

La respuesta contiene el grupo en el array groups y utiliza los mismos campos que el endpoint de listado. Una solicitud de un grupo al que el usuario de la clave de API no puede acceder devuelve un error de permisos.

Membresías

Listar membresías

Lista las membresías visibles para el usuario de la clave de API. Los miembros del grupo pueden consultar los nombres, los ID, los títulos y los roles de los miembros. Las direcciones de correo electrónico solo se incluyen para la cuenta del propio usuario de la clave de API o cuando ese usuario es administrador del grupo.

GET /api/user0/memberships

Parámetros

Nombre Descripción
group_id Entero, obligatorio. ID del grupo cuyas membresías se listarán
limit Entero, opcional, valor predeterminado 50. Tamaño de página
offset Entero, opcional, valor predeterminado 0. Desplazamiento para la paginación

Compatibilidad con versiones anteriores: per y from se aceptan como alias de limit y offset y seguirán funcionando.

La respuesta contiene una página de memberships y los registros de users relacionados. meta.total es el número total de membresías visibles en el grupo antes de aplicar la paginación.

Ejemplo

curl 'https://www.loomio.com/api/user0/memberships?group_id=123&limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Gestionar membresías

Envía una lista de direcciones de correo electrónico. Se enviará una invitación al grupo a todas las direcciones nuevas. A diferencia de la consulta de membresías, esta operación requiere permisos de administrador del grupo.

POST /api/user0/memberships

Parámetros

Nombre Descripción
group_id Entero, obligatorio. ID del grupo cuyas membresías se gestionarán
emails Array de cadenas de texto, obligatorio. Direcciones de correo electrónico de las personas a las que invitar al grupo
remove_absent Booleano. Si es true, elimina del grupo a cualquier persona cuya dirección de correo electrónico no esté en la lista

Ejemplo

curl https://www.loomio.com/api/user0/memberships \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "emails": [
      "person@example.com"
    ]
  }'

Si pasas remove_absent=1, se eliminarán del grupo todos los miembros que no estén incluidos en la lista. Ten cuidado, podrías eliminar a todos los miembros de tu grupo.

curl https://www.loomio.com/api/user0/memberships \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "emails": [
      "person@example.com"
    ],
    "remove_absent": 1
  }'

Esto devuelve un objeto con {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.

Informe de participación

Devuelve los mismos datos agregados de participación que utiliza el informe de participación de Loomio.

GET /api/user0/reports

Parámetros

Nombre Descripción
section Sección del informe: base, users o countries. Usa users para la actividad por persona
group_scope custom o my. El valor antiguo all se trata como my porque las claves de la API de usuario nunca reciben acceso a toda la instancia
group_ids ID de grupos separados por comas cuando group_scope=custom. Se ignoran los ID de grupos a los que el usuario de la API no pertenece
start_month Primer mes que se incluye, en formato YYYY-MM; por defecto, hace 12 meses
end_month Último mes que se incluye, en formato YYYY-MM; por defecto, el mes actual
interval Intervalo para la sección base: day, week, month o year
member_type Establécelo en delegate con section=users para devolver solo los delegados actuales

Una persona es delegada cuando tiene una membresía activa como delegada en cualquiera de los grupos seleccionados. Sus recuentos se agregan para todos los grupos seleccionados. Se devuelven las filas de los delegados incluso cuando todos los recuentos de actividad son cero. Los recuentos abarcan hilos, comentarios, encuestas, votos, conclusiones y reacciones; no son tasas de participación en las votaciones. Las filas de usuarios también incluyen las papeletas de votaciones identificadas que se han emitido, utilizado para votar o dejado sin utilizar. Las encuestas anónimas se excluyen de todos los recuentos de votación por persona. all_votes_cast es verdadero solo cuando se ha emitido al menos una papeleta y se han utilizado todas las papeletas emitidas para votar.

La API aplica las mismas reglas de visibilidad de los grupos que el informe de la aplicación. Una clave de la API de usuario no puede revelar datos del informe de grupos a los que ese usuario no puede acceder.

Ejemplo

curl 'https://www.loomio.com/api/user0/reports?section=users&group_scope=custom&group_ids=123&member_type=delegate&start_month=2026-01&end_month=2026-09' \
  -H 'Authorization: Bearer YOUR_API_KEY'

El array users contiene filas completas de actividad:

{
  "users": [
    {
      "id": 456,
      "name": "Ada Lovelace",
      "country": "NZ",
      "delegate": true,
      "threads": 2,
      "comments": 8,
      "polls": 1,
      "votes": 5,
      "votes_cast": 5,
      "votes_issued": 6,
      "votes_missed": 1,
      "all_votes_cast": false,
      "outcomes": 1,
      "reactions": 4
    }
  ]
}

Encuestas

Crear una encuesta

Crea una encuesta como el usuario de la clave de API.

POST /api/user0/polls

Parámetros

Nombre Descripción
group_id Entero, opcional, null por defecto. ID del grupo de la encuesta. Si se proporciona discussion_id, se ignora group_id
discussion_id Entero, opcional, null por defecto. ID del hilo de discusión al que añadir esta encuesta
title Cadena de texto, obligatoria. Título de la encuesta
poll_type Cadena de texto, obligatoria. Valores: proposal, poll, count, score, ranked_choice, meeting, dot_vote
details Cadena de texto, opcional. Texto del cuerpo de la encuesta
details_format Cadena de texto, opcional, md por defecto. Valores: md o html
options Nombres simples de opciones como array de cadenas de texto. Para proposal, usa agree, disagree, abstain o block para obtener las etiquetas, los iconos, los significados y las preguntas estándar. Para meeting, proporciona cadenas de texto con fechas o fechas y horas en formato ISO 8601. Para los demás tipos de encuesta, proporciona nombres de opciones. Para opciones detalladas, usa poll_options_attributes en su lugar
poll_options_attributes Alternativa a options: un array de objetos de opciones con nombres, significados, preguntas, iconos y orden. Consulta Crear una encuesta con opciones detalladas
reason_prompt Cadena de texto, opcional. Pregunta compartida para el motivo del voto, utilizada por los tipos de encuesta sin preguntas por opción, como poll, score y ranked_choice
stance_reason_required Cadena de texto, optional por defecto. Valores: disabled, optional, required, required_for_disagree_or_block, required_for_block. Los dos últimos se aplican a los iconos disagree y block. Las encuestas anónimas deshabilitan los motivos del voto
closing_at Cadena de texto en formato ISO 8601 o null, null por defecto. Ejemplo: 2026-09-01T12:00:00Z. Si es null, la votación está deshabilitada y la encuesta se considera en preparación
specified_voters_only Booleano, opcional, false por defecto. Si es true, solo pueden votar las personas especificadas. Si es false, se invitará a votar a todas las personas del grupo
hide_results Cadena de texto, opcional, off por defecto. Valores: off, until_vote, until_closed
shuffle_options Booleano, false por defecto. Muestra las opciones a los votantes en orden aleatorio
anonymous Booleano, opcional, false por defecto. Oculta las identidades de los votantes
recipient_audience group o null, opcional, null por defecto. Si es group, se notificará a todo el grupo
notify_on_closing_soon Cadena de texto, opcional, nobody por defecto. Valores: nobody, author, voters_uncast, voters
recipient_user_ids Array de IDs de usuarios a quienes notificar o invitar
recipient_emails Array de direcciones de correo electrónico de personas a quienes invitar a votar
recipient_message Mensaje que se incluirá en la invitación por correo electrónico
notify_recipients Booleano, false por defecto. Si es false, añade personas sin enviar notificaciones. Si es true, todas las personas invitadas en esta solicitud recibirán una notificación por correo electrónico

Ejemplo

curl https://www.loomio.com/api/user0/polls \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "title": "example poll",
    "poll_type": "proposal",
    "options": [
      "agree",
      "disagree"
    ],
    "closing_at": "2026-09-01T12:00:00Z",
    "recipient_emails": [
      "person@example.com"
    ]
  }'

Crear un borrador de encuesta con muchas opciones

Envía todos los nombres de las opciones en el array options. Omitir closing_at crea una encuesta en preparación con la votación deshabilitada; no oculta la encuesta a las personas que pueden leer el hilo. Añade un valor futuro de closing_at cuando estés listo para abrir la votación.

Añade todos los nombres de tus opciones al array:

curl https://www.loomio.com/api/user0/polls \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "title": "Meeting venue",
    "poll_type": "poll",
    "options": [
      "Town hall",
      "Library",
      "Community centre"
    ]
  }'

Crear una encuesta con opciones detalladas

Usa options para una lista de nombres, o poll_options_attributes cuando cada opción necesite un significado, una pregunta para el motivo del voto o un icono. Elige un formato por solicitud. Ambos formatos funcionan en un cuerpo JSON plano o dentro de un objeto poll.

Cada objeto de poll_options_attributes acepta estos campos:

Campo Descripción
name Cadena de texto, obligatoria para una opción nueva. La etiqueta que se muestra a los votantes
meaning Cadena de texto, opcional. Explica qué significa elegir esta opción
prompt Cadena de texto, opcional. Pregunta para el motivo del voto que se muestra al seleccionar esta opción en una encuesta de tipo proposal, count o check. Para los demás tipos de encuesta, establece reason_prompt en la encuesta
icon Cadena de texto, opcional. Para proposal, count y check, usa agree, disagree, abstain o block
priority Entero. Orden de las opciones, empezando por 0. Proporciona una prioridad distinta para cada opción; las opciones de reunión se ordenan por fecha
test_operator Cadena de texto o null, opcional. Requisito de proporción de votos: gte significa como mínimo y lte significa como máximo. Establece null para deshabilitar el requisito
test_percent Entero, opcional. Porcentaje para el requisito de proporción de votos, de 0 a 100
test_against Cadena de texto, opcional. score_percent compara la proporción de la opción respecto a la puntuación total o los puntos asignados; voter_percent compara los votantes de la opción con todos los votantes con derecho a voto
id Entero. Inclúyelo al editar una opción existente; omítelo para una opción nueva
_destroy Booleano, opcional. Establece true junto con el id de una opción existente para eliminarla

Crea una propuesta con etiquetas y preguntas personalizadas para las opciones:

curl https://www.loomio.com/api/user0/polls \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "title": "Should we adopt this proposal?",
    "poll_type": "proposal",
    "stance_reason_required": "optional",
    "poll_options_attributes": [
      {
        "name": "Support",
        "meaning": "I support adopting this proposal",
        "prompt": "What do you support about it?",
        "icon": "agree",
        "priority": 0
      },
      {
        "name": "Oppose",
        "meaning": "I would prefer another approach",
        "prompt": "What would you change?",
        "icon": "disagree",
        "priority": 1
      }
    ]
  }'

Para una encuesta normal, usa el mismo formato de opciones detalladas con un reason_prompt compartido en la encuesta:

curl https://www.loomio.com/api/user0/polls \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "title": "Choose a venue",
    "poll_type": "poll",
    "reason_prompt": "Why do you prefer this venue?",
    "stance_reason_required": "optional",
    "poll_options_attributes": [
      {
        "name": "Town hall",
        "meaning": "Central, accessible venue",
        "priority": 0
      },
      {
        "name": "Library",
        "meaning": "Smaller room with no hire fee",
        "priority": 1
      }
    ]
  }'

Estos ejemplos omiten closing_at, por lo que la votación permanece deshabilitada hasta que se establezca una fecha de cierre futura.

Mostrar una encuesta

Obtén una encuesta mediante el ID de la encuesta, un entero, o la clave, una cadena de texto.

GET /api/user0/polls/:id

Ejemplo

curl https://www.loomio.com/api/user0/polls/abc123 \
  -H 'Authorization: Bearer YOUR_API_KEY'

Listar encuestas

Lista las encuestas de un grupo visibles para el usuario de la clave de API, incluidas las encuestas independientes y las encuestas dentro de discusiones. En un grupo visible públicamente, una persona que no sea miembro puede listar las encuestas públicas; las encuestas privadas siguen restringidas a los usuarios que pueden leerlas en Loomio. La respuesta incluye la conclusión actual de cada encuesta visible, por lo que puedes usar status=closed para listar las encuestas cerradas y leer sus conclusiones cuando se hayan establecido.

Para mostrar el estado de las decisiones junto a las discusiones, obtén las discusiones y las encuestas del mismo grupo, usando status=all para las encuestas, y relaciona sus valores de topic_id. Obtén todas las páginas usando limit y offset. Una discusión puede tener varias encuestas, así que elige qué encuesta determina el estado que muestras, por ejemplo, la encuesta creada más recientemente. Un valor de closed_at distinto de null identifica una encuesta cerrada; un valor null en closing_at indica un borrador. Cuando una encuesta tiene una conclusión, su current_outcome_id identifica un registro en el array outcomes de la respuesta; relaciona el poll_id de ese registro con el id de la encuesta.

Para una sola discusión, también puedes leer los elementos de su hilo usando GET /api/user0/threads/:topic_id/items. Esto devuelve las encuestas y las conclusiones del hilo junto con sus otros elementos. Obtén todas las páginas para incluir el hilo completo.

GET /api/user0/polls

Parámetros

Nombre Descripción
group_id Entero, obligatorio. ID del grupo cuyas encuestas se listarán
status Cadena de texto, opcional, active por defecto. Valores: active, closed, all
limit Entero, opcional, 50 por defecto. Tamaño de página
offset Entero, opcional, 0 por defecto. Desplazamiento para la paginación

Compatibilidad con versiones anteriores: per y from se aceptan como alias de limit y offset y seguirán funcionando.

Ejemplo

curl 'https://www.loomio.com/api/user0/polls?group_id=123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Editar una encuesta

Edita una encuesta como el usuario de la clave de API. Se aplican los mismos permisos que en Loomio: el usuario debe tener permiso para editar esa encuesta.

PATCH /api/user0/polls/:id

Parámetros

Nombre Descripción
title Título actualizado
details Detalles actualizados de la encuesta
details_format md o html, opcional, md por defecto
options Nombres actualizados de las opciones. Cambiar las opciones puede afectar a los votos existentes según el estado de la encuesta
poll_options_attributes Alternativa a options. Actualiza los objetos de opciones detalladas mediante id, añade objetos sin id o elimina una opción con id y _destroy: true. Las opciones omitidas permanecen sin cambios
reason_prompt Pregunta compartida actualizada para el motivo del voto en los tipos de encuesta sin preguntas por opción
stance_reason_required Requisito actualizado para el motivo del voto; se aplican los mismos valores que al crear una encuesta
closing_at Cadena de texto en formato ISO 8601 o null
recipient_audience group o null. Si es group, se notificará a todo el grupo
recipient_user_ids Array de IDs de usuarios a quienes notificar o invitar
recipient_emails Array de direcciones de correo electrónico de personas a quienes invitar a votar
recipient_message Mensaje que se incluirá en la invitación por correo electrónico

Ejemplo

curl https://www.loomio.com/api/user0/polls/123 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "title": "updated poll title",
    "details": "updated details",
    "details_format": "md"
  }'

Editar opciones detalladas

Obtén los IDs de las opciones del array poll_options en una respuesta de creación o consulta. Envía solo los campos que quieras cambiar, junto con el id de cada opción existente:

curl https://www.loomio.com/api/user0/polls/123 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "poll_options_attributes": [
      {
        "id": 456,
        "meaning": "Updated explanation",
        "prompt": "What would improve this proposal?"
      },
      {
        "name": "Abstain",
        "meaning": "I leave the decision to others",
        "icon": "abstain",
        "priority": 2
      }
    ]
  }'

Los IDs de las opciones deben pertenecer a la encuesta que se está editando. Para editarla, necesitas permiso para editar la encuesta, y las encuestas cerradas no se pueden editar. Las encuestas anónimas también bloquean los cambios en la configuración de las opciones después de que se emita el primer voto.

Eliminar una encuesta de forma lógica

Elimina una encuesta de forma lógica como el usuario de la clave de API. Esto descarta la encuesta y conserva el registro de la encuesta.

DELETE /api/user0/polls/:id

Ejemplo

curl https://www.loomio.com/api/user0/polls/123 \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_API_KEY'

Busca discusiones, comentarios, encuestas, votos y conclusiones visibles para el usuario de la clave API. Los resultados incluyen contenido público incluso cuando el usuario no es miembro del grupo al que pertenece ese contenido; el contenido privado sigue sujeto a las reglas habituales de visibilidad de los temas.

GET /api/user0/search

Parámetros

Nombre Descripción
query Texto de búsqueda. Se admiten coincidencias exactas y aproximadas
group_id Restringe los resultados a un grupo visible
org_id Restringe los resultados a un grupo principal visible y a sus subgrupos visibles. Usa 0 para las discusiones directas
type Restringe los resultados a un tipo: Discussion, Comment, Poll, Stance u Outcome
types Lista de tipos de resultados separados por comas
tag Restringe los resultados a los temas con esta etiqueta
author_id Restringe los resultados al contenido de un autor. Sin query, devuelve la actividad reciente visible de ese autor
order Establécelo en authored_at_desc para ordenar el contenido coincidente por fecha de creación
curl 'https://www.loomio.com/api/user0/search?query=quarterly+planning&type=Discussion' \
  -H 'Authorization: Bearer YOUR_API_KEY'

La respuesta contiene un array search_results. Cada resultado identifica el registro coincidente y el contexto visible de ese registro mediante campos como searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at y tags. Los campos que no se aplican a un resultado tienen el valor null.

Hilos

Listar hilos

Lista los hilos de discusión y de encuesta visibles para el usuario de la clave API, ordenados por la actividad más reciente. El ID de un hilo es el valor de topic_id.

GET /api/user0/threads

Parámetros

Nombre Descripción
limit Número entero, opcional, valor predeterminado 50. Tamaño de página
offset Número entero, opcional, valor predeterminado 0. Desplazamiento para la paginación

Ejemplo

curl 'https://www.loomio.com/api/user0/threads?limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Leer un hilo

Lee un hilo, la secuencia ordenada de eventos del hilo o el documento Markdown con todo el contenido visible del hilo.

GET /api/user0/threads/:topic_id

GET /api/user0/threads/:topic_id/items

GET /api/user0/threads/:topic_id/markdown

El endpoint items acepta estos parámetros de paginación:

Nombre Descripción
limit Número entero, opcional, valor predeterminado 50, máximo 500. Tamaño de página
offset Número entero, opcional, valor predeterminado 0. Desplazamiento para la paginación

Ejemplo

GET https://www.loomio.com/api/user0/threads/<topic_id>
GET https://www.loomio.com/api/user0/threads/<topic_id>/items?limit=50&offset=0
GET https://www.loomio.com/api/user0/threads/<topic_id>/markdown

El endpoint items devuelve una página de la secuencia de eventos en orden ascendente, incluidos los comentarios, las encuestas, los votos y las conclusiones visibles. meta.total es el número total de elementos del hilo. Obtén las páginas siguientes para leer toda la secuencia. El endpoint markdown devuelve todo el contenido visible del hilo en un único documento Markdown. Los motivos de los votos solo se incluyen cuando son visibles para el usuario de la clave API.

Todos los endpoints de hilos aplican los mismos permisos que la interfaz de Loomio. La clave API no concede acceso a un hilo que el usuario no pueda abrir normalmente.

Webhooks

La API de usuario se basa en solicitudes: una integración llama a Loomio cuando quiere leer o modificar datos. Un webhook de grupo permite enviar los datos en la dirección contraria. Loomio envía los eventos seleccionados del grupo a tu endpoint a medida que ocurren, por lo que una integración no necesita consultar periódicamente la API REST para detectar cambios.

Los webhooks se configuran por grupo y requieren permisos de administrador del grupo. Puedes gestionarlos desde la interfaz de Loomio:

  1. Abre el grupo.
  2. Abre el menú del grupo y selecciona Integraciones de chat.
  3. Añade la integración que coincida con el formato de datos que acepta tu endpoint. Para un endpoint de uso general, usa el formato Mattermost/Markdown.
  4. Introduce un nombre y la URL de destino.
  5. Selecciona los eventos que Loomio debe enviar automáticamente.
  6. Guarda la integración y usa Conexión de prueba para enviar un mensaje de prueba.

Usa un destino HTTPS con una URL que no se pueda adivinar. Loomio exige que el destino resuelva a una dirección pública y bloquea las solicitudes a direcciones de redes locales o privadas.

Los agentes y otras integraciones también pueden gestionar webhooks mediante los endpoints de chatbots con autenticación Bearer descritos a continuación. El recurso se llama chatbots por compatibilidad con las integraciones de chat de Loomio, pero también representa webhooks salientes de uso general.

Listar webhooks

Devuelve las integraciones de chat configuradas para un grupo. El usuario de la clave de API debe ser administrador de ese grupo. La respuesta incluye las URL de destino, por lo que no debe exponerse a los miembros del grupo que no sean administradores.

GET /api/user0/chatbots?group_id=123

Nombre Descripción
group_id Número entero, obligatorio. ID del grupo cuyos webhooks se listarán
limit Número entero, opcional, valor predeterminado 50, máximo 500. Tamaño de página
offset Número entero, opcional, valor predeterminado 0. Desplazamiento para la paginación
curl 'https://www.loomio.com/api/user0/chatbots?group_id=123&limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

La respuesta contiene una página de chatbots ordenada por ID de integración ascendente, con el número total de integraciones del grupo en meta.total. Cada integración tiene estos campos:

Campo Descripción
id ID de la integración utilizado para actualizarla y eliminarla
group_id Grupo que recibe los eventos
name Nombre administrativo de la integración
kind webhook para un webhook saliente o matrix para una integración de Matrix
webhook_kind Formato de los datos: markdown, slack, discord, microsoft o webex
server URL de destino
event_kinds Eventos enviados automáticamente
notification_only Indica si los mensajes contienen solo el encabezado de la notificación

Crear un webhook

POST /api/user0/chatbots

curl https://www.loomio.com/api/user0/chatbots \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "name": "Planning system",
    "kind": "webhook",
    "webhook_kind": "markdown",
    "server": "https://hooks.example.org/loomio/unguessable-token",
    "event_kinds": [
      "new_discussion",
      "new_comment",
      "poll_created",
      "outcome_created"
    ],
    "notification_only": false
  }'

El usuario de la clave de API debe ser administrador del grupo indicado por group_id. Antes de guardar el destino, se comprueba que sea una URL pública.

Actualizar un webhook

PATCH /api/user0/chatbots/:id

Envía los campos que deban cambiar. No se puede transferir el webhook a otro grupo cambiando group_id.

curl https://www.loomio.com/api/user0/chatbots/456 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "name": "Planning events",
    "event_kinds": [
      "new_discussion",
      "outcome_created"
    ]
  }'

Probar el destino de un webhook

Envía un mensaje de prueba compatible con Markdown a un destino antes o después de guardar la configuración.

POST /api/user0/chatbots/check

curl https://www.loomio.com/api/user0/chatbots/check \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "server": "https://hooks.example.org/loomio/unguessable-token"
  }'

Eliminar un webhook

DELETE /api/user0/chatbots/:id

curl https://www.loomio.com/api/user0/chatbots/456 \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_API_KEY'

Eliminar la configuración detiene los envíos futuros. No elimina ningún contenido del grupo de Loomio.

Tipos de eventos

Un webhook puede suscribirse a estos tipos de eventos:

Evento Cuándo se envía
new_discussion Se inicia una discusión
discussion_edited Se edita una discusión
new_comment Se crea un comentario
poll_created Se inicia una encuesta
poll_edited Se edita una encuesta
poll_closing_soon Se acerca la hora de cierre de una encuesta
poll_expired Una encuesta alcanza la hora de cierre
poll_closed_by_user Una persona cierra una encuesta manualmente
poll_reopened Se reabre una encuesta
outcome_created Se publica una conclusión
outcome_updated Se actualiza una conclusión
outcome_review_due Llega la fecha de revisión de una conclusión
stance_created Se emite un voto
stance_updated Se cambia un voto

El webhook pertenece a un grupo y recibe los eventos de ese grupo a los que está suscrito. Las personas también pueden seleccionar explícitamente la integración al compartir o enviar algunas notificaciones, incluso cuando el evento automático correspondiente no está seleccionado.

Envío HTTP

Loomio envía una petición HTTP POST asíncrona a la URL configurada con esta cabecera:

Content-Type: application/json; charset=utf-8

El tiempo de espera de la petición es de cinco segundos. Una respuesta 2xx, incluida 204 No Content, se considera satisfactoria. Los servicios que reciben webhooks deben responder con rapidez, procesar las tareas más largas de forma asíncrona y admitir envíos duplicados o fuera de orden.

Actualmente, Loomio no añade una firma del webhook, una cabecera con un secreto compartido, un ID de evento ni un ID de envío. Trata la URL de destino completa como una credencial, no la expongas públicamente e incluye en ella un token que no se pueda adivinar cuando el servicio receptor lo admita. Si necesitas un esquema de eventos estable y legible por máquinas o un envío firmado, usa el webhook como notificación de cambios y obtén los registros actuales mediante la API de usuario autenticada.

Formatos de los datos enviados

Los datos enviados por los webhooks son mensajes destinados a servicios de chat y preparados para mostrarse. No son registros completos serializados de Loomio. Los enlaces del mensaje identifican el contenido de Loomio afectado; una integración puede consultar después la API de usuario cuando necesite el estado actual en un formato estructurado.

Formato de integración Campos JSON principales
Mattermost/Markdown text, icon_url, username
Slack text
Discord content, limitado a aproximadamente 1900 caracteres
Microsoft Teams @type, @context, themeColor, text, sections
Webex markdown

Por ejemplo, el formato general de Markdown envía un cuerpo con esta estructura:

{
  "text": "Ada started a discussion: [Quarterly planning](https://example.loomio.org/d/example)",
  "icon_url": "https://example.loomio.org/path/to/group-logo.png",
  "username": "Loomio"
}

El texto exacto del mensaje depende del evento, la configuración regional del grupo, el ajuste de solo notificaciones y la versión de Loomio. Los servicios receptores deben basarse en los campos de nivel superior documentados del formato seleccionado, en lugar de analizar la redacción de las frases.

Esta página se tradujo automáticamente. Si alguna palabra es incorrecta o poco clara, escribe a contact@loomio.org y la corregiremos.