> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vocily.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get a chat
> Fetch one text conversation, transcript included.
A chat has no phone numbers, no duration and no recording - it is priced per assistant reply, so
it carries `turn_count` and a `rate_per_reply` cost instead. Voice conversations live at
[`/v1/calls`](/developers/calls/get).
`transcript` is the stored conversation as `{ "turns": [...] }`, oldest turn first, each turn a
`role` and a `text`. A conversation with no turns stores `{}`, with no `turns` key, so check for
the key before walking it.
## OpenAPI
````yaml developers/openapi.json GET /v1/chats/{chat_id}
openapi: 3.1.0
info:
title: Vocily API
description: >-
Public REST API for Vocily. Build and configure an agent, publish a version
and put it live, place outbound calls, and read back calls, chats and what
the agent remembered. Authenticate with a workspace API key as a Bearer
token.
Some things stay in the dashboard, by design: creating an API key, buying or
connecting a phone number, setting an agent's webhook URL, connecting
WhatsApp and its templates, building HTTP tools, and running batch
campaigns.
version: v1
servers:
- url: https://api.vocily.ai
description: Production
security: []
paths:
/v1/chats/{chat_id}:
get:
tags:
- chats
summary: Get Chat
description: >-
Fetch one chat by id, transcript always included.
A call's id here is a 404: calls and chats are separate resources, and a
call is read from
`GET /v1/calls/{id}`.
operationId: get_chat_v1_chats__chat_id__get
parameters:
- name: chat_id
in: path
required: true
schema:
type: string
title: Chat Id
description: The chat's id, from `GET /v1/chats`.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PublicChatRead'
example:
id: 00000002-0000-4000-8000-000000000002
agent_id: 00000003-0000-4000-8000-000000000003
agent_name: Acme Support
agent_version: 4
status: completed
origin: widget
turn_count: 6
created_at: '2026-09-17T09:20:11Z'
ended_at: '2026-09-17T09:24:48Z'
metadata:
order_id: '88431'
variables:
plan: pro
cost:
currency: USD
total: 0.012
rate_per_reply: 0.002
custom_analysis:
Default Analysis:
User Sentiment: positive
Call Outcome: resolved
transcript:
turns:
- role: user
content: where is order 88431
- role: assistant
content: It shipped this morning — arriving Thursday.
dashboard_url: >-
https://app.vocily.ai/chats?execution_id=00000002-0000-4000-8000-000000000002
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
detail: Invalid API key
code: UNAUTHORIZED
'404':
description: Chat not found (a malformed id also returns this).
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
detail:
code: chat_not_found
message: Chat not found (a malformed id also returns this).
code: NOT_FOUND
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Rate limit exceeded — honor `Retry-After`.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
code: rate_limited
security:
- bearerAuth: []
components:
schemas:
PublicChatRead:
properties:
id:
type: string
title: Id
description: The chat's id.
agent_id:
anyOf:
- type: string
- type: 'null'
title: Agent Id
description: Which agent handled it.
agent_name:
anyOf:
- type: string
- type: 'null'
title: Agent Name
description: >-
The agent's name as it was at the time — snapshotted, so a later
rename does not rewrite history.
agent_version:
anyOf:
- type: integer
- type: 'null'
title: Agent Version
description: Which version of the agent answered.
status:
type: string
title: Status
description: >-
Where the chat got to — `started`, `in_progress`, or `completed`. A
chat has no failure state: it cannot ring, be declined or reach
voicemail. `completed` means **no longer active**, which includes a
visitor simply closing the tab.
origin:
anyOf:
- type: string
- type: 'null'
title: Origin
description: >-
`widget` for a real end user on your site, `dashboard` for our own
chat test button. `null` means unknown on older rows.
turn_count:
type: integer
title: Turn Count
description: >-
Assistant replies in the session. **This is the billing unit for
text** — voice bills on `duration_seconds`, which is always `null`
here — so it is published rather than left for you to count out of
the transcript and get a different answer than the invoice.
created_at:
type: string
format: date-time
title: Created At
description: When the chat started (UTC, ISO 8601).
ended_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Ended At
description: When it ended. `null` while still open.
metadata:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Metadata
description: Your own passthrough, unchanged.
variables:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Variables
description: The chat's own variables. Only your `custom` bag.
cost:
anyOf:
- $ref: '#/components/schemas/PublicChatCost'
- type: 'null'
description: What the chat cost. Priced per assistant reply, not per minute.
custom_analysis:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Custom Analysis
description: Everything your analysis groups extracted, keyed by group then item.
transcript:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Transcript
description: >-
The conversation. Omitted (`null`) on the LIST unless you pass
`?include=transcript`.
dashboard_url:
type: string
title: Dashboard Url
description: Deep link to this chat in the Vocily dashboard.
type: object
required:
- id
- agent_id
- agent_name
- agent_version
- status
- origin
- turn_count
- created_at
- ended_at
- metadata
- variables
- cost
- custom_analysis
- transcript
- dashboard_url
title: PublicChatRead
description: >-
One text conversation — a widget chat or a WhatsApp thread.
Separate from a call because a chat has no numbers, no duration, no
recording and no transfer, and is priced per assistant reply rather than
per minute.
Read-only. A chat begins when someone opens your widget or messages your
WhatsApp number, so there is no endpoint that starts one.
ApiError:
type: object
description: >-
Error envelope. `code` is derived from the HTTP status, so branch on it
for the CLASS of failure; the specific reason is `detail.code`. Every
public refusal carries both.
properties:
detail:
type: object
description: >-
The reason. `code` is the domain reason (e.g. `call_not_found`) and
`message` is a sentence safe to log. On a `422` it also carries
`errors[]`, one entry per rejected field — see
`HTTPValidationError`.
properties:
code:
type: string
example: call_not_found
message:
type: string
example: Call not found
required:
- code
- message
code:
type: string
description: Derived from the HTTP status, not the domain reason.
example: NOT_FOUND
HTTPValidationError:
type: object
title: HTTPValidationError
description: >-
A request the API could not read: a field of the wrong type, out of
range, missing, or one we do not accept. Same envelope as every other
error.
properties:
detail:
type: object
description: >-
What was wrong, as `code`, a one-line `message`, and every offending
field in `errors`.
required:
- code
- message
- errors
properties:
code:
type: string
enum:
- validation_error
message:
type: string
description: >-
The first problem in one line, with a count of the rest — e.g.
`model.temperature: Input should be less than or equal to 2 (and
1 more)`.
errors:
type: array
items:
$ref: '#/components/schemas/ValidationError'
description: >-
One entry per offending field. **Every problem is reported at
once**, not just the first, so a malformed body needs one round
trip to fix rather than one per field.
code:
type: string
enum:
- VALIDATION_ERROR
description: Derived from the HTTP status, as on every error.
PublicChatCost:
properties:
currency:
type: string
title: Currency
description: ISO currency code.
default: USD
total:
type: number
title: Total
description: What the chat cost, in `currency`. Dollars.
rate_per_reply:
anyOf:
- type: number
- type: 'null'
title: Rate Per Reply
description: >-
The per-reply rate it was billed at, in dollars per assistant reply
at the time of the chat. Text is priced per reply, not per minute.
type: object
required:
- total
title: PublicChatCost
description: >-
What a chat cost. Priced per assistant REPLY, which is why this carries
no `rate_per_min` — that is the voice unit and would be wrong here.
ValidationError:
type: object
title: ValidationError
required:
- field
- message
- type
properties:
field:
type: string
description: >-
The offending field as a path from the root of your request —
`voice.speed`, `variables[0].key`, or `query.limit` for a query
parameter. **This is the field to read.**
message:
type: string
description: What is wrong with it, in plain language.
type:
type: string
description: >-
A stable machine code for the kind of failure, e.g.
`extra_forbidden` for a field we do not accept, `missing` for a
required one, or `less_than_equal` for a number out of range. Switch
on this rather than on `message`, which may be reworded.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'Your API key as a Bearer token, e.g. `Authorization: Bearer vk_…`.'
````