List all conversations

cURL

curl --request GET \
  --url https://api.us-1.platform.polyai.app/v1/{account_id}/{project_id}/conversations \
  --header 'x-api-key: <api-key>'

{
  "conversations": [
    {
      "id": "CAabcd1234567abcdef1250065d4fc7389",
      "account_id": "<string>",
      "project_id": "<string>",
      "environment": "<string>",
      "started_at": "2023-11-07T05:31:56Z",
      "channel": "<string>",
      "in_progress": true,
      "variant_id": "<string>",
      "variant_name": "<string>",
      "from_number": "<string>",
      "to_number": "<string>",
      "num_turns": 123,
      "total_duration": 123,
      "polyai_duration": 123,
      "handoff": true,
      "handoff_reason": "<string>",
      "handoff_destination": "<string>",
      "num_silences": 123,
      "num_ood": 123,
      "metrics": {
        "CALL_DURATION": "30",
        "CALL_TURN": [
          "2022-02-18T12:09:05.12677Z",
          "2022-02-18T12:09:17.90602Z",
          "2022-02-18T12:09:29.57732Z",
          "2022-02-18T12:09:35.36996Z"
        ]
      },
      "state": {},
      "turns": [
        {
          "user_input": "<string>",
          "user_input_dtmf": "<string>",
          "user_input_datetime": "2023-11-07T05:31:56Z",
          "agent_response": "<string>",
          "agent_response_datetime": "2023-11-07T05:31:56Z",
          "latency": 123,
          "translated_user_input": "<string>",
          "english_agent_response": "<string>",
          "intents": [
            "<string>"
          ],
          "entities": [
            {}
          ],
          "is_ood": true,
          "is_silence": true
        }
      ]
    }
  ],
  "descriptions": {
    "conversations": {}
  },
  "next_offset": 123
}

GET

{account_id}

{project_id}

conversations

cURL

curl --request GET \
  --url https://api.us-1.platform.polyai.app/v1/{account_id}/{project_id}/conversations \
  --header 'x-api-key: <api-key>'

{
  "conversations": [
    {
      "id": "CAabcd1234567abcdef1250065d4fc7389",
      "account_id": "<string>",
      "project_id": "<string>",
      "environment": "<string>",
      "started_at": "2023-11-07T05:31:56Z",
      "channel": "<string>",
      "in_progress": true,
      "variant_id": "<string>",
      "variant_name": "<string>",
      "from_number": "<string>",
      "to_number": "<string>",
      "num_turns": 123,
      "total_duration": 123,
      "polyai_duration": 123,
      "handoff": true,
      "handoff_reason": "<string>",
      "handoff_destination": "<string>",
      "num_silences": 123,
      "num_ood": 123,
      "metrics": {
        "CALL_DURATION": "30",
        "CALL_TURN": [
          "2022-02-18T12:09:05.12677Z",
          "2022-02-18T12:09:17.90602Z",
          "2022-02-18T12:09:29.57732Z",
          "2022-02-18T12:09:35.36996Z"
        ]
      },
      "state": {},
      "turns": [
        {
          "user_input": "<string>",
          "user_input_dtmf": "<string>",
          "user_input_datetime": "2023-11-07T05:31:56Z",
          "agent_response": "<string>",
          "agent_response_datetime": "2023-11-07T05:31:56Z",
          "latency": 123,
          "translated_user_input": "<string>",
          "english_agent_response": "<string>",
          "intents": [
            "<string>"
          ],
          "entities": [
            {}
          ],
          "is_ood": true,
          "is_silence": true
        }
      ]
    }
  ],
  "descriptions": {
    "conversations": {}
  },
  "next_offset": 123
}

Authorizations

x-api-key

string

header

required

Path Parameters

account_id

string

required

Account ID.

project_id

string

required

Project ID.

Query Parameters

client_env

enum<string>

default:live

Client environment – sandbox, pre-release or live.

Available options:

sandbox,

pre-release,

live

start_time

string<date-time>

Start of the time range of the conversations to get, in ISO8601 format.

end_time

string<date-time>

End of the time range of the conversations to get, in ISO8601 format.

limit

integer

default:5

Max number of conversations to return per API call. If the result set is larger than this, it will be paginated.

