Chat - HaloAgents

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

string

required

The user’s message. Max 10,000 characters.

string

The user’s external ID. Set to "anonymous" or omit for unauthenticated users.

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.

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. Must be 1-200 characters of letters, digits and _ . : @ -.

string

The company’s external ID. Used to look up company data if the user isn’t already linked to a company.

string

default:"chat"

One of "chat", "voice", "video", or "livehelp".

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.

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.

object

Key-value user traits sent with this request. Merged with DB traits (request wins on conflicts).

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.

array

Previous messages for multi-turn context. Each item should have speaker/role and text/content fields.

string

Behavioral data about the user’s session (page views, clicks, frustration signals). Max 5,000 characters.

Response

string

The AI agent’s response text.

string

Unique session identifier for this conversation. Pass this back in subsequent requests to maintain continuity.

string

The ID of the agent that handled the request.

array

Actions triggered by the AI (highlights, ticket creation, etc.).

number

Confidence score (0-1). Based on knowledge base coverage, tool usage, and escalation signals.

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

const response = await fetch("https://api.haloagents.ai/api/sdk/chat", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer ab_live_xxxxxxxxxxxxxxxx",
  },
  body: JSON.stringify({
    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" }
        }
      }
    }
  }),
});

const data = await response.json();
console.log(data.text);

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
}

​Endpoint

​Authentication

​Request Body

​Response

​Example

Endpoint

Authentication

Request Body

Response

Example