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 |
Listar agentes
Sección titulada «Listar agentes»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 |
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 |
Un agente
Sección titulada «Un 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.
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/agents/<agent_id>"Cambiar el nombre de un agente
Sección titulada «Cambiar el nombre de un agente»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).
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.
Reglas de los datos
Sección titulada «Reglas de los datos»- 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_idsfuera de ellos es 403insufficient_scope. - Si creas agentes mientras recorres las páginas, alguno puede repetirse en la siguiente: quédate con uno por
id.
Relacionado
Sección titulada «Relacionado»- Llamadas, Chats y Reservas: fíltralas con
agent_ids. - Escribir datos: versiones, reintentos y el límite de escritura.
