Generate AI Reply

This endpoint generates an AI response for a given message using your configured assistant. It automatically creates or reuses conversations based on the customer identifier, making it ideal for integrating AI responses into external platforms, CRMs, or custom chat interfaces.

Request Body

Response Fields

  The name of the function that was called

  The arguments passed to the function

  The result returned by the function

Error Responses

curl -X POST "https://app.voxlink.ai/api/user/ai/generate-reply" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": 123,
    "customer_identifier": "+14155551234",
    "message": "Hi, I would like to schedule an appointment",
    "variables": {
      "customer_name": "John Smith",
      "source": "whatsapp"
    }
  }'

const response = await fetch('https://app.voxlink.ai/api/user/ai/generate-reply', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    assistant_id: 123,
    customer_identifier: '+14155551234',
    message: 'Hi, I would like to schedule an appointment',
    variables: {
      customer_name: 'John Smith',
      source: 'whatsapp'
    }
  })
});

const data = await response.json();
console.log(data.reply);

import requests

response = requests.post(
    'https://app.voxlink.ai/api/user/ai/generate-reply',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'assistant_id': 123,
        'customer_identifier': '+14155551234',
        'message': 'Hi, I would like to schedule an appointment',
        'variables': {
            'customer_name': 'John Smith',
            'source': 'whatsapp'
        }
    }
)

data = response.json()
print(data['reply'])

$response = Http::withToken('YOUR_API_TOKEN')
    ->post('https://app.voxlink.ai/api/user/ai/generate-reply', [
        'assistant_id' => 123,
        'customer_identifier' => '+14155551234',
        'message' => 'Hi, I would like to schedule an appointment',
        'variables' => [
            'customer_name' => 'John Smith',
            'source' => 'whatsapp'
        ]
    ]);

$reply = $response->json()['reply'];

{
  "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
}

{
  "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
}

{
  "success": false,
  "error": "Assistant not found or does not belong to you",
  "error_code": "ASSISTANT_NOT_FOUND"
}

{
  "success": false,
  "error": "Insufficient balance. Please top up your account.",
  "error_code": "INSUFFICIENT_BALANCE"
}

{
  "message": "The assistant id field is required.",
  "errors": {
    "assistant_id": ["The assistant id field is required."]
  }
}

{
  "message": "Too Many Attempts.",
  "retry_after": 60
}

Use Cases

Multi-Channel AI Responses

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

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

CRM Integration

Integrate AI responses into your CRM or helpdesk:

1. Use the CRM contact ID as the customer_identifier
2. Pass customer data as variables for personalized responses
3. The conversation persists across sessions using the same identifier

Custom Chat Interfaces

Build your own chat interface powered by your VoxLink assistant:

1. Generate a unique identifier for each user session
2. Send messages through this endpoint
3. Display the AI responses in your interface

Conversation Persistence

Conversations are automatically persisted based on the assistant_id and customer_identifier combination:

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

Best Practices

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