Skip to main content
POST
/
live-chat
/
sessions
curl -X POST https://api.avoca.ai/v1/live-chat/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "site_abc123",
    "visitor": {
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
      "referrer": "https://google.com",
      "page_url": "https://yoursite.com/services/ac-repair"
    },
    "initial_message": "Hi, I need help with my AC unit",
    "custom_fields": {
      "lead_source": "Google Ads",
      "service_interest": "AC Repair"
    }
  }'

{
  "data": {
    "session_id": "chat_jkl012",
    "assistant_id": "asst_chat_001",
    "status": "active",
    "websocket_url": "wss://chat.avoca.ai/v1/sessions/chat_jkl012",
    "widget_config": {
      "theme_color": "#2563EB",
      "greeting_message": "Hi! I'm here to help with your HVAC needs. What can I assist you with today?",
      "business_hours": true
    },
    "estimated_wait": 0
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2024-01-20T10:30:00Z"
  }
}
Create AI-powered live chat sessions for website or app visitors. The chat widget can be embedded on any page and provides real-time communication with intelligent responses.

​
Request

​
source_id
string
required
Your website or app identifier from Avoca dashboard
​
visitor
object
required
Visitor information for context
​
initial_message
string
Optional pre-filled message from visitor
​
custom_fields
object
Additional visitor data from your website or app
​
assistant_id
string
Specific AI assistant to use (defaults to primary live chat assistant)

​
Response

​
session_id
string
Unique identifier for the chat session
​
assistant_id
string
ID of the AI assistant handling the chat
​
status
string
Session status: active, queued, closed
​
websocket_url
string
WebSocket URL for real-time chat communication
​
widget_config
object
Configuration for the chat widget
​
estimated_wait
number
Estimated wait time in seconds if queued
curl -X POST https://api.avoca.ai/v1/live-chat/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "site_abc123",
    "visitor": {
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
      "referrer": "https://google.com",
      "page_url": "https://yoursite.com/services/ac-repair"
    },
    "initial_message": "Hi, I need help with my AC unit",
    "custom_fields": {
      "lead_source": "Google Ads",
      "service_interest": "AC Repair"
    }
  }'

{
  "data": {
    "session_id": "chat_jkl012",
    "assistant_id": "asst_chat_001",
    "status": "active",
    "websocket_url": "wss://chat.avoca.ai/v1/sessions/chat_jkl012",
    "widget_config": {
      "theme_color": "#2563EB",
      "greeting_message": "Hi! I'm here to help with your HVAC needs. What can I assist you with today?",
      "business_hours": true
    },
    "estimated_wait": 0
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2024-01-20T10:30:00Z"
  }
}

​
WebSocket Events

Once connected to the WebSocket URL, you can send and receive real-time messages:

​
Send Message

{
  "type": "message",
  "text": "I need to schedule AC maintenance"
}

​
Receive Message

{
  "type": "message",
  "text": "I'd be happy to help schedule your AC maintenance. What's your ZIP code?",
  "timestamp": "2024-01-20T10:31:00Z"
}

​
Session Events

{
  "type": "event",
  "event": "appointment_scheduled",
  "data": {
    "appointment_id": "appt_123",
    "date": "2024-01-22",
    "time": "2:00 PM - 4:00 PM"
  }
}