Skip to main content
POST
https://app.famulor.de
/
api
/
ai
/
generate-reply
Generate AI Reply
curl --request POST \
  --url https://app.famulor.de/api/ai/generate-reply \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "assistant_id": 123,
  "customer_identifier": "<string>",
  "message": "<string>",
  "variables": {
    "customer_name": "<string>",
    "source": "<string>",
    "order_id": "<string>"
  }
}
'
{
  "success": true,
  "conversation_id": "f3wqsa-asd23-grt4-ggg34-derf4",
  "customer_identifier": "+49155551234",
  "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
}
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.
Rate Limit: This endpoint is limited to 5 requests per minute per API token to prevent abuse.

​
Request Body

​
assistant_id
integer
required
The ID of the assistant to use for reply generation. Must belong to your account.
​
customer_identifier
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.
​
message
string
required
The customer’s message to reply to.
​
variables
object
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.

​
Response Fields

​
success
boolean
Indicates whether the request was successful
​
conversation_id
string
The UUID of the conversation. Use this to track or reference the conversation later.
​
customer_identifier
string
The customer identifier provided in the request
​
reply
string
The AI-generated reply to the customer message
​
function_calls
array
Array of function calls the assistant made while processing the message. Empty array if no functions were called.
​
ai_disabled
boolean
Indicates whether AI replies are disabled for this conversation (e.g. due to manual takeover)

​
Error Responses

​
success
boolean
Will be false when an error occurs
​
error
string
Error message describing what went wrong
​
error_code
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

​
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
{
  "success": true,
  "conversation_id": "f3wqsa-asd23-grt4-ggg34-derf4",
  "customer_identifier": "+49155551234",
  "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
}