Ir al contenido

Agentes

Los agentes de tu cuenta: qué devuelve la API de cada uno, cómo filtrarlos por local y cómo cambiarles el nombre.

Los endpoints de agentes devuelven los agentes de tu cuenta: el nombre, el tipo, el idioma, el local al que sirven y sus etiquetas. Sirven para resolver los ids que usan otros endpoints (agent_ids en Llamadas). Para leer hace falta el permiso bots:read; para cambiar el nombre de un agente, bots:write.

Endpoint Ruta Permiso
Listar agentes GET /v1/agents bots:read
Un agente GET /v1/agents/{agent_id} bots:read
Cambiar el nombre de un agente PATCH /v1/agents/{agent_id} bots:write

GET /v1/agents devuelve los agentes activos de tu cuenta, paginados.

Parámetro Tipo Por defecto Reglas
venue_ids UUID, repetible todos tus locales 100 como máximo; solo los agentes de esos locales (ids de GET /venues)
agent_ids texto, repetible todos 100 como máximo; solo esos agentes
limit de 1 a 100 50 Agentes por página
cursor texto ninguno meta.next_cursor de la página anterior, con los mismos filtros y el mismo limit
customer_id UUID el cliente de la clave Consulta qué lee cada clave
Ventana de terminal
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/agents?limit=50"
{
"data": [
{
"id": "…",
"name": "Recepción",
"type": "HOTEL_BOT",
"language": "SPANISH",
"venue_id": "…",
"venue_group_id": null,
"tags": []
}
],
"meta": { "limit": 50, "next_cursor": null }
}
Campo Qué es
id Identificador del agente; el agent_id de las llamadas
name Nombre del agente en el portal
type Tipo de agente, p. ej. RESTAURANT, HOTEL_BOT, FLEXBOT_V2
language Idioma por defecto del agente, tal como está en el portal: SPANISH, CATALAN, ENGLISH…
venue_id Local al que sirve, si es uno
venue_group_id Grupo de locales al que sirve, si es uno
tags Etiquetas del agente

GET /v1/agents/{agent_id} devuelve los mismos campos de un agente, con una cabecera ETag: la versión que tienes que enviar como If-Match al cambiarle el nombre. Un agente que no es de tu cliente, o fuera de los locales a los que está limitada tu clave, es 404 not_found.

Ventana de terminal
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/agents/<agent_id>"

PATCH /v1/agents/{agent_id} cambia el nombre visible del agente, y nada más. name es obligatorio, de 1 a 120 caracteres. Envía el ETag del agente como If-Match (consulta Escribir datos).

Ventana de terminal
curl -s -X PATCH "$BASE/agents/<agent_id>" \
-H "apikey: $BOOKLINE_API_KEY" \
-H "Content-Type: application/json" \
-H 'If-Match: "<etag>"' \
-d '{"name": "Recepción"}'

La respuesta es el agente tal como queda guardado, con su nuevo ETag. La configuración del agente se cambia en el portal.

  • Solo los campos de esta página. La configuración interna del agente (textos, integraciones, credenciales) no forma parte de la API, y solo se puede cambiar el nombre.
  • Agentes activos. Los agentes eliminados no se listan ni se pueden leer por id.
  • Claves limitadas a locales. La clave solo lista los agentes de esos locales, y un venue_ids fuera de ellos es 403 insufficient_scope.
  • Si creas agentes mientras recorres las páginas, alguno puede repetirse en la siguiente: quédate con uno por id.