DocumentationAPI ReferenceChangelog

Envocal API

API Reference API Changelog

Endpoints

Get a conversation GETList conversations of a tenant GET
Conversations

Get a conversation

Change a phone number PUT

Changes the number itself; its tenant and agent assignment stay the same.

List conversations of a tenant GET

Newest first, paged. Combine the filters as needed. Get one conversation for its transcript and summary.

GET
/v1/tenants/{tenantId}/conversations/{id}

Who talked to which agent and when, the transcript, the summary and how it ended.

Required permission: conversations:read

Authorization

Bearer
headerAuthorizationBearer <token>

Tenant API key (evk_…), created in Studio → Vault → API keys.

Path Parameters

tenantId*string

Tenant id, or current for the key's own tenant. Must be the key's tenant or one of its sub-tenants.

id*string

Conversation id.

Response Body

The conversation.

  1. response
  1. response
  2. …

A conversation: who talked to which agent, when, what was said and how it ended.

id*string

Conversation id.

tenantId*string

Tenant the conversation belongs to.

agentId?string

Agent that handled it; null if the agent was deleted since.

agentName?string

Agent name at the time of the conversation.

channel?string

phone, voice_chat (web voice, including text chats upgraded to voice) or text_chat (web text). Older data may contain text_voice_chat.

startUtc?string

Start time (UTC).

Formatdate-time
endUtc?string

End time (UTC).

Formatdate-time
duration?integer

Length in seconds.

Formatint32
endReason?string

Why the conversation ended (e.g. caller hung up, AI ended the call).

agentPhoneNumber?string

Number the caller dialled (phone), E.164.

userPhoneNumber?string

Caller's number (phone), E.164.

summary?string

Summary generated after the conversation, in the conversation's language.

result?string

Outcome label, if set.

topic?string

Short topic (1–2 words), generated after the conversation.

sentiment?string

Sentiment label, if set.

successCriteria?string

Success criteria evaluation, if set.

messages?integer

Number of messages in transcript.

Formatint32
transcript*array<>

What was said, in order: the visitor's or caller's messages and the agent's. The agent's tool calls are not included.

Example Request
curl -X GET 'https://api.envocal.ai/v1/tenants/string/conversations/string'
Example Response
{  "id": "string",  "tenantId": "string",  "agentId": "string",  "agentName": "string",  "channel": "string",  "startUtc": "2019-08-24T14:15:22Z",  "endUtc": "2019-08-24T14:15:22Z",  "duration": 0,  "endReason": "string",  "agentPhoneNumber": "string",  "userPhoneNumber": "string",  "summary": "string",  "result": "string",  "topic": "string",  "sentiment": "string",  "successCriteria": "string",  "messages": 0,  "transcript": [    {      "role": "user",      "text": "string",      "startTimeMs": 0    }  ]}
Example Request
curl -X GET 'https://api.envocal.ai/v1/tenants/string/conversations/string'
{
  "id": "string",
  "tenantId": "string",
  "agentId": "string",
  "agentName": "string",
  "channel": "string",
  "startUtc": "2019-08-24T14:15:22Z",
  "endUtc": "2019-08-24T14:15:22Z",
  "duration": 0,
  "endReason": "string",
  "agentPhoneNumber": "string",
  "userPhoneNumber": "string",
  "summary": "string",
  "result": "string",
  "topic": "string",
  "sentiment": "string",
  "successCriteria": "string",
  "messages": 0,
  "transcript": [
    {
      "role": "user",
      "text": "string",
      "startTimeMs": 0
    }
  ]
}