Required range: 1 <= x <= 5000

offset

integer

default:0

Offset within the result set to fetch.

Required range: x >= 0

variant_id

string

Return all conversations under this variant_id. You may specify either variant_id or variant_name, not both.

variant_name

string

Return all conversations under this variant_name. You may specify either variant_id or variant_name. Encode spaces as "%20".

in_progress

boolean

If false, only return finished conversations. If true, only return conversations still in progress. If omitted, return all conversations.

Response

OK.

conversations

object[]

Array of conversations returned in ascending chronological order.

Show child attributes

conversations.id

string

required

Unique ID for this conversation.

Example:

"CAabcd1234567abcdef1250065d4fc7389"

conversations.account_id

string

required

ID of the customer account this conversation is under.

conversations.project_id

string

required

ID of the project this conversation is under.

conversations.environment

string

required

Deployment environment. Usually live, sandbox, or pre-release.

conversations.started_at

string<date-time>

required

Time when the conversation began, in ISO8601 format.

conversations.channel

string

required

Medium of the conversation, e.g. CHAT or VOICE-SIP.

conversations.in_progress

boolean

required

If true, the call is still in progress and its properties may change.

conversations.variant_id

string

ID of the variant this conversation is in.

conversations.variant_name

string

Name of the variant this conversation is in.

conversations.from_number

string

Caller’s phone number.

conversations.to_number

string

Phone number of the agent the caller was connected to.

conversations.num_turns

integer

Number of turns in the conversation.

conversations.total_duration

integer

Duration of the entire call, in seconds.

conversations.polyai_duration

integer

Duration of the portion handled by the PolyAI agent, in seconds.

conversations.handoff

boolean

Whether the agent handed the call off.

conversations.handoff_reason

string

Brief reason why the agent handed the call off.

conversations.handoff_destination

string

If multiple destinations exist, which one was used.

conversations.num_silences

integer

Number of silence turns.

conversations.num_ood

integer

Number of Out-of-Domain turns.

conversations.metrics

object

Mapping of metric name -> value(s).

Show child attributes

conversations.metrics.{key}

Example:

{
  "CALL_DURATION": "30",
  "CALL_TURN": [
    "2022-02-18T12:09:05.12677Z",
    "2022-02-18T12:09:17.90602Z",
    "2022-02-18T12:09:29.57732Z",
    "2022-02-18T12:09:35.36996Z"
  ]
}

conversations.state

object

Mapping of keys -> values written to the dialogue state.

conversations.turns

object[]

Ordered list of turns in the conversation.

Show child attributes

conversations.turns.user_input

string

Transcription of what the user spoke or typed. May be an empty string when no input is present.

conversations.turns.user_input_dtmf

string

DTMF digits captured for this turn. May be an empty string when none were entered.

conversations.turns.user_input_datetime

string<date-time>

Time when the agent received the user's input.

conversations.turns.agent_response

string

Transcription of the agent's response. May be an empty string when no response was produced.

conversations.turns.agent_response_datetime

string<date-time>

Time when the agent responded.

conversations.turns.latency

number

Agent latency for this turn in seconds.

conversations.turns.translated_user_input

string

User input translated into the agent's working language if translation is enabled. Empty string when not applicable.

conversations.turns.english_agent_response

string

Agent response in English when translation is enabled. Empty string when not applicable.

conversations.turns.intents

string[]

List of intents found in this turn's input.

conversations.turns.entities

object[]

List of entities found in this turn's input.

Show child attributes

conversations.turns.entities.{key}

conversations.turns.is_ood

boolean

Whether the turn is classified as Out of Domain (OOD).

conversations.turns.is_silence

boolean

Whether the turn is classified as a silence.

descriptions

object

Dictionary of response keys and their descriptions.

Show child attributes

descriptions.conversations

object

Dictionary of Conversation object keys and their descriptions.

next_offset

integer

If present, the result is paginated. Pass this value as offset in the next request to fetch the next page.

Overview

⌘I

API reference

Chat API

Conversations API v3 (current)

Handoff API

Concurrent Calls API

DNI API

External Events API

Conversations API v1 (legacy)

List all conversations

Authorizations

Path Parameters

Query Parameters

Response