Conversations

A conversation represents a single session between a user and a Voisnap agent. It includes the full transcript, audio recording, cost breakdown, and AI-generated analysis.

Base path: /api/v1/conversations

---

Conversation object

{
  "id": "conv_01HXDEF456GHI",
  "agentId": "agt_01HXK8Z3MNPQRS",
  "agentName": "Aria – Support Agent",
  "channel": "phone",
  "status": "completed",
  "direction": "inbound",
  "startedAt": "2025-06-16T14:22:00Z",
  "endedAt": "2025-06-16T14:25:47Z",
  "durationSeconds": 227,
  "caller": {
    "phoneNumber": "+14155550199",
    "country": "US"
  },
  "metadata": {
    "customerId": "cust_12345",
    "campaignId": null
  },
  "cost": {
    "totalUsd": 0.094,
    "llmUsd": 0.041,
    "ttsUsd": 0.028,
    "sttUsd": 0.018,
    "telephonyUsd": 0.007
  },
  "analysis": {
    "sentiment": "positive",
    "sentimentScore": 0.81,
    "intent": "billing_inquiry",
    "summary": "Customer called about a charge on their June invoice. Agent confirmed the charge was for the annual plan upgrade and offered to send a detailed breakdown by email. Customer was satisfied.",
    "customFields": {
      "resolution_status": "resolved",
      "issue_category": "billing"
    }
  },
  "recording": {
    "available": true,
    "durationSeconds": 227,
    "format": "mp3",
    "expiresAt": "2025-09-14T00:00:00Z"
  },
  "tags": ["billing", "resolved"],
  "outcome": "resolved"
}

---

List conversations

GET /api/v1/conversations

Query parameters:

Parameter	Type	Description
agentId	string	Filter by agent ID
channel	string	phone, webrtc, webchat, sms, whatsapp, telegram
status	string	in_progress, completed, failed, abandoned
direction	string	inbound or outbound
dateFrom	string	ISO 8601 start date (inclusive)
dateTo	string	ISO 8601 end date (inclusive)
outcome	string	Filter by outcome value
tags	string	Comma-separated tag filter
minDuration	integer	Minimum duration in seconds
page	integer	Page number
pageSize	integer	Items per page (max 100)

curl "https://api.voisnap.ai/api/v1/conversations?agentId=agt_01HXK8Z3MNPQRS&channel=phone&dateFrom=2025-06-01&dateTo=2025-06-30&status=completed" \
  -H "Authorization: Bearer vsnp_live_..."

conversations = client.conversations.list(
    agent_id="agt_01HXK8Z3MNPQRS",
    channel="phone",
    date_from="2025-06-01",
    date_to="2025-06-30",
    status="completed"
)
for conv in conversations:
    print(f"{conv.id}: {conv.duration_seconds}s — {conv.analysis.outcome}")

for await (const conv of client.conversations.list({
  agentId: 'agt_01HXK8Z3MNPQRS',
  channel: 'phone',
  dateFrom: '2025-06-01',
  dateTo: '2025-06-30',
  status: 'completed',
})) {
  console.log(`${conv.id}: ${conv.durationSeconds}s`);
}

---

Get a conversation

GET /api/v1/conversations/{conversationId}

curl https://api.voisnap.ai/api/v1/conversations/conv_01HXDEF456GHI \
  -H "Authorization: Bearer vsnp_live_..."

---

Get conversation messages

Returns the turn-by-turn message list without word-level timing (faster for display purposes).

GET /api/v1/conversations/{conversationId}/messages

curl https://api.voisnap.ai/api/v1/conversations/conv_01HXDEF456GHI/messages \
  -H "Authorization: Bearer vsnp_live_..."

Response:

{
  "conversationId": "conv_01HXDEF456GHI",
  "messages": [
    {
      "id": "msg_01",
      "role": "agent",
      "content": "Hello! Thanks for calling. How can I help you today?",
      "timestamp": "2025-06-16T14:22:01Z",
      "durationMs": 3200
    },
    {
      "id": "msg_02",
      "role": "user",
      "content": "Hi, I have a question about my last invoice.",
      "timestamp": "2025-06-16T14:22:06Z",
      "durationMs": 2800
    }
  ]
}

---

Get conversation costs

GET /api/v1/conversations/{conversationId}/costs

Response:

