Listas#

Los métodos de esta sección crean y eliminan listas, cambian sus campos y gestionan los registros: añadirlos, leerlos, actualizarlos y eliminarlos. Por ejemplo, tu sitio web puede mantener al día una lista «Carta de la cafetería», y el bot se la muestra a las personas.

Cómo se estructura una lista#

Una lista tiene dos partes:

• El esquema: el nombre de la lista y sus campos. Con él trabajan los métodos de la página Listas y campos. Los nombres de los métodos lo llaman exactamente así: getListSchema, createListSchema.
• Los registros: las filas de la lista con los valores de los campos. Con ellos trabajan los métodos de la página Registros.

Las listas pertenecen a un proyecto. Una lista se puede crear en un proyecto o en un bot; en ese caso, también pasa al proyecto de ese bot. La API da acceso a todas las listas de los proyectos del propietario de la clave: tanto las creadas en bots como las creadas directamente en el proyecto.

Identificadores#

El slug es el nombre del campo en las plantillas: el valor se guarda en el registro con ese nombre, y los bloques del bot lo leen con el mismo nombre. Los campos creados en tu cuenta lo reciben automáticamente; a través de la API lo defines tú.

Tipos de campo#

El tipo se define en el parámetro type al crear el campo y no se puede cambiar después.

Un campo vacío se devuelve como null.

Fecha y hora#

Una hora sin zona horaria se trata como UTC: "2026-10-15 14:30" se guarda como 14:30 UTC. Para enviar la hora local, añade el desfase: "2026-10-15T14:30:00-05:00". Un campo date no recorta la hora: si envías una fecha con hora, la hora se conserva.

Dinero#

La moneda se define en el campo al crearlo (currency) y no se envía con los registros. Es un código ISO 4217 de tres letras: USD, EUR, GBP. En createListSchema la moneda se puede omitir, y entonces es USD; en addListSchemaField es obligatoria. Un código desconocido: 422.

Envía los importes en unidades principales: dólares, no céntimos. El importe se redondea a los decimales de la moneda (dos para el dólar y el euro), y las mitades se redondean hacia arriba: 0.295 se guarda como 0.30.

Archivos e imágenes#

El valor de un campo file o image es un objeto. A través de la API solo puedes guardar un enlace a un archivo disponible en internet:

{
  "url": "https://example.com/menu/cappuccino.jpg",
  "storage": "url",
  "name": "cappuccino.jpg",
  "type": "image"
}

Advertencia

Sin "storage": "url", o con un enlace de otro tipo (no http/https), el valor no se guarda y no hay aviso: el campo queda en null y no se produce ningún error.

Las demás claves (como uuid o path) se ignoran: el campo guarda solo el enlace externo, y la respuesta lo devuelve exactamente como lo enviaste. Un enlace a un archivo del almacenamiento de la plataforma (como los que contienen las respuestas para los archivos subidos en tu cuenta) solo se puede guardar dentro de tu propia cuenta; un enlace a un archivo de otra cuenta no se guarda, y el campo queda en null. Si envías a updateListItem el archivo que ya está en el registro, por ejemplo un registro completo de getListItems, se queda como estaba.

En las respuestas, un archivo se describe con un objeto con las claves type, mime_type, created_at, name, size, storage, caption, meta (ancho, alto, duración, códec) y url. Los enlaces a archivos subidos en tu cuenta son temporales: descarga el archivo de inmediato o vuelve a pedir el registro.

Contacto y bot#

Los campos contact y bot reciben un ID. El contacto debe pertenecer a tu bot y el bot debe ser tuyo; si no, la respuesta es 403. Un ID que no existe no pasa la validación: 422.

Además del valor del propio campo, el registro recibe las claves de servicio contact_id o bot_id; el filtro de getListItems funciona sobre ellas. Si una lista tiene varios campos de este tipo, contienen el valor del último.

Configuración del campo#

Importante

Por defecto, un campo creado a través de la API es obligatorio, a diferencia de tu cuenta. Si un campo puede quedar vacío, envía "is_required": false.

Límites#

• Hasta 5000 listas por proyecto.
• De 1 a 30 campos al crear una lista.
• Nombres de listas y campos: hasta 255 caracteres.
• No se pueden usar nombres de campos de servicio: id, _id, contact, contact_id, bot, bot_id, user, user_id, project, project_id, data, schema_id, created_at, updated_at, deleted_at ni cualquier nombre que empiece por __. Para ese slug, la API responde con 422 y el texto «The slug is reserved.».

Las reglas generales (la clave, la frecuencia de solicitudes, los códigos de error) se describen en la página API.

Métodos#