> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ouraicalling.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generar respuesta de IA

> Genera una respuesta de IA usando un asistente a partir de un identificador de cliente

<Warning>
  **API de Famulor 1.0 (legado).** Esta página se aplica únicamente a Famulor 1.0 (`app.famulor.de`) y se conserva por compatibilidad. Para la plataforma actual, usa la [referencia de la API de Famulor 2.0](/es/api-reference/introduction).
</Warning>

Este endpoint genera automáticamente una respuesta inteligente a un mensaje de cliente usando tu asistente de IA configurado. El sistema gestiona automáticamente el contexto de la conversación de cada cliente, de modo que el asistente recuerda los mensajes anteriores y puede responder de forma contextual. Ideal para integrarlo en plataformas de mensajería externas, CRM o interfaces de chat personalizadas.

<Warning>
  **Límite de frecuencia**: este endpoint está limitado a 5 solicitudes por minuto por token de API para evitar abusos.
</Warning>

### Cuerpo de la solicitud

<ParamField body="assistant_id" type="integer" required>
  El ID del asistente que se usará para generar la respuesta. Debe pertenecer a tu cuenta.
</ParamField>

<ParamField body="customer_identifier" type="string" required>
  Un identificador único del cliente. Se usa para mantener el contexto de la conversación a lo largo de varios mensajes.

  **Ejemplos**: número de teléfono, dirección de correo electrónico, ID de contacto del CRM, ID de usuario de Facebook.

  **Longitud máxima**: 255 caracteres.

  **Importante**: usa siempre el mismo formato para el mismo cliente, de modo que el contexto se asocie correctamente.
</ParamField>

<ParamField body="message" type="string" required>
  El mensaje del cliente al que se va a responder.
</ParamField>

<ParamField body="variables" type="object" optional>
  Variables de contexto opcionales que se pasan al asistente. Se combinan con las variables de conversación existentes.

  Útil para pasar datos del cliente, contexto de sesión u otros metadatos que permitan personalizar la respuesta.

  <Expandable title="Ejemplos de variables">
    <ParamField body="customer_name" type="string">
      Nombre del cliente para dirigirse a él de forma personalizada
    </ParamField>

    <ParamField body="source" type="string">
      Origen del mensaje (p. ej. `whatsapp`, `facebook`, `sms`)
    </ParamField>

    <ParamField body="order_id" type="string">
      Número de pedido para solicitudes de soporte
    </ParamField>
  </Expandable>
</ParamField>

### Campos de la respuesta

<ResponseField name="success" type="boolean">
  Indica si la solicitud se realizó correctamente
</ResponseField>

<ResponseField name="conversation_id" type="string">
  El UUID de la conversación. Úsalo para hacer seguimiento o referenciar la conversación más adelante.
</ResponseField>

<ResponseField name="customer_identifier" type="string">
  El identificador de cliente proporcionado en la solicitud
</ResponseField>

<ResponseField name="reply" type="string">
  La respuesta generada por la IA para el mensaje del cliente
</ResponseField>

<ResponseField name="function_calls" type="array">
  Array de llamadas a función que hizo el asistente al procesar el mensaje. Array vacío si no se llamó a ninguna función.

  <Expandable title="Objeto de llamada a función">
    <ResponseField name="name" type="string">
      El nombre de la función que se llamó
    </ResponseField>

    <ResponseField name="arguments" type="object">
      Los argumentos pasados a la función
    </ResponseField>

    <ResponseField name="result" type="object">
      El resultado de la llamada a función
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="ai_disabled" type="boolean">
  Indica si las respuestas de IA están desactivadas para esta conversación (p. ej., por una intervención manual)
</ResponseField>

### Respuestas de error

<ResponseField name="success" type="boolean">
  Será `false` cuando se produzca un error
</ResponseField>

<ResponseField name="error" type="string">
  Mensaje de error que describe lo que ha fallado
</ResponseField>