{
  "conversationId": "conv_01HXDEF456GHI",
  "currency": "USD",
  "total": 0.094,
  "breakdown": {
    "llm": {
      "provider": "openai",
      "model": "gpt-4o",
      "inputTokens": 1840,
      "outputTokens": 620,
      "cost": 0.041
    },
    "tts": {
      "provider": "elevenlabs",
      "characters": 2340,
      "cost": 0.028
    },
    "stt": {
      "provider": "deepgram",
      "audioSeconds": 108,
      "cost": 0.018
    },
    "telephony": {
      "provider": "twilio",
      "minutes": 4,
      "cost": 0.007
    }
  }
}

---

Get recording

GET /api/v1/conversations/{conversationId}/recording

Returns a pre-signed URL valid for 1 hour.

curl https://api.voisnap.ai/api/v1/conversations/conv_01HXDEF456GHI/recording \
  -H "Authorization: Bearer vsnp_live_..."

Response:

{
  "url": "https://storage.voisnap.ai/recordings/conv_01HXDEF456GHI.mp3?token=...",
  "format": "mp3",
  "durationSeconds": 227,
  "expiresAt": "2025-06-16T15:22:00Z"
}

---

Get audio stream (live)

For in-progress conversations, stream audio in real time via the VoiceHub SignalR connection (see Real-Time: VoiceHub).

---

Get transcript

Returns the full transcript with word-level timing and confidence scores.

GET /api/v1/conversations/{conversationId}/transcript

curl https://api.voisnap.ai/api/v1/conversations/conv_01HXDEF456GHI/transcript \
  -H "Authorization: Bearer vsnp_live_..."

Response:

{
  "conversationId": "conv_01HXDEF456GHI",
  "language": "en-US",
  "durationSeconds": 227,
  "turns": [
    {
      "id": "turn_01",
      "speaker": "agent",
      "text": "Hello! Thanks for calling. How can I help you today?",
      "startTime": 0.0,
      "endTime": 3.2,
      "confidence": 0.99,
      "words": [
        { "word": "Hello!", "startTime": 0.0, "endTime": 0.38, "confidence": 0.99 },
        { "word": "Thanks", "startTime": 0.5, "endTime": 0.82, "confidence": 0.98 },
        { "word": "for", "startTime": 0.83, "endTime": 0.95, "confidence": 0.99 },
        { "word": "calling.", "startTime": 0.96, "endTime": 1.34, "confidence": 0.99 }
      ]
    },
    {
      "id": "turn_02",
      "speaker": "user",
      "text": "Hi, I have a question about my last invoice.",
      "startTime": 3.8,
      "endTime": 6.4,
      "confidence": 0.96,
      "words": []
    }
  ]
}

---

Get analysis

GET /api/v1/conversations/{conversationId}/analysis

Response:

{
  "conversationId": "conv_01HXDEF456GHI",
  "completedAt": "2025-06-16T14:26:15Z",
  "sentiment": "positive",
  "sentimentScore": 0.81,
  "sentimentBreakdown": {
    "agent": 0.88,
    "user": 0.74
  },
  "intent": "billing_inquiry",
  "entities": [
    { "type": "invoice_id", "value": "INV-2025-0612" },
    { "type": "amount", "value": "$149.00" }
  ],
  "summary": "Customer called about a charge on their June invoice. Agent confirmed the charge was for the annual plan upgrade and offered to send a detailed breakdown by email. Customer was satisfied.",
  "topics": ["billing", "invoice", "annual plan"],
  "customFields": {
    "resolution_status": "resolved",
    "issue_category": "billing"
  },
  "callQualityScore": 4.2,
  "agentPerformanceNotes": "Agent correctly identified issue and provided clear explanation. Response time was within expected range."
}

---

Delete a conversation

Permanently deletes conversation data including transcript and recording.

DELETE /api/v1/conversations/{conversationId}

:::warning This action is irreversible. For compliance/audit purposes, consider archiving instead of deleting. :::

---

Add tags

POST /api/v1/conversations/{conversationId}/tags

curl -X POST https://api.voisnap.ai/api/v1/conversations/conv_01HXDEF456GHI/tags \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["billing", "vip-customer"] }'

---

Set outcome

PUT /api/v1/conversations/{conversationId}/outcome

curl -X PUT https://api.voisnap.ai/api/v1/conversations/conv_01HXDEF456GHI/outcome \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "resolved", "notes": "Billing question answered, customer satisfied." }'