Sign in

v1

latestOpenAPI 3.0.32026-07-267015229.9 KB
Conversations

Get Conversation

This endpoint returns a single conversation by its unique identifier.

get/v2/conversations/{conversation_id}

Query parameters

verboseboolean

Append verbose=true to the URL to receive additional event data in the response, including:

  • shutdown_reason: The reason why the conversation ended (e.g., "participant_left_timeout")
  • system.pal_joined: When the PAL joined the conversation (preferred for new integrations)
  • system.replica_joined: Legacy duplicate of system.pal_joined with an identical payload; still sent for backward compatibility
  • system.shutdown: When and why the conversation ended
  • application.transcription_ready: The end-of-call transcript. Each entry in properties.transcript has role (user / assistant / system / tool), content, timestamp (Unix epoch float, seconds), seconds_from_start, duration (seconds, float) and inference_id where available.
  • application.perception_analysis: The final visual analysis of the user that includes their appearance, behavior, emotional states, and screen activities
  • application.perception_unavailable: Emitted when perception is enabled but no visual analysis could be produced. properties.reason is one of no_vision_history, empty_summary, or summary_error (for example, the participant's camera was off, no frames were received, or the summary came back empty).
  • application.post_call_action_executed: The outcome of each post-call action Tavus ran after the call, with tool_name, status, and the action's request / response.

This is particularly useful as an alternative to using the callback_url parameter on the create conversation endpoint for retrieving detailed conversation data.

Response

conversation_idstring

A unique identifier for the conversation.

conversation_namestring

The name of the conversation.

conversation_urlstring

A direct link to join the conversation.

callback_urlstring

The url that will receive webhooks with updates of the conversation state.

statusstring

The status of the conversation.

face_idstring

A unique identifier for the face used to create this conversation

pal_idstring

A unique identifier for the PAL used to create this conversation

created_atstring

The date and time the conversation was created.

updated_atstring

The date and time of when the conversation was last updated.

Example response

{
  "conversation_id": "c123456",
  "conversation_name": "A Meeting with Hassaan",
  "conversation_url": "https://tavus.daily.co/c123456",
  "callback_url": "https://yourwebsite.com/webhook",
  "status": "active",
  "face_id": "r90bbd427f71",
  "pal_id": "pcb7a34da5fe"
}