Create conversation

Creates a new conversation session with an AI assistant. Use this to initiate text-based chat through your web widget or application. The response includes a conversation_id to use for subsequent messages.

Endpoint

POST /conversations

This endpoint does not require authentication. It is called from your client application using the assistant’s public UUID.

Request

string

required

UUID of the assistant to start the conversation with.

string

default:"widget"

Conversation type:

widget — Web widget conversation. Charged at $0.01 per user message.
test — Free test conversation for development.

object

Custom variables to pass to the assistant. Accessible in the system prompt and initial message via {{variable_name}}.

Response

boolean

Whether the request was successful.

string

UUID of the created conversation. Use this for subsequent Send message calls.

array

Initial conversation history. Contains the assistant’s opening message if one is configured.

Show Message properties

string

Message sender: assistant or user.

string

Message content.

Example

curl -X POST "https://portal.intellixent.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"
    }
  }'

const response = await fetch('https://portal.intellixent.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'
    }
  })
});

const data = await response.json();
const conversationId = data.conversation_id;

200 Success

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

404 Assistant not found

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

400 Insufficient balance

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

After creating a conversation, use the Send message endpoint to exchange messages.

Overview

Assistants

Calls

Campaigns & Leads

Conversations

Messaging

Phone Numbers

Knowledge & Tools

Webhooks

Endpoint

Request

Response

Example

​Endpoint

​Request

​Response

​Example

Endpoint

Request

Response

Example