Skip to main content

​
Endpoint

POST /api/sdk/chat
Send a user message through the multi-agent AI pipeline and receive a complete response.

​
Authentication

Requires your publishable widget key in the Authorization header: 
Authorization: Bearer ab_live_xxxxxxxxxxxxxxxx
The org_id is derived from the widget key. You do not need to pass it in the request body.

​
Request Body

​
message
string
required
The user’s message. Max 10,000 characters.
​
user_id
string
The user’s external ID. Set to "anonymous" or omit for unauthenticated users.
​
user_token
string
JWT signed with your Identity Secret (HS256) for identity verification. Must include a user_id claim matching the user_id field. May include additional trusted claims (email, name, role, plan, company_id). Required if identity verification is enabled. See Identity Verification.
​
session_id
string
Session identifier for continuing a conversation. If omitted, a new session ID is generated and returned in the response. Pass the same session_id across messages to maintain conversation continuity.
​
company_id
string
The company’s external ID. Used to look up company data if the user isn’t already linked to a company.
​
mode
string
default:"chat"
One of "chat", "voice", "video", or "livehelp".
​
agent_id
string
Target a specific agent for this request. If omitted, Halo routes to your active agent. Use this when you have multiple agents (e.g. a sales agent and a support agent) and want to pin the conversation to one of them.
​
images
string[]
Optional array of image URLs (or data: URLs) to attach to the user message. Used for multimodal chat (screenshots, photos). Stored alongside the message in the transcript.
​
custom_fields
object
Key-value user traits sent with this request. Merged with DB traits (request wins on conflicts).
​
context
object
Structured context entries. Each key maps to a ContextEntry with label, optional type, and value. Merged with DB context (request wins on conflicts). See Context Entries.
​
conversation_history
array
Previous messages for multi-turn context. Each item should have speaker/role and text/content fields.
​
behavior_context
string
Behavioral data about the user’s session (page views, clicks, frustration signals). Max 5,000 characters.

​
Response

​
text
string
The AI agent’s response text.
​
session_id
string
Unique session identifier for this conversation. Pass this back in subsequent requests to maintain continuity.
​
agent_id
string
The ID of the agent that handled the request.
​
actions
array
Actions triggered by the AI (highlights, ticket creation, etc.).
​
confidence
number
Confidence score (0-1). Based on knowledge base coverage, tool usage, and escalation signals.
​
routing
object
Present when the message was routed directly to a team instead of being answered by the AI (direct-to-team chat routing). Shape: { action: string, ticket_id?: string }. When this is set, text contains the routing acknowledgement copy and no further AI generation runs for the message.

​
Example

curl -X POST https://api.haloagents.ai/api/sdk/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ab_live_xxxxxxxxxxxxxxxx" \
  -d '{
    "user_id": "user_123",
    "message": "Why is my Google Ads integration not working?",
    "context": {
      "integrations": {
        "label": "Connected Integrations",
        "type": "integration",
        "value": {
          "google_ads": { "connected": true, "status": "error", "error": "Token expired" }
        }
      }
    }
  }'
Response: 
{
  "text": "I can see that your Google Ads integration has an expired OAuth token. To fix this, go to Settings > Integrations > Google Ads and click 'Reconnect'. You'll be prompted to re-authorize access through your Google account.",
  "session_id": "chat_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "agent_id": "agent-uuid",
  "actions": [],
  "confidence": 0.85
}