Skip to main content
POST
/
outbound
/
live-chat
/
message
curl -X POST https://api.avoca.ai/v1/outbound/live-chat/message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "visitor_id": "visitor_abc123",
    "message": "Hi! I noticed you are looking at our AC repair services. We have same-day appointments available. Can I help answer any questions?",
    "trigger": {
      "type": "page_visit",
      "page_url": "https://example.com/services/ac-repair",
      "time_on_page": 45
    },
    "personalization": {
      "current_interest": "AC Repair"
    },
    "quick_replies": [
      {
        "text": "Get a Quote",
        "value": "quote_request",
        "action": "quote"
      },
      {
        "text": "Schedule Service",
        "value": "schedule_service",
        "action": "schedule"
      },
      {
        "text": "Call Now",
        "value": "call_request",
        "action": "call"
      }
    ]
  }'

{
  "data": {
    "message_id": "msg_chat_789",
    "session_id": "chat_session_123",
    "status": "delivered",
    "visitor_status": "online",
    "engagement_score": 75
  },
  "meta": {
    "request_id": "req_abc456",
    "timestamp": "2024-01-20T14:30:00Z"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.avoca.ai/llms.txt

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

Initiate proactive live chat conversations with website visitors based on behavior, page visits, or customer data. Perfect for engaging high-intent visitors and providing immediate assistance.

​
Request

​
session_id
string
Existing chat session ID (if continuing conversation)
​
visitor_id
string
Unique visitor identifier (if no active session)
​
message
string
required
Message content to send
​
trigger
object
What triggered this proactive message
​
assistant_id
string
AI assistant to handle conversation (defaults to primary chat assistant)
​
personalization
object
Personalization data for the message
​
options
object
Message display options
​
quick_replies
array
Suggested quick reply buttons

​
Response

​
message_id
string
Unique message identifier
​
session_id
string
Chat session ID
​
status
string
Message status: sent, delivered, read
​
visitor_status
string
Visitor status: online, idle, offline
​
engagement_score
number
Likelihood of conversion (0-100)
curl -X POST https://api.avoca.ai/v1/outbound/live-chat/message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "visitor_id": "visitor_abc123",
    "message": "Hi! I noticed you are looking at our AC repair services. We have same-day appointments available. Can I help answer any questions?",
    "trigger": {
      "type": "page_visit",
      "page_url": "https://example.com/services/ac-repair",
      "time_on_page": 45
    },
    "personalization": {
      "current_interest": "AC Repair"
    },
    "quick_replies": [
      {
        "text": "Get a Quote",
        "value": "quote_request",
        "action": "quote"
      },
      {
        "text": "Schedule Service",
        "value": "schedule_service",
        "action": "schedule"
      },
      {
        "text": "Call Now",
        "value": "call_request",
        "action": "call"
      }
    ]
  }'

{
  "data": {
    "message_id": "msg_chat_789",
    "session_id": "chat_session_123",
    "status": "delivered",
    "visitor_status": "online",
    "engagement_score": 75
  },
  "meta": {
    "request_id": "req_abc456",
    "timestamp": "2024-01-20T14:30:00Z"
  }
}

​
Visitor Response Webhook

{
  "event": "live_chat.visitor_responded",
  "session_id": "chat_session_123",
  "timestamp": "2024-01-20T14:30:45Z",
  "data": {
    "message_id": "msg_visitor_001",
    "message": "Yes, I need AC repair",
    "quick_reply_clicked": {
      "value": "schedule_service",
      "action": "schedule"
    },
    "visitor": {
      "id": "visitor_abc123",
      "status": "engaged",
      "engagement_score": 85
    }
  }
}

​
Best Practices

  1. Timing: Wait 30-60 seconds before first engagement
  2. Relevance: Message should relate to the page they’re viewing
  3. Personalization: Use customer data when available
  4. Quick Replies: Provide 2-3 clear action options
  5. Frequency: Limit to one proactive message per session unless visitor engages