> ## Documentation Index > Fetch the complete documentation index at: https://docs.bookliftagent.com/llms.txt > Use this file to discover all available pages before exploring further. # Conversar con un agente > Envía el historial de la conversación y recibe la respuesta del agente, que aplica los servicios, precios y horarios de ese negocio y puede cerrar una reserva en su calendario. **Consume 1 crédito** por llamada con éxito. Si el agente falla, el crédito se devuelve automáticamente. Manda el historial completo (o los últimos mensajes) para que el agente no pierda el hilo. Si repites `sesion` entre llamadas, recordamos la conversación por ti. ## OpenAPI ````yaml /openapi.yaml post /negocios/{negocioId}/chat openapi: 3.1.0 info: title: Booklift API version: 1.0.0 description: > Agentes de IA que reservan y venden por WhatsApp, para negocios con cita previa. La API está pensada para **agencias y partners** que gestionan varios negocios: una sola clave cubre todos los locales de tu organización. ### Autenticación Todas las llamadas llevan tu clave en la cabecera `Authorization`: ``` Authorization: Bearer bk_live_xxxxxxxxxxxx ``` Usa `bk_test_...` para probar sin consumir créditos de producción. **La clave no debe salir del servidor**: llamar desde un navegador la expondría a cualquiera que abra el inspector. ### Créditos Cada conversación atendida consume **1 crédito**. Tu plan define cuántos tienes al mes. Al agotarlos, la API responde `402 sin_creditos` y el agente deja de contestar hasta el siguiente periodo o hasta que amplíes el plan. Consulta tu saldo en cualquier momento con `GET /v1/yo` — no consume créditos. ### Reintentos seguros Envía una cabecera `Idempotency-Key` única en cada `POST /v1/negocios/{id}/chat`. Si repites la llamada con la misma clave (por un timeout, por ejemplo), devolvemos la respuesta original **sin cobrarte otra vez**. contact: name: Soporte Booklift url: https://bookliftagent.com servers: - url: https://api.bookliftagent.com/v1 description: Producción security: - claveApi: [] tags: - name: Cuenta description: Tu organización y tu consumo. - name: Agentes description: Los negocios que gestionas y sus conversaciones. paths: /negocios/{negocioId}/chat: post: tags: - Agentes summary: Conversar con un agente description: | Envía el historial de la conversación y recibe la respuesta del agente, que aplica los servicios, precios y horarios de ese negocio y puede cerrar una reserva en su calendario. **Consume 1 crédito** por llamada con éxito. Si el agente falla, el crédito se devuelve automáticamente. Manda el historial completo (o los últimos mensajes) para que el agente no pierda el hilo. Si repites `sesion` entre llamadas, recordamos la conversación por ti. operationId: conversar parameters: - $ref: '#/components/parameters/NegocioId' - name: Idempotency-Key in: header required: false description: >- Identificador único de esta llamada. Un reintento con el mismo valor no vuelve a cobrar. schema: type: string maxLength: 200 example: b3f1c2d4-1111-2222-3333-444455556666 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PeticionChat' example: sesion: cliente-34600111222 mensajes: - rol: cliente contenido: Hola, quiero cita para un corte esta semana responses: '200': description: Respuesta del agente content: application/json: schema: $ref: '#/components/schemas/RespuestaChat' example: respuesta: >- ¡Hola! Tengo hueco el jueves a las 16:00 o el viernes a las 11:30. ¿Cuál te viene mejor? calendario_url: null negocio_id: peluqueria-sol '400': $ref: '#/components/responses/PeticionInvalida' '401': $ref: '#/components/responses/NoAutorizado' '402': description: Sin créditos en este periodo content: application/json: schema: $ref: '#/components/schemas/Error' example: error: codigo: sin_creditos mensaje: >- Has agotado los créditos de este mes. Amplía tu plan para seguir. limite_mes: 25000 periodo: '2026-08-01' '404': $ref: '#/components/responses/NoEncontrado' '409': description: El negocio existe pero su agente aún no está desplegado content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: El agente no ha respondido. No se te ha cobrado el crédito. content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: NegocioId: name: negocioId in: path required: true description: Identificador del negocio dentro de tu organización. schema: type: string example: peluqueria-sol schemas: PeticionChat: type: object required: - mensajes properties: mensajes: type: array minItems: 1 description: Historial de la conversación, del más antiguo al más reciente. items: $ref: '#/components/schemas/Mensaje' sesion: type: string description: > Identificador estable de la conversación (por ejemplo, el teléfono del cliente). Si lo repites, recordamos el hilo y los datos del cliente entre llamadas y entre días. Si lo omites, cada llamada empieza de cero. example: cliente-34600111222 RespuestaChat: type: object properties: respuesta: type: string description: El texto que enviar al cliente. calendario_url: type: - string - 'null' description: Enlace .ics para añadir la cita, si se ha cerrado una reserva. negocio_id: type: string Error: type: object properties: error: type: object properties: codigo: type: string description: Identificador estable para tu código. No cambia entre versiones. mensaje: type: string description: Explicación legible. Puede cambiar; no la uses para bifurcar. additionalProperties: true description: | Algunos errores añaden contexto útil. Por ejemplo, `sin_creditos` incluye `limite_mes` y `periodo` para que puedas avisar al cliente sin una llamada extra. Mensaje: type: object required: - rol - contenido properties: rol: type: string enum: - cliente - agente description: Quién escribió el mensaje. contenido: type: string maxLength: 4000 responses: PeticionInvalida: description: El cuerpo de la petición no es válido content: application/json: schema: $ref: '#/components/schemas/Error' NoAutorizado: description: Falta la clave o no es válida content: application/json: schema: $ref: '#/components/schemas/Error' example: error: codigo: clave_invalida mensaje: La clave de API no es válida o fue revocada. NoEncontrado: description: | El negocio no existe en tu organización. Devolvemos 404 también cuando existe pero es de otra organización: confirmarlo sería una fuga. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: codigo: negocio_no_encontrado mensaje: Ese negocio no existe en tu organización. securitySchemes: claveApi: type: http scheme: bearer description: Tu clave de API (`bk_live_...` o `bk_test_...`). ````