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"
  }
}
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