> ## Documentation Index
> Fetch the complete documentation index at: https://docs.haloagents.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat

> POST /api/sdk/chat -- Send a message and receive a complete AI response.

## 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](https://docs.haloagents.ai/advanced/identity-verification.md).

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

**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](https://docs.haloagents.ai/contacts/context-entries.md).

**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

```bash cURL theme={null}
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" }
        }
      }
    }
  }'
```

```typescript JavaScript theme={null}
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:**

```json theme={null}
{
  "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
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.