Ctrl K

Conversations & Call Records

Create Conversation

Create a new conversation session with an AI assistant

Updated 25 Jan 2026

On this page

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_idstringrequired

The UUID of the assistant to start the conversation with. Must be a valid assistant UUID that exists in the system.

typestring

The type of conversation. Possible values:

widget - Web widget conversation (default, charged)
test - Test conversation (free, for development)

variablesobject

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

statusboolean

Indicates whether the request was successful

conversation_idstring

The unique UUID identifier for the created conversation. Use this ID for subsequent message requests.

historyarray

The initial conversation history. If the assistant has an initial message configured, it will be included here.

rolestring

  The message role: `assistant` or `user`

contentstring

  The message content

Error Responses

statusboolean

Will be false when an error occurs

errorstring

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.voxlink.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"
    }
  }'

const response = await fetch('https://app.voxlink.ai/api/conversations', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    assistant_id: '550e8400-e29b-41d4-a716-446655440000',
    type: 'widget',
    variables: {
      customer_name: 'John Smith',
      company: 'Acme Corp',
      source: 'pricing_page'
    }
  })
});

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

import requests

response = requests.post(
    'https://app.voxlink.ai/api/conversations',
    json={
        'assistant_id': '550e8400-e29b-41d4-a716-446655440000',
        'type': 'widget',
        'variables': {
            'customer_name': 'John Smith',
            'company': 'Acme Corp',
            'source': 'pricing_page'
        }
    }
)

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

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

{
  "status": true,
  "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "history": []
}

{
  "status": false,
  "error": "Assistant not found"
}

{
  "status": false,
  "error": "Insufficient balance. Please top up your account."
}

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.

Related guides

Conversations & Call Records

Conversations Overview

Track and review text-based conversations with your AI assistant

Read guide →

Conversations & Call Records

Viewing & Managing Conversations

How to view, filter, and manage your conversation history

Read guide →

Conversations & Call Records

List Conversations

List all conversations for the authenticated user with filtering and pagination

Read guide →

Conversations & Call Records

Get Conversation

Retrieve the message history of a conversation

Read guide →