# Chat API

## What this covers

Typed chats with an agent, from your web chat or your own app. Start a conversation, then send each message and get the agent's reply in the response. The agent answers with the same job, knowledge and actions as on a call. Each reply costs ₹0.05 or $0.0005 from the wallet; messages from people are free.

Every example below runs as written once these are exported:

```bash
export DVAARIK_API_KEY="dvk_..."        # project API key, server side only
export DVAARIK_TOKEN="<account access token>"   # console session, from POST /console/auth/login
export CHAT_ID="<uuid>"
export PROJECT_ID="<uuid>"
```

A `<value>` inside a JSON body is a value you supply. Responses are JSON; every error body is `{ "detail": … }`. Each schema is expanded once per page, where it first appears.

### Machine door errors

Raised by the project-key dependency before any handler on this page runs.

| Status | Cause |
| --- | --- |
| `401` | `Missing API key` or `Invalid API key` — the `X-Api-Key` header is absent, unknown, or revoked. |
| `403` | `API key is not scoped to a project`, `Project unavailable`, or `API key is missing the required scope '<scope>'`. |
| `429` | The project's `api_rpm` ceiling was exceeded. Honour `Retry-After`; `X-RateLimit-*` headers are on every response. |

Scopes used on this page: `voice:read`, `voice:write`. Mint a key with only these.

### Account door errors

| Status | Cause |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. Refresh once, then re-authenticate. |
| `403` | The account is suspended or its email is not verified. |

## Operations — project API key

Call these from your own server with a project key. Never from a browser or a mobile bundle.

### GET `/v2/chats`

List conversations, the most recent message first, filtered by agent or channel.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:read` |
| Operation | `listChats` |
| Success | `200` `ChatPage` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `agent_id` | query | uuid or null | no |  |
| `channel_id` | query | uuid or null | no |  |
| `limit` | query | integer | no |  |
| `offset` | query | integer | no |  |

#### `ChatPage`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `data` | ChatInfo[] | yes |  |
| `next_offset` | integer or null | no |  |

#### `ChatInfo`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `agent_id` | uuid or null | yes |  |
| `channel` | "api" or "telegram" or "whatsapp" or "instagram" | yes |  |
| `channel_id` | uuid or null | yes |  |
| `created_at` | date-time | yes |  |
| `expires_at` | date-time | yes |  |
| `external_id` | string or null | yes |  |
| `external_name` | string or null | yes |  |
| `id` | uuid | yes |  |
| `last_message_at` | date-time | yes |  |
| `metadata` | object | yes |  |
| `retention_days` | integer | yes |  |
| `variables` | object | yes |  |

#### `FieldErrors`

A 422 from a route that names its fields: every field that failed validation, or one sentence when the request validated and was then refused.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `detail` | string or FieldError[] | yes | The fields that failed validation (each named), or a sentence for the developer. |

| Error | When |
| --- | --- |
| `401` | No API key was sent in X-Api-Key, or it is invalid or revoked. |
| `403` | The API key lacks the scope this route needs, or its account or project is unavailable. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |
| `429` | The project's requests-per-minute limit is reached; Retry-After says when to try again. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X GET "https://api.developers.dvaarik.com/v2/chats?limit=20" \
  -H "X-Api-Key: $DVAARIK_API_KEY"
```

### POST `/v2/chats`

Start a conversation with an agent. Give `variables` for the agent's job and your own `external_id` for the person; nothing is charged until a reply is written.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:write` |
| Operation | `startChat` |
| Success | `201` `ChatInfo` |

Request body: `ChatCreate`.

#### `ChatCreate`

Start a conversation with an agent (the chat API: your web chat, your own app).

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `agent_id` | uuid | yes |  |
| `external_id` | string or null | no |  |
| `metadata` | object | no |  |
| `variables` | object | no |  |

| Error | When |
| --- | --- |
| `401` | No API key was sent in X-Api-Key, or it is invalid or revoked. |
| `403` | The API key lacks the scope this route needs, or its account or project is unavailable. |
| `404` | The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |
| `429` | The project's requests-per-minute limit is reached; Retry-After says when to try again. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X POST "https://api.developers.dvaarik.com/v2/chats" \
  -H "X-Api-Key: $DVAARIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent uuid>",
    "external_id": "customer-4821",
    "variables": {
      "company": "Northline Dental"
    }
  }'
```

### GET `/v2/chats/{chat_id}`

Read a conversation with its newest messages, oldest first: each reply's status, cost, tokens and actions. Send `before` (from `next_before`) to read further back.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:read` |
| Operation | `getChat` |
| Success | `200` `ChatDetail` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `chat_id` | path | uuid | yes |  |
| `limit` | query | integer | no |  |
| `before` | query | date-time or null | no |  |

#### `ChatDetail`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `agent_id` | uuid or null | yes |  |
| `channel` | "api" or "telegram" or "whatsapp" or "instagram" | yes |  |
| `channel_id` | uuid or null | yes |  |
| `created_at` | date-time | yes |  |
| `expires_at` | date-time | yes |  |
| `external_id` | string or null | yes |  |
| `external_name` | string or null | yes |  |
| `id` | uuid | yes |  |
| `last_message_at` | date-time | yes |  |
| `messages` | ChatMessageInfo[] | yes |  |
| `metadata` | object | yes |  |
| `next_before` | date-time or null | no |  |
| `retention_days` | integer | yes |  |
| `variables` | object | yes |  |

