> ## 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.

# Générer une réponse IA

> Génère une réponse IA à l’aide d’un assistant, à partir d’un identifiant client

<Warning>
  **API Famulor 1.0 (héritée).** Cette page concerne uniquement Famulor 1.0 (`app.famulor.de`) et est conservée pour la compatibilité. Pour la plateforme actuelle, consultez la [référence API Famulor 2.0](/fr/api-reference/introduction).
</Warning>

Ce point de terminaison génère automatiquement une réponse intelligente à un message client à l’aide de votre assistant IA configuré. Le système gère automatiquement le contexte de conversation pour chaque client, de sorte que l’assistant se souvient des messages précédents et peut répondre de façon contextuelle. Idéal pour l’intégration dans des plateformes de messagerie externes, des CRM ou des interfaces de chat personnalisées.

<Warning>
  **Limite de débit** : ce point de terminaison est limité à 5 requêtes par minute et par jeton API afin d’éviter les abus.
</Warning>

### Corps de la requête

<ParamField body="assistant_id" type="integer" required>
  L’ID de l’assistant à utiliser pour générer la réponse. Doit appartenir à votre compte.
</ParamField>

<ParamField body="customer_identifier" type="string" required>
  Un identifiant unique pour le client. Il sert à maintenir le contexte de la conversation à travers plusieurs messages.

  **Exemples** : numéro de téléphone, adresse e-mail, identifiant de contact CRM, identifiant utilisateur Facebook.

  **Longueur maximale** : 255 caractères.

  **Important** : utilisez toujours le même format pour un même client afin que le contexte soit correctement associé.
</ParamField>

<ParamField body="message" type="string" required>
  Le message du client auquel répondre.
</ParamField>

<ParamField body="variables" type="object" optional>
  Variables de contexte facultatives à transmettre à l’assistant. Elles sont fusionnées avec les variables de conversation existantes.

  Utile pour transmettre des données client, le contexte de session ou d’autres métadonnées permettant de personnaliser la réponse.

  <Expandable title="Exemples de variables">
    <ParamField body="customer_name" type="string">
      Nom du client pour une salutation personnalisée
    </ParamField>

    <ParamField body="source" type="string">
      Source du message (par ex. `whatsapp`, `facebook`, `sms`)
    </ParamField>

    <ParamField body="order_id" type="string">
      Numéro de commande pour les demandes de support
    </ParamField>
  </Expandable>
</ParamField>

### Champs de réponse

<ResponseField name="success" type="boolean">
  Indique si la requête a réussi
</ResponseField>

<ResponseField name="conversation_id" type="string">
  L’UUID de la conversation. Utilisez-le pour suivre ou référencer la conversation ultérieurement.
</ResponseField>

<ResponseField name="customer_identifier" type="string">
  L’identifiant client fourni dans la requête
</ResponseField>

<ResponseField name="reply" type="string">
  La réponse générée par l’IA au message du client
</ResponseField>

<ResponseField name="function_calls" type="array">
  Tableau des appels de fonction effectués par l’assistant pendant le traitement du message. Tableau vide si aucune fonction n’a été appelée.

  <Expandable title="Objet d’appel de fonction">
    <ResponseField name="name" type="string">
      Le nom de la fonction appelée
    </ResponseField>

    <ResponseField name="arguments" type="object">
      Les arguments transmis à la fonction
    </ResponseField>

    <ResponseField name="result" type="object">
      Le résultat de l’appel de fonction
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="ai_disabled" type="boolean">
  Indique si les réponses IA sont désactivées pour cette conversation (par ex. en cas de reprise manuelle)
</ResponseField>

### Réponses d’erreur

<ResponseField name="success" type="boolean">
  Sera `false` en cas d’erreur
</ResponseField>

<ResponseField name="error" type="string">
  Message d’erreur décrivant le problème rencontré
</ResponseField>

<ResponseField name="error_code" type="string">
  Code d’erreur exploitable par une machine. Valeurs possibles :

  * `ASSISTANT_NOT_FOUND` - L’ID de l’assistant est invalide ou n’appartient pas à votre compte
  * `INSUFFICIENT_BALANCE` - Le solde de votre compte est insuffisant pour traiter le message
</ResponseField>

### Cas d’usage

#### Réponses IA multicanal

Utilisez ce point de terminaison pour ajouter des réponses IA à n’importe quelle plateforme de messagerie :

1. Recevez un message depuis WhatsApp, Facebook, SMS ou un autre canal
2. Appelez ce point de terminaison avec le message et l’identifiant client
3. Renvoyez la réponse IA via le canal d’origine

#### Intégration CRM

Intégrez les réponses IA à votre CRM ou à votre système d’assistance :

* Utilisez l’identifiant de contact CRM comme `customer_identifier`
* Transmettez les données client sous forme de variables pour personnaliser les réponses
* La conversation persiste entre les sessions tant que le même identifiant est utilisé

#### Interfaces de chat personnalisées

Créez votre propre interface de chat propulsée par votre assistant Famulor :

* Générez un identifiant unique pour chaque session utilisateur
* Envoyez les messages via ce point de terminaison
* Affichez les réponses IA dans votre interface

#### Persistance de la conversation

Les conversations sont automatiquement enregistrées selon la combinaison de `assistant_id` et `customer_identifier` :

* **Même identifiant** : les messages sont ajoutés à la conversation existante, en conservant le contexte complet
* **Nouvel identifiant** : une nouvelle conversation est créée pour le client
* **Fusion des variables** : lorsque des variables sont fournies, elles sont fusionnées avec les variables de conversation existantes

### Bonnes pratiques

* **Utilisez des identifiants cohérents** : conservez toujours le même format pour les identifiants client (par ex. toujours E.164 pour les numéros de téléphone)
* **Transmettez un contexte pertinent** : utilisez le champ `variables` pour fournir des données client qui aident l’IA à personnaliser ses réponses
* **Gérez les limites de débit** : mettez en place une logique de nouvelle tentative avec backoff exponentiel pour les requêtes limitées
* **Stockez les ID de conversation** : conservez le `conversation_id` renvoyé pour une référence ou un débogage ultérieurs
* **Surveillez les coûts** : suivez l’utilisation pour maîtriser les coûts, en particulier pour les intégrations à fort volume

<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>
  Pages associées : [Introduction](/fr/api-v1/introduction) et [Guide d’authentification](/fr/api-v1/authentication), et [Exemples d’intégration API](/fr/api-v1/introduction).
</Tip>