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

# Generate AI Reply

> Generates an AI reply using an assistant based on a customer identifier

This endpoint automatically generates an intelligent reply to a customer message using your configured AI assistant. The system automatically manages conversation context for each customer, so the assistant remembers previous messages and can respond contextually. Ideal for integration into external messaging platforms, CRMs, or custom chat interfaces.

<Warning>
  **Rate Limit**: This endpoint is limited to 5 requests per minute per API token to prevent abuse.
</Warning>

### Request Body

<ParamField body="assistant_id" type="integer" required>
  The ID of the assistant to use for reply generation. Must belong to your account.
</ParamField>

<ParamField body="customer_identifier" type="string" required>
  A unique identifier for the customer. This is used to maintain conversation context across multiple messages.

  **Examples**: Phone number, email address, CRM contact ID, Facebook user ID.

  **Maximum length**: 255 characters.

  **Important**: Always use the same format for the same customer to ensure context is correctly mapped.
</ParamField>

<ParamField body="message" type="string" required>
  The customer's message to reply to.
</ParamField>

<ParamField body="variables" type="object" optional>
  Optional context variables to pass to the assistant. These are merged with existing conversation variables.

  Useful for passing customer data, session context, or other metadata that can personalize the reply.

  <Expandable title="Variable Examples">
    <ParamField body="customer_name" type="string">
      Customer name for personalized addressing
    </ParamField>

    <ParamField body="source" type="string">
      Message source (e.g. `whatsapp`, `facebook`, `sms`)
    </ParamField>

    <ParamField body="order_id" type="string">
      Order number for support requests
    </ParamField>
  </Expandable>
</ParamField>

### Response Fields

<ResponseField name="success" type="boolean">
  Indicates whether the request was successful
</ResponseField>

<ResponseField name="conversation_id" type="string">
  The UUID of the conversation. Use this to track or reference the conversation later.
</ResponseField>

<ResponseField name="customer_identifier" type="string">
  The customer identifier provided in the request
</ResponseField>

<ResponseField name="reply" type="string">
  The AI-generated reply to the customer message
</ResponseField>

<ResponseField name="function_calls" type="array">
  Array of function calls the assistant made while processing the message. Empty array if no functions were called.

  <Expandable title="Function Call Object">
    <ResponseField name="name" type="string">
      The name of the function that was called
    </ResponseField>

    <ResponseField name="arguments" type="object">
      The arguments passed to the function
    </ResponseField>

    <ResponseField name="result" type="object">
      The result of the function call
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="ai_disabled" type="boolean">
  Indicates whether AI replies are disabled for this conversation (e.g. due to manual takeover)
</ResponseField>

### Error Responses

<ResponseField name="success" type="boolean">
  Will be `false` when an error occurs
</ResponseField>

<ResponseField name="error" type="string">
  Error message describing what went wrong
</ResponseField>

<ResponseField name="error_code" type="string">
  Machine-readable error code. Possible values:

  * `ASSISTANT_NOT_FOUND` - The assistant ID is invalid or does not belong to your account
  * `INSUFFICIENT_BALANCE` - Your account balance is too low to process the message
</ResponseField>

### Use Cases

#### Multi-Channel AI Replies

Use this endpoint to add AI replies to any messaging platform:

1. Receive a message from WhatsApp, Facebook, SMS, or another channel
2. Call this endpoint with the message and customer identifier
3. Send the AI reply back through the original channel

#### CRM Integration

Integrate AI replies into your CRM or helpdesk system:

* Use the CRM contact ID as `customer_identifier`
* Pass customer data as variables for personalized replies
* The conversation persists across sessions when using the same identifier

#### Custom Chat Interfaces

Build your own chat interface powered by your Famulor assistant:

* Generate a unique identifier for each user session
* Send messages through this endpoint
* Display the AI replies in your interface

#### Conversation Persistence

Conversations are automatically stored based on the combination of `assistant_id` and `customer_identifier`:

* **Same identifier**: Messages are added to the existing conversation, maintaining full context
* **New identifier**: A new conversation is created for the customer
* **Variable merging**: When variables are provided, they are merged with existing conversation variables

### Best Practices

* **Use consistent identifiers**: Always use the same format for customer identifiers (e.g. always E.164 for phone numbers)
* **Pass relevant context**: Use the `variables` field to provide customer data that helps the AI personalize replies
* **Handle rate limits**: Implement retry logic with exponential backoff for rate-limited requests
* **Store conversation IDs**: Save the returned `conversation_id` for later reference or debugging
* **Monitor costs**: Track usage to manage costs, especially for high-volume integrations

<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>
  Related pages: [Introduction](/en/api-reference/introduction) and [Authentication Guide](/en/developers/authentication-guide), and [API Integration Examples](/en/developers/api-integration-examples).
</Tip>