Retrieving a Conversation

This endpoint allows you to retrieve detailed information about a specific conversation using its unique identifier.

Path Parameters

Parameter	Type	Description
conversationId	string (UUID)	The unique identifier of the conversation you want to retrieve

Response Structure

The response includes comprehensive details about the conversation, including:

Basic conversation details (ID, type, status)
Timing information (start time, end time)
Phone numbers and routing information
Post-call data and metadata
Dynamic variables used during the conversation

Example Request

Here’s an example of how to retrieve a conversation:

curl --request GET \
  --url https://www.oration.ai/api/v2/conversations/a7cc5115-fe5c-4a6a-3428-123b39ac8dd3 \
  --header 'x-api-key: your-api-key-here' \
  --header 'x-workspace-id: your-workspace-id-here'

Example Response

{
    "id": "a7cc5115-fe5c-4a6a-3428-123b39ac8dd3",
    "phoneId": null,
    "agentId": "3e3132c1-700e-40e8-9b10-9fbd538f28c2",
    "workspaceId": "c9baa2e8-a75a-4203-8f64-45f232430926",
    "wsUrl": null,
    "llmUrl": null,
    "callStartTime": "2025-01-21T08:55:01.709Z",
    "callEndTime": "2025-01-21T08:55:55.333Z",
    "userJoinTime": null,
    "userLeaveTime": "2025-01-21T08:55:55.333Z",
    "customerId": "f8a70f62-d1ce-4860-8f1d-dce3ccdbbaab",
    "toPhoneNumber": "+911234123412",
    "fromPhoneNumber": null,
    "conversationStatus": "completed",
    "telephonyType": "outbound",
    "telephonyStatus": null,
    "endReason": "user_did_not_answer",
    "recordingStatus": null,
    "postCallNotes": null,
    "postCallCategory1": null,
    "postCallCategory2": null,
    "postCallCategory3": null,
    "postCallMetadata": null,
    "conversationType": "telephony",
    "dynamicVariables": "{\"customerName\":\"Alice Smith\",\"productName\":\"Gold Membership\"}",
    "summary": "",
    "createdAt": "2025-01-21T08:55:00.398Z",
    "updatedAt": "2025-01-21T08:55:00.398Z"
}

Error Responses

404 Not Found

{
  "message": "Conversation not found or access denied",
  "code": "NOT_FOUND",
  "data": {
    "code": "NOT_FOUND",
    "httpStatus": 404,
    "path": "workspaces.conversation.getById",
    "zodError": null
  }
}

401 Unauthorized

{
  "message": "User Not Found",
  "code": "UNAUTHORIZED",
  "data": {
    "code": "UNAUTHORIZED",
    "httpStatus": 401,
    "path": "workspaces.conversation.getById",
    "zodError": null
  }
}

Tips for Using the Get Conversation Endpoint

Store Conversation IDs: Always store the conversation IDs returned from the create conversation endpoint if you plan to retrieve them later.
Error Handling: Implement proper error handling for cases where the conversation might not exist or the API key is invalid.
Timestamps: All timestamp fields are returned in ISO 8601 format with UTC timezone.

Authorizations

x-api-key

string

header

required

x-workspace-id

string

header

required

Path Parameters

conversationId

string<uuid>

required

Unique identifier of the conversation

Response

Successful response

string<uuid>

Unique identifier for the conversation

phoneId

string<uuid> | null

ID of the phone device used. Currently, not used.

agentId

string<uuid>

The ID of the AI agent

workspaceId

string<uuid>

The ID of the workspace

wsUrl

string | null

WebSocket URL for real-time communication. Currently, not used.

llmUrl

string | null

URL for the language model service. Currently, not used.

callStartTime

string<date-time>

The time when the call is triggered from Oration systems.

callEndTime

string<date-time> | null

The time when the call is closed by Oration systems.

userJoinTime

string<date-time> | null

The time when the user joined the conversation. It is the time user picks up the call in case of telephony conversations

userLeaveTime

string<date-time> | null

The time when the user left the conversation. It is the time user hangs up the call in case of telephony conversations

customerId

string<uuid>

Unique identifier for the customer

toPhoneNumber

string

The destination phone number

fromPhoneNumber

string | null

The source phone number. This number might be empty as it is not available for all telephony types.

conversationStatus

enum<string>

Current status of the conversation.

Available options:

queued,

dialing,

completed,

active,

failed

telephonyType

enum<string>

Type of telephony call (inbound/outbound)

Available options:

inbound,

outbound

telephonyStatus

string | null

Status of the telephony connection

endReason

enum<string>

Reason for conversation ending.

Available options:

user_did_not_answer,

user_hangup,

user_inactivity,

agent_hangup,

network_error,

max_duration_exceeded

recordingStatus

enum<string> | null

Status of call recording

Available options:

in_progress,

completed

postCallNotes

string | null

Notes added after the call

postCallCategory1

string | null

Primary categorization of the call

postCallCategory2

string | null

Secondary categorization of the call

postCallCategory3

string | null

Tertiary categorization of the call

postCallMetadata

object

Additional metadata collected after the call. This is usually used to store any analysis data that is computed after the call is finished.

conversationType

enum<string>

The type of conversation

Available options:

chat,

telephony,

web

dynamicVariables

string

JSON string containing dynamic variables for the conversation

summary

string

Summary of the conversation

createdAt

string<date-time>

The time when the conversation was created

updatedAt

string<date-time>

The time when the conversation was last updated

API Documentation

Conversations

Jobs

Customers

Get Conversation

Retrieving a Conversation

Path Parameters

Response Structure

Example Request

Example Response

Error Responses

404 Not Found

401 Unauthorized

Tips for Using the Get Conversation Endpoint

Authorizations

Path Parameters

Response

API Documentation

Conversations

Jobs

Customers

​Retrieving a Conversation

​Path Parameters

​Response Structure

​Example Request

​Example Response

​Error Responses

​404 Not Found

​401 Unauthorized

​Tips for Using the Get Conversation Endpoint

Authorizations

Path Parameters

Response

Retrieving a Conversation

Path Parameters

Response Structure

Example Request

Example Response

Error Responses

404 Not Found

401 Unauthorized

Tips for Using the Get Conversation Endpoint