autoch.at Documentation

Appearance

Voice System API Reference ​

Complete API reference for the Voice system, including analytics and recording endpoints.

Base URL ​

All endpoints use the base URL:

https://your-domain.com/api

Authentication ​

All endpoints require authentication via Bearer token:

http
Authorization: Bearer <your-token>

Voice Analytics Endpoints ​

Get Voice Analytics Overview ​

Returns high-level voice analytics for the authenticated tenant.

Endpoint: GET /api/voice/analytics/overview

Query Parameters:

  • start_date (optional): Start date filter (ISO 8601 format)
  • end_date (optional): End date filter (ISO 8601 format)

Response (200 OK):

json
{
  "metrics": {
    "total_calls": 150,
    "completed_calls": 142,
    "incomplete_calls": 8,
    "avg_duration_seconds": 245.5,
    "recording_availability_rate": 0.95
  }
}

Example Request:

bash
curl -X GET "https://your-domain.com/api/voice/analytics/overview?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer <your-token>"

Get Detailed Voice Analytics ​

Returns detailed aggregate metrics including tool calls and sentiment.

Endpoint: GET /api/voice/analytics/detailed

Query Parameters:

  • start_date (optional): Start date filter (ISO 8601 format)
  • end_date (optional): End date filter (ISO 8601 format)

Response (200 OK):

json
{
  "metrics": {
    "total_calls": 150,
    "completed_calls": 142,
    "incomplete_calls": 8,
    "avg_duration_seconds": 245.5,
    "recording_availability_rate": 0.95,
    "tool_call_success_rate": 0.92,
    "sentiment_distribution": {
      "positive": 85,
      "neutral": 45,
      "negative": 20
    }
  }
}

Example Request:

bash
curl -X GET "https://your-domain.com/api/voice/analytics/detailed?start_date=2025-01-01" \
  -H "Authorization: Bearer <your-token>"

Get Voice Analytics Timeline ​

Returns time-series metrics for voice conversations.

Endpoint: GET /api/voice/analytics/timeline

Query Parameters:

  • start_date (optional): Start date filter (ISO 8601 format)
  • end_date (optional): End date filter (ISO 8601 format)
  • bucket (optional): Time bucket - day (default) or hour

Response (200 OK):

json
{
  "timeline": [
    {
      "bucket": "2025-01-15T00:00:00Z",
      "call_count": 12,
      "avg_duration_seconds": 230.5
    },
    {
      "bucket": "2025-01-16T00:00:00Z",
      "call_count": 15,
      "avg_duration_seconds": 245.2
    }
  ]
}

Example Request:

bash
curl -X GET "https://your-domain.com/api/voice/analytics/timeline?bucket=hour&start_date=2025-01-15" \
  -H "Authorization: Bearer <your-token>"

Recording Endpoints ​

Get Call Recording ​

Returns recording metadata for a specific conversation.

Endpoint: GET /api/voice/recordings/:conversationId

Path Parameters:

  • conversationId: Conversation ID (UUID)

Response (200 OK):

json
{
  "recording": {
    "id": "recording-123",
    "urls": [
      "https://telnyx.com/recordings/recording-123.mp3"
    ],
    "duration_seconds": 245,
    "available": true,
    "started_at": "2025-01-15T10:00:00Z",
    "ended_at": "2025-01-15T10:04:05Z"
  }
}

Response (404 Not Found) - No recording available:

json
{
  "recording": {
    "id": null,
    "urls": null,
    "duration_seconds": null,
    "available": false,
    "started_at": "2025-01-15T10:00:00Z",
    "ended_at": "2025-01-15T10:04:05Z"
  }
}

Example Request:

bash
curl -X GET "https://your-domain.com/api/voice/recordings/conv-123" \
  -H "Authorization: Bearer <your-token>"

Conversation Endpoints ​

Voice conversations use the standard conversation endpoints. See Conversations API for details.

List Conversations (Voice) ​

Endpoint: GET /api/conversations?channel=voice

Query Parameters:

  • channel: Set to voice to filter voice conversations
  • status: Filter by status (active, completed, failed)
  • limit: Number of results (default: 50)
  • offset: Pagination offset (default: 0)

Response: Standard conversation list response

Get Conversation Messages (Voice Transcript) ​

Endpoint: GET /api/conversations/:id/messages

Returns the transcript of a voice conversation as messages.

Path Parameters:

  • id: Conversation ID (UUID)

Response: Array of messages (user and assistant transcripts)

Webhook Events ​

The system receives webhooks from Telnyx for voice events. These are handled automatically and don't require direct API interaction.

Webhook Endpoints ​

  • Telnyx Voice Webhooks: POST /api/webhooks/telnyx/voice
  • Telnyx Conversational AI Webhooks: POST /api/webhooks/telnyx/voice/conversational-ai

Webhook Event Types ​

  • call.initiated: Call started
  • call.answered: Call answered
  • call.hangup: Call ended
  • call.recording.saved: Recording saved
  • ai.assistant.transcript: Transcript event (partial/final)
  • ai.assistant.tool_call: Tool call event
  • ai.assistant.response: AI response event
  • ai.assistant.ended: AI session ended

Note: Webhooks are automatically configured and don't require manual setup.

Error Responses ​

All endpoints may return standard error responses:

401 Unauthorized:

json
{
  "error": "Missing tenant context for analytics request"
}

404 Not Found:

json
{
  "error": "Conversation not found"
}

500 Internal Server Error:

json
{
  "error": "Internal server error"
}

Rate Limiting ​

API endpoints are rate-limited:

  • Analytics Endpoints: 60 requests per minute
  • Recording Endpoints: 30 requests per minute
  • Conversation Endpoints: Standard conversation rate limits

Rate limit headers:

http
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1640000000

Caching ​

Analytics endpoints use caching:

  • Overview: 60 second cache TTL
  • Detailed: 60 second cache TTL
  • Timeline: 5 minute cache TTL

Cache headers:

http
Cache-Control: public, max-age=60
ETag: "abc123"

Examples ​

Get Voice Analytics for Last 30 Days ​

bash
# Calculate dates
START_DATE=$(date -u -d '30 days ago' +%Y-%m-%d)
END_DATE=$(date -u +%Y-%m-%d)

# Request analytics
curl -X GET "https://your-domain.com/api/voice/analytics/overview?start_date=${START_DATE}&end_date=${END_DATE}" \
  -H "Authorization: Bearer <your-token>"

Get Recording for Conversation ​

bash
CONVERSATION_ID="conv-123"

curl -X GET "https://your-domain.com/api/voice/recordings/${CONVERSATION_ID}" \
  -H "Authorization: Bearer <your-token>"

Get Voice Conversations ​

bash
curl -X GET "https://your-domain.com/api/conversations?channel=voice&limit=20" \
  -H "Authorization: Bearer <your-token>"

Next Steps ​

autoch.at Documentation

Copyright © 2024 autoch.at