Chat with a transcript (beta)

Chat is in beta. It is enabled per account. While it is in beta, the chat endpoints and their response shape may change or be removed within /v1 without notice.

Chat lets you ask a question about a transcription and get the answer in the same response: a summary, the action items, the decisions made, or anything else the recording covers. Each chat is saved against its transcription, so you can add follow-up prompts and read the conversation back later.

Before you start

Mint an API key (see Authentication) and export it:

export VOOK_API_KEY=vk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

You also need the id of a transcription whose transcript is ready (has_transcription is true). See Retrieve and export to find one. The Python examples use the requests package (pip install requests).

If chat is not enabled for your account, every chat endpoint returns 403 with the error code chat_not_enabled, reads included.

1. Open a chat

Send a title and your first prompt. Vook opens the chat, answers the prompt, and returns the whole chat.

Field	Type	Description
`title`	string	Short label for the chat, shown when you list chats. 1 to 255 characters.
`prompt`	string	Question or instruction to run against the transcript. At least 1 character.

curl -X POST "https://www.api.vook.ai/api/v1/transcriptions/$ID/chats" \
  -H "Authorization: Bearer $VOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Action items", "prompt": "List the action items decided in this meeting."}'

import os, requests

BASE = "https://www.api.vook.ai/api/v1"
headers = {"Authorization": f"Bearer {os.environ['VOOK_API_KEY']}"}

resp = requests.post(
    f"{BASE}/transcriptions/{transcription_id}/chats",
    headers=headers,
    json={
        "title": "Action items",
        "prompt": "List the action items decided in this meeting.",
    },
)
resp.raise_for_status()
chat = resp.json()
print(chat["messages"][-1]["content"])

A successful request returns 201 with the chat:

{
  "id": "5f2b8c1e-3a4d-4e6f-9b7a-1c2d3e4f5a6b",
  "transcription_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Action items",
  "created_at": "2024-01-15T10:30:00.000Z",
  "messages": [
    {
      "role": "user",
      "content": "List the action items decided in this meeting.",
      "created_at": "2024-01-15T10:30:00.000Z"
    },
    {
      "role": "assistant",
      "content": "1. Maria sends the revised budget by Friday.\n2. Tom books the venue for the offsite.",
      "created_at": "2024-01-15T10:30:12.000Z"
    }
  ],
  "turn_in_progress": false
}

Field	Type	Description
`id`	string	Chat ID. Use it to add prompts and to read the chat.
`transcription_id`	string	The transcription this chat runs against.
`title`	string	The label you gave the chat.
`created_at`	string	When the chat was created, as an ISO 8601 timestamp.
`messages`	object[]	Prompts and answers, oldest first.
`messages[].role`	string	Who wrote the message: `user` for a prompt, `assistant` for an answer.
`messages[].content`	string	Message text.
`messages[].created_at`	string	When the message was written, as an ISO 8601 timestamp.
`turn_in_progress`	boolean	`true` while a prompt on this chat is being answered.

Each request returns one complete answer as JSON. Answers can take a while on a long transcript, so give your HTTP client a generous timeout. The chat reads the transcript as it is when the chat opens. If you edit the transcript later, the existing chat keeps the earlier version: open a new chat to ask about the edited transcript.

2. Add a follow-up prompt

Send another prompt to the chat. The answer takes the earlier messages into account.

curl -X POST "https://www.api.vook.ai/api/v1/transcriptions/$ID/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $VOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Who owns each item?"}'

resp = requests.post(
    f"{BASE}/transcriptions/{transcription_id}/chats/{chat_id}/messages",
    headers=headers,
    json={"prompt": "Who owns each item?"},
)
resp.raise_for_status()
chat = resp.json()
print(chat["messages"][-1]["content"])

A successful request returns 201 with the full chat, your prompt and its answer appended:

{
  "id": "5f2b8c1e-3a4d-4e6f-9b7a-1c2d3e4f5a6b",
  "transcription_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Action items",
  "created_at": "2024-01-15T10:30:00.000Z",
  "messages": [
    {
      "role": "user",
      "content": "List the action items decided in this meeting.",
      "created_at": "2024-01-15T10:30:00.000Z"
    },
    {
      "role": "assistant",
      "content": "1. Maria sends the revised budget by Friday.\n2. Tom books the venue for the offsite.",
      "created_at": "2024-01-15T10:30:12.000Z"
    },
    {
      "role": "user",
      "content": "Who owns each item?",
      "created_at": "2024-01-15T10:32:00.000Z"
    },
    {
      "role": "assistant",
      "content": "Maria owns the revised budget. Tom owns the venue booking.",
      "created_at": "2024-01-15T10:32:08.000Z"
    }
  ],
  "turn_in_progress": false
}