#### `ChatMessageInfo`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `agent_version` | integer or null | no |  |
| `attachments` | string[] | no |  |
| `conversation_id` | uuid | yes |  |
| `cost_minor` | string | no | default "0" |
| `created_at` | date-time | yes |  |
| `currency` | string or null | no |  |
| `delivery_status` | "sent" or "delivered" or "read" or "failed" or null | no |  |
| `error` | string or null | no |  |
| `error_code` | string or null | no |  |
| `id` | uuid | yes |  |
| `input_tokens` | integer | no | default 0 |
| `model` | string or null | no |  |
| `money_scale` | integer or null | no |  |
| `output_tokens` | integer | no | default 0 |
| `parts` | integer or null | no |  |
| `price_minor` | string or null | no |  |
| `price_version` | string or null | no |  |
| `provider` | string or null | no |  |
| `role` | "user" or "agent" | yes |  |
| `sent_at` | date-time or null | no |  |
| `status` | "received" or "pending" or "ready" or "sending" or "sent" or "failed" or "ambiguous" | yes |  |
| `text` | string | yes | max length 8000 |
| `tool_calls` | ChatToolCall[] | no |  |

| Error | When |
| --- | --- |
| `401` | No API key was sent in X-Api-Key, or it is invalid or revoked. |
| `403` | The API key lacks the scope this route needs, or its account or project is unavailable. |
| `404` | The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |
| `429` | The project's requests-per-minute limit is reached; Retry-After says when to try again. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X GET "https://api.developers.dvaarik.com/v2/chats/$CHAT_ID?limit=20" \
  -H "X-Api-Key: $DVAARIK_API_KEY"
```

### POST `/v2/chats/{chat_id}/messages`

Send the person's message and get the agent's reply in the response. Send an `Idempotency-Key`; the same key again returns the first reply with `duplicate: true` and is never charged twice.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:write` |
| Operation | `sendChatMessage` |
| Success | `201` `ChatExchange` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `chat_id` | path | uuid | yes |  |
| `Idempotency-Key` | header | string or null | no |  |

Request body: `ChatMessageCreate`.

#### `ChatMessageCreate`

One message from the person, as text.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `text` | string | yes | min length 1; max length 4096 |

#### `ChatExchange`

The person's message and the agent's reply to it. A reply that could not be written is `failed`, says why in `error`, and is charged nothing.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `duplicate` | boolean | no | default false |
| `message` | ChatMessageInfo | yes |  |
| `reply` | ChatMessageInfo | yes |  |

| Error | When |
| --- | --- |
| `401` | No API key was sent in X-Api-Key, or it is invalid or revoked. |
| `402` | The wallet cannot pay for one AI reply; top it up. |
| `403` | The API key lacks the scope this route needs, or its account or project is unavailable. |
| `404` | The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed. |
| `409` | A limit or the resource's state refuses this change; the sentence says which. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |
| `429` | The project's request limit or one of the chat reply limits is reached (per conversation an hour, per minute, per day); Retry-After says when to try again. |
| `503` | A bounded worker this request needs is busy; Retry-After says when to try again. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X POST "https://api.developers.dvaarik.com/v2/chats/$CHAT_ID/messages" \
  -H "X-Api-Key: $DVAARIK_API_KEY" \
  -H "Idempotency-Key: <unique per call attempt>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Do you open on Sunday?"
  }'
```

## Operations — account session

The same resource through the console door. These are what the web console calls; both doors return the same shapes.

### GET `/console/v2/projects/{project_id}/chats`

List conversations, the most recent message first, filtered by agent or channel.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleListChats` |
| Success | `200` `ChatPage` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `project_id` | path | uuid | yes |  |
| `agent_id` | query | uuid or null | no |  |
| `channel_id` | query | uuid or null | no |  |
| `limit` | query | integer | no |  |
| `offset` | query | integer | no |  |

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/chats?limit=20" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"
```

### POST `/console/v2/projects/{project_id}/chats`

Start a conversation with an agent. Give `variables` for the agent's job and your own `external_id` for the person; nothing is charged until a reply is written.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleStartChat` |
| Success | `201` `ChatInfo` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `project_id` | path | uuid | yes |  |

Request body: `ChatCreate`.

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `409` | The project or resource is in a state that refuses this change. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X POST "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/chats" \
  -H "Authorization: Bearer $DVAARIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent uuid>",
    "external_id": "customer-4821",
    "variables": {
      "company": "Northline Dental"
    }
  }'
```

### GET `/console/v2/projects/{project_id}/chats/{chat_id}`

Read a conversation with its newest messages, oldest first: each reply's status, cost, tokens and actions. Send `before` (from `next_before`) to read further back.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleGetChat` |
| Success | `200` `ChatDetail` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `chat_id` | path | uuid | yes |  |
| `project_id` | path | uuid | yes |  |
| `limit` | query | integer | no |  |
| `before` | query | date-time or null | no |  |

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/chats/$CHAT_ID?limit=20" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"
```

### POST `/console/v2/projects/{project_id}/chats/{chat_id}/messages`

Send the person's message and get the agent's reply in the response. Send an `Idempotency-Key`; the same key again returns the first reply with `duplicate: true` and is never charged twice.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleSendChatMessage` |
| Success | `201` `ChatExchange` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `chat_id` | path | uuid | yes |  |
| `project_id` | path | uuid | yes |  |
| `Idempotency-Key` | header | string or null | no |  |

Request body: `ChatMessageCreate`.

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `402` | The wallet cannot pay for one AI reply; top it up. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `409` | The project or resource is in a state that refuses this change. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |
| `429` | The project's request limit or one of the chat reply limits is reached (per conversation an hour, per minute, per day); Retry-After says when to try again. |
| `503` | This server is already writing its share of chat replies; Retry-After (2 s) says when to try again. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X POST "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $DVAARIK_TOKEN" \
  -H "Idempotency-Key: <unique per call attempt>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Do you open on Sunday?"
  }'
```

---

Source: https://developers.dvaarik.com/docs/api/chats · every page as one file: https://developers.dvaarik.com/docs.md