Skip to main content
POST
/
conversations
curl -X POST "https://call.aiployees.com/api/conversations" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "widget",
    "variables": {
      "customer_name": "John Smith",
      "company": "Acme Corp",
      "source": "pricing_page"
    }
  }'

{
  "status": true,
  "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "history": [
    {
      "role": "assistant",
      "content": "Hello John Smith! Welcome to Acme Corp support. How can I help you today?"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.aiployees.com/llms.txt

Use this file to discover all available pages before exploring further.

This endpoint creates a new conversation session with an AI assistant. Use this to initiate a text-based chat session through your web widget or application.

​
Request Body

​
assistant_id
string
required
The UUID of the assistant to start the conversation with. Must be a valid assistant UUID that exists in the system.
​
type
string
default:"widget"
The type of conversation. Possible values:
  • widget - Web widget conversation (default, charged)
  • test - Test conversation (free, for development)
​
variables
object
Custom variables to pass to the assistant. These variables can be used in the assistant’s system prompt and initial message using {{variable_name}} syntax.Common use cases:
  • Pre-filling customer information from forms
  • Passing context from your application
  • Customizing assistant behavior per session

​
Response Fields

​
status
boolean
Indicates whether the request was successful
​
conversation_id
string
The unique UUID identifier for the created conversation. Use this ID for subsequent message requests.
​
history
array
The initial conversation history. If the assistant has an initial message configured, it will be included here.

​
Error Responses

​
status
boolean
Will be false when an error occurs
​
error
string
Error message describing what went wrong. Possible values:
  • Assistant not found - The provided assistant_id does not exist
  • Insufficient balance. Please top up your account. - The assistant owner’s account balance is too low
curl -X POST "https://call.aiployees.com/api/conversations" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "widget",
    "variables": {
      "customer_name": "John Smith",
      "company": "Acme Corp",
      "source": "pricing_page"
    }
  }'

{
  "status": true,
  "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "history": [
    {
      "role": "assistant",
      "content": "Hello John Smith! Welcome to Acme Corp support. How can I help you today?"
    }
  ]
}

​
Pricing

  • Widget conversations: $0.01 per user message
  • Test conversations: Free (for development and testing)

​
Next Steps

After creating a conversation, use the Send Message endpoint to exchange messages with the assistant.