The fields are the same as when you open a chat. A chat answers one prompt at a time. If you send a prompt while another one on the same chat is still being answered, the request returns 409 with the code chat_turn_in_progress. Wait until the chat’s turn_in_progress is false, then send it again.

3. List the chats of a transcription

Get every chat of a transcription. The list is not paginated. It does not include messages: read a chat to get them.

curl "https://www.api.vook.ai/api/v1/transcriptions/$ID/chats" \
  -H "Authorization: Bearer $VOOK_API_KEY"

resp = requests.get(f"{BASE}/transcriptions/{transcription_id}/chats", headers=headers)
resp.raise_for_status()
for c in resp.json()["data"]:
    print(c["id"], c["title"])

{
  "data": [
    {
      "id": "5f2b8c1e-3a4d-4e6f-9b7a-1c2d3e4f5a6b",
      "transcription_id": "123e4567-e89b-12d3-a456-426614174000",
      "title": "Action items",
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Field	Type	Description
`data`	object[]	Every chat of the transcription, including chats opened in the web app.
`data[].id`	string	Chat ID.
`data[].transcription_id`	string	The transcription this chat runs against.
`data[].title`	string	The label given to the chat.
`data[].created_at`	string	When the chat was created, as an ISO 8601 timestamp.

Chats belong to your account, so the list also includes chats opened in the Vook web app. You can read and continue them through the API. A chat opened in the web app may start with an assistant message. The list can also hold a chat titled Summary, created when you summarize the transcription.

4. Read a chat

Get a chat with all of its messages.

curl "https://www.api.vook.ai/api/v1/transcriptions/$ID/chats/$CHAT_ID" \
  -H "Authorization: Bearer $VOOK_API_KEY"

resp = requests.get(
    f"{BASE}/transcriptions/{transcription_id}/chats/{chat_id}", headers=headers
)
resp.raise_for_status()
for m in resp.json()["messages"]:
    print(m["role"], ":", m["content"])

{
  "id": "5f2b8c1e-3a4d-4e6f-9b7a-1c2d3e4f5a6b",
  "transcription_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Action items",
  "created_at": "2024-01-15T10:30:00.000Z",
  "messages": [
    {
      "role": "user",
      "content": "List the action items decided in this meeting.",
      "created_at": "2024-01-15T10:30:00.000Z"
    },
    {
      "role": "assistant",
      "content": "1. Maria sends the revised budget by Friday.\n2. Tom books the venue for the offsite.",
      "created_at": "2024-01-15T10:30:12.000Z"
    }
  ],
  "turn_in_progress": false
}

The fields are the same as when you open a chat.

If your connection drops

The answer keeps being produced after your connection closes, and it is saved to the chat. Recover it by reading the chat instead of sending the prompt again, which would ask the same question twice. On a follow-up prompt, you already have the chat id:

Read the chat every few seconds until turn_in_progress is false.
If your prompt and its answer are the last two messages, the turn completed.
If they are missing, the turn failed. Send the prompt again.

When opening a chat, the response never reached you, so you do not have its id yet:

List the chats of the transcription and find yours by title. Give each chat a distinct title so this match is reliable.
If it is there, read it until turn_in_progress is false.
If it does not appear after a while, opening the chat failed. Open it again.

Limits

Limit	Value	What happens above it
Prompts answered at once	1 per chat	`409 chat_turn_in_progress`. Wait for the current answer, then retry.
Chat length	2,000,000 tokens per chat	`409 chat_token_limit_reached`. Open a new chat to continue.

Every message counts toward the chat length, including messages from the web app. The limit is checked before a prompt is answered, so a prompt accepted just under the limit still gets its answer.

Retention

A chat lives as long as its transcription. There is no endpoint to delete a single chat: when you delete the transcription, its chats are deleted with it. See Data retention.

Vook API

API Reference

Chat with a transcript (beta)

Before you start

1. Open a chat

2. Add a follow-up prompt

3. List the chats of a transcription

4. Read a chat

If your connection drops

Limits

Retention

Next steps

Errors and limits

API Reference

​Before you start

​1. Open a chat

​2. Add a follow-up prompt

​3. List the chats of a transcription

​4. Read a chat

​If your connection drops

​Limits

​Retention

​Next steps

Errors and limits

API Reference

Before you start

1. Open a chat

2. Add a follow-up prompt

3. List the chats of a transcription

4. Read a chat

If your connection drops

Limits

Retention

Next steps