<ResponseField name="error_code" type="string">
  Código de error legible por máquina. Valores posibles:

  * `ASSISTANT_NOT_FOUND` - el ID del asistente no es válido o no pertenece a tu cuenta
  * `INSUFFICIENT_BALANCE` - el saldo de tu cuenta es insuficiente para procesar el mensaje
</ResponseField>

### Casos de uso

#### Respuestas de IA multicanal

Usa este endpoint para añadir respuestas de IA a cualquier plataforma de mensajería:

1. Recibe un mensaje de WhatsApp, Facebook, SMS u otro canal
2. Llama a este endpoint con el mensaje y el identificador de cliente
3. Envía la respuesta de la IA de vuelta por el canal original

#### Integración con CRM

Integra respuestas de IA en tu CRM o sistema de helpdesk:

* Usa el ID de contacto del CRM como `customer_identifier`
* Pasa datos del cliente como variables para respuestas personalizadas
* La conversación persiste entre sesiones cuando se usa el mismo identificador

#### Interfaces de chat personalizadas

Crea tu propia interfaz de chat impulsada por tu asistente de Famulor:

* Genera un identificador único para cada sesión de usuario
* Envía mensajes a través de este endpoint
* Muestra las respuestas de la IA en tu interfaz

#### Persistencia de la conversación

Las conversaciones se almacenan automáticamente según la combinación de `assistant_id` y `customer_identifier`:

* **Mismo identificador**: los mensajes se añaden a la conversación existente, manteniendo el contexto completo
* **Identificador nuevo**: se crea una nueva conversación para el cliente
* **Combinación de variables**: cuando se proporcionan variables, se combinan con las variables de conversación existentes

### Buenas prácticas

* **Usa identificadores consistentes**: usa siempre el mismo formato para los identificadores de cliente (p. ej., siempre E.164 para números de teléfono)
* **Pasa contexto relevante**: usa el campo `variables` para proporcionar datos del cliente que ayuden a la IA a personalizar las respuestas
* **Gestiona los límites de frecuencia**: implementa lógica de reintento con retroceso exponencial para las solicitudes limitadas por frecuencia
* **Guarda los ID de conversación**: guarda el `conversation_id` devuelto para referencia o depuración posterior
* **Supervisa los costes**: haz seguimiento del uso para gestionar los costes, especialmente en integraciones de alto volumen

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "success": true,
    "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "customer_identifier": "+14155551234",
    "reply": "Hi John! I'd be happy to help you schedule an appointment. What day and time work best for you?",
    "function_calls": [],
    "ai_disabled": false
  }
  ```

  ```json 200 Success (With Function Calls) theme={null}
  {
    "success": true,
    "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "customer_identifier": "+14155551234",
    "reply": "I've checked our calendar and we have availability tomorrow at 2 PM and Friday at 10 AM. Which works better for you?",
    "function_calls": [
      {
        "name": "check_availability",
        "arguments": {
          "start_date": "2025-01-08",
          "days": 7
        },
        "result": {
          "slots": ["2025-01-08 14:00", "2025-01-10 10:00"]
        }
      }
    ],
    "ai_disabled": false
  }
  ```

  ```json 404 Assistant Not Found theme={null}
  {
    "success": false,
    "error": "Assistant not found or does not belong to you",
    "error_code": "ASSISTANT_NOT_FOUND"
  }
  ```

  ```json 402 Insufficient Balance theme={null}
  {
    "success": false,
    "error": "Insufficient balance. Please top up your account.",
    "error_code": "INSUFFICIENT_BALANCE"
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The assistant id field is required.",
    "errors": {
      "assistant_id": ["The assistant id field is required."]
    }
  }
  ```

  ```json 429 Rate Limited theme={null}
  {
    "message": "Too Many Attempts.",
    "retry_after": 60
  }
  ```
</ResponseExample>

<Tip>
  Páginas relacionadas: [Introducción](/es/api-v1/introduction) y [Guía de autenticación](/es/api-v1/authentication), y [Ejemplos de integración de la API](/es/api-v1/introduction).
</Tip>