Skip to main content

​
What Are Conversations?

Conversations represent individual interactions between customers and AI agents. This includes phone calls, chat sessions, and other communication channels that our agents handle.

​
TODO: Conversation Data Model

Team Input Needed: We need to document the actual conversation structure in our database
Questions for the team:
  1. What fields does a conversation have? (id, agent_id, start_time, duration, etc.)
  2. How do we store conversation transcripts?
  3. What metadata do we capture? (caller_id, outcome, sentiment, etc.)
  4. How do we handle audio recordings? (storage, privacy, retention)
Example structure we need to document: 
// TODO: Replace with actual conversation schema
{
  id: "string",
  agent_id: "string",
  client_id: "string",
  start_time: "timestamp",
  end_time: "timestamp",
  status: "active" | "completed" | "failed", // TODO: Confirm statuses
  // TODO: Add all actual fields
}

​
TODO: Conversation States and Lifecycle

Questions for the team:
  1. What are the different conversation states? (ringing, active, completed, etc.)
  2. How do we handle failed or dropped calls?
  3. Can conversations be transferred between agents?
  4. How do we track conversation quality/success metrics?

​
TODO: Real-Time Monitoring

Questions for the team:
  1. Can we monitor active conversations in real-time?
  2. What real-time data is available? (transcript, audio, metrics)
  3. How do we handle live intervention/takeover by humans?
  4. What alerts/notifications are available for conversation issues?

​
TODO: Available Endpoints

Once we confirm what endpoints exist, we’ll document:
  • GET /v1/conversations - List conversations (with filtering)
  • GET /v1/conversations/{id} - Get conversation details
  • GET /v1/conversations/{id}/transcript - Get conversation transcript
  • GET /v1/conversations/{id}/audio - Get audio recording (if available)
  • GET /v1/conversations/active - List active conversations (if available)
Questions for the team:
  1. How can we filter conversations? (by agent, client, date range, outcome)
  2. What search capabilities exist? (transcript search, caller search)
  3. How do we handle pagination for large conversation lists?
  4. What sorting options are available?

​
TODO: Privacy and Compliance

Questions for the team:
  1. What data privacy rules apply to conversations?
  2. How long do we retain conversation data?
  3. Can customers request conversation deletion?
  4. What compliance requirements do we need to meet? (GDPR, HIPAA, etc.)

​
TODO: Integration with Voice Providers

Questions for the team:
  1. How do we sync conversation data from ElevenLabs?
  2. What about Retell.ai conversation data?
  3. How do we handle provider-specific metadata?
  4. Can we correlate conversations across different providers?