Skip to main content
POST
https://app.autocalls.ai/api/
/
conversations
curl -X POST "https://app.autocalls.ai/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?"
    }
  ]
}
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://app.autocalls.ai/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.