Get a chat

GET

chats

{chat_id}

Get Chat

curl --request GET \
  --url https://api.vocily.ai/v1/chats/{chat_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.vocily.ai/v1/chats/{chat_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vocily.ai/v1/chats/{chat_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vocily.ai/v1/chats/{chat_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.vocily.ai/v1/chats/{chat_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

{
  "detail": "Invalid API key",
  "code": "UNAUTHORIZED"
}

{
  "detail": {
    "code": "chat_not_found",
    "message": "Chat not found (a malformed id also returns this)."
  },
  "code": "NOT_FOUND"
}

{
  "detail": {
    "code": "validation_error",
    "message": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>",
        "type": "<string>"
      }
    ]
  },
  "code": "VALIDATION_ERROR"
}

{
  "code": "rate_limited"
}

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.

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.

Authorizations

Authorization

string

header

required

Your API key as a Bearer token, e.g. Authorization: Bearer vk_….

Path Parameters

chat_id

string

required

The chat's id, from GET /v1/chats.

Response

Successful Response

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.

string

required

The chat's id.

agent_id

string | null

required

Which agent handled it.

agent_name

string | null

required

The agent's name as it was at the time — snapshotted, so a later rename does not rewrite history.

agent_version

integer | null

required

Which version of the agent answered.

status

string

required

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

string | null

required

widget for a real end user on your site, dashboard for our own chat test button. null means unknown on older rows.

turn_count

integer

required

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

string<date-time>

required

When the chat started (UTC, ISO 8601).

ended_at

string<date-time> | null

required

When it ended. null while still open.

metadata

Metadata · object | null

required

Your own passthrough, unchanged.

variables

Variables · object | null

required

The chat's own variables. Only your custom bag.

cost

PublicChatCost · object | null

required

What the chat cost. Priced per assistant reply, not per minute.

Show child attributes

custom_analysis

Custom Analysis · object | null

required

Everything your analysis groups extracted, keyed by group then item.

transcript

Transcript · object | null

required

The conversation. Omitted (null) on the LIST unless you pass ?include=transcript.

dashboard_url

string

required

Deep link to this chat in the Vocily dashboard.

Get Chat

curl --request GET \
  --url https://api.vocily.ai/v1/chats/{chat_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.vocily.ai/v1/chats/{chat_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vocily.ai/v1/chats/{chat_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vocily.ai/v1/chats/{chat_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.vocily.ai/v1/chats/{chat_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

{
  "detail": "Invalid API key",
  "code": "UNAUTHORIZED"
}

{
  "detail": {
    "code": "chat_not_found",
    "message": "Chat not found (a malformed id also returns this)."
  },
  "code": "NOT_FOUND"
}

{
  "detail": {
    "code": "validation_error",
    "message": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>",
        "type": "<string>"
      }
    ]
  },
  "code": "VALIDATION_ERROR"
}

{
  "code": "rate_limited"
}

Calls

Chats

Phone Numbers

Knowledge Bases

Files

Agents

Speech

Catalogues

Integrations

Custom Analysis

Memory

Widget

Webhooks

Authorizations

Path Parameters

Response