VoiceConsole AI - Voice AI Analytics

Documentation

Everything you need to integrate and operate VoiceConsole AI.

VoiceConsole AI is the command center for voice AI agencies. Monitor agents across Retell AI and Vapi from a single dashboard. Score every call with AI, track performance trends, and get real-time alerts when things go wrong.

The REST API gives you programmatic access to everything in the platform. Use it to build custom dashboards, trigger automations, or integrate with your existing tech stack.

Base URL: https://voiceconsole.ai/api

Quick Start

Go from zero to monitoring in under 5 minutes.

Create Your Account

Generate an API Key

Navigate to Settings > API Keys. Click 'Create Key' and save it somewhere safe. Keys start with viq_ and can't be retrieved after creation.

curl -X GET https://voiceconsole.ai/api/v1/agents \
  -H "Authorization: Bearer viq_your_api_key_here"

Connect Your Voice Platform

In Settings > Integrations, add your Retell AI or Vapi API key. VoiceConsole syncs agents and calls automatically every 4 hours.

Verify the Connection

Check that your agents appear in the Agents tab. VoiceConsole will begin scoring calls within minutes.

curl -X GET https://voiceconsole.ai/api/v1/agents \
  -H "Authorization: Bearer viq_your_api_key_here"

# Response:
# {
#   "agents": [
#     { "id": "agent_abc123", "name": "Sales Qualifier", "platform": "retell" }
#   ]
# }

Set Up Alerts

Configure webhook or Slack notifications for low-score calls, new calls, and daily summaries in Settings > Integrations.

Authentication

Secure your API requests with API keys or session tokens.

API Key Authentication

Pass your API key in the Authorization header as a Bearer token. API keys are scoped to your account and have the same permissions as your user.

curl -X GET https://voiceconsole.ai/api/v1/agents \
  -H "Authorization: Bearer viq_your_api_key_here" \
  -H "Content-Type: application/json"

Session Cookie Authentication

When using the dashboard, authentication is handled via the cp_session cookie. Sessions expire after 7 days. This method is used by the frontend and is not recommended for API integrations.

Keep your API keys secret

Never expose API keys in client-side code, public repositories, or logs. Rotate compromised keys immediately in Settings > API Keys.

API Reference

Complete reference for all REST API endpoints.

All endpoints return JSON. Successful responses return 200 with a data object. Errors return appropriate HTTP status codes with an error field.

Standard Response Envelope

// Success
{ "data": { ... }, "meta": { "page": 1, "perPage": 20, "total": 142 } }

// Error
{ "error": "Unauthorized" }

Common Query Parameters

Parameter	Type	Required	Description
page	integer	Optional	Page number (default: 1)
perPage	integer	Optional	Items per page (default: 20, max: 100)
sortBy	string	Optional	Field to sort by (e.g., startedAt, callScore)
sortOrder	string	Optional	asc or desc (default: desc)
dateFrom	ISO 8601	Optional	Filter from date (e.g., 2026-01-01T00:00:00Z)
dateTo	ISO 8601	Optional	Filter to date

Agents

Manage and monitor your voice AI agents.

GET

/api/v1/agents

List all agents for your account. Returns platform, call count, avg score, and status.

Auth

GET

/api/v1/agents/:agentId

Get detailed stats for a single agent including recent calls, score trend, and cost.

Auth

GET

/api/agents/stats

Aggregated agent performance metrics for the dashboard.

Auth

Response Fields

Parameter	Type	Required	Description
id	string	Required	Agent ID (Retell or Vapi format)
name	string	Required	Agent display name
platform	string	Required	retell or vapi
totalCalls	integer	Optional	Total calls handled
avgScore	number	Optional	Average call score (0-100)
avgDuration	number	Optional	Average call duration in seconds
totalCost	number	Optional	Total Retell/Vapi cost in USD

curl -X GET "https://voiceconsole.ai/api/v1/agents" \
  -H "Authorization: Bearer viq_your_api_key"

Calls

Access call history, transcripts, recordings, and scores.

GET

/api/calls

List calls with filtering by agent, date range, score, sentiment, and tags.

Auth

GET

/api/calls/:callId

Get full call detail including transcript, score breakdown, recording URL, and notes.

Auth

POST

/api/calls/:callId/notes

Add a note to a call.

Auth

POST

/api/calls/:callId/tags

Add or remove tags from a call.

Auth

GET

/api/calls/:callId/coaching

Get AI coaching insights for a specific call.

Auth

Query Parameters

Parameter	Type	Required	Description
agentId	string	Optional	Filter by agent ID
status	string	Optional	Filter by status (ended, error, in_progress)
minScore	integer	Optional	Minimum call score (0-100)
maxScore	integer	Optional	Maximum call score (0-100)
sentiment	string	Optional	Positive, Neutral, or Negative
platform	string	Optional	retell or vapi
direction	string	Optional	inbound or outbound
search	string	Optional	Search transcript and summary text

curl -X GET "https://voiceconsole.ai/api/calls?agentId=agent_abc123&minScore=70&dateFrom=2026-01-01" \
  -H "Authorization: Bearer viq_your_api_key"

Analytics

Aggregated performance metrics and trend data.

GET

/api/analytics

Dashboard KPIs: total calls, success rate, avg duration, sentiment, cost, avg score. Includes period-over-period trends.

Auth

GET

/api/v1/analytics

Public API variant of analytics with API key auth.

Auth

Query Parameters

Parameter	Type	Required	Description
range	string	Optional	Time range: 7d, 30d, 90d, or custom
dateFrom	ISO 8601	Optional	Custom range start (required if range=custom)
dateTo	ISO 8601	Optional	Custom range end
agentId	string	Optional	Filter by specific agent

Response Example

GET /api/analytics?range=30d

{
  "data": {
    "totalCalls": 3842,
    "successRate": 0.78,
    "avgScore": 74,
    "avgDuration": 156,
    "totalCost": 482.30,
    "sentimentBreakdown": {
      "positive": 2104,
      "neutral": 1245,
      "negative": 493
    },
    "trends": {
      "calls": { "current": 3842, "previous": 3210, "change": 19.7 },
      "score": { "current": 74, "previous": 71, "change": 4.2 },
      "cost":  { "current": 482.30, "previous": 410.15, "change": 17.6 }
    }
  },
  "meta": { "range": "30d", "from": "2026-01-13", "to": "2026-02-12" }
}

Webhooks

Receive real-time event notifications via HTTP POST.

VoiceConsole sends webhook events for key actions. Configure webhook URLs in Settings > Integrations. All payloads are signed with HMAC-SHA256 for verification.

Event Types

call.completedA call has ended and been scored

call.low_scoreA call scored below the alert threshold

call.newA new call has been synced

agent.status_changeAgent went online/offline

daily_summaryDaily digest with KPIs

Signature Verification

Every webhook includes three headers for verification. Always verify signatures before processing events.

Parameter	Type	Required	Description
X-VoiceConsole-Signature	string	Required	HMAC-SHA256 signature of the request body
X-VoiceConsole-Event	string	Required	Event type (e.g., call.completed)
X-VoiceConsole-Timestamp	ISO 8601	Required	Event timestamp for replay protection

Webhook Payload Example

{
  "event": "call.completed",
  "timestamp": "2026-02-12T14:30:00.000Z",
  "data": {
    "callId": "cl_xyz789",
    "agentId": "agent_abc123",
    "agentName": "Insurance Qualifier",
    "callScore": 87,
    "duration": 142,
    "sentiment": "Positive",
    "summary": "Caller booked appointment for Tuesday 3pm.",
    "cost": 0.12
  }
}

Integrations

Connect VoiceConsole with your voice platforms and tools.

Retell AI

Full Support

Bidirectional sync: agents, calls, transcripts, costs, recordings. Agent Builder can create/deploy agents directly.

Vapi

Full Support

Import assistants and calls. Real-time scoring, campaign management, and analytics.

ElevenLabs

Coming Soon

Conversational AI agent management. Agent Builder integration for create/deploy.

Slack

Full Support

Rich notifications in any channel: low scores, new calls, daily digests, campaign updates.

Discord

Full Support

Embed-rich notifications via Discord webhooks. Same event types as Slack.

Custom Webhooks

Full Support

HMAC-signed HTTP POST events to any URL. Supports retry with exponential backoff.

Stripe

Full Support

Subscription billing, usage metering, and automatic invoice generation.

Zapier

Coming Soon

Connect to 5,000+ apps with Zapier triggers and actions.

GoHighLevel

Coming Soon

Two-way CRM sync with contacts, opportunities, and call logging.

HubSpot

Coming Soon

Log calls as activities, sync leads, and trigger workflows.

Call Scoring

How VoiceConsole scores every call with AI.

Every call receives an AI-generated score from 0-100 based on four weighted categories. Scoring happens automatically within seconds of call completion.

Duration25%

Was the call long enough to be productive? Very short calls (<15s) and abandoned calls score low.

Sentiment25%

Overall tone of the conversation. Positive sentiment from both parties scores highest.

Resolution25%

Did the agent achieve the call objective? Booked appointments, answered questions, or resolved issues.

Engagement25%

Back-and-forth quality. Natural conversation flow with balanced turn-taking scores highest.

Score Ranges

90-100

Excellent

70-89

Good

50-69

Average

30-49

Below Avg

0-29

Poor

Rate Limits

API rate limiting and best practices.

API requests are rate limited per API key. Limits are generous for normal usage but protect against abuse.

Plan	Rate Limit	Burst
Free	60 req/min	10 req/sec
Pro ($49/mo)	300 req/min	30 req/sec
Agency ($149/mo)	1,000 req/min	100 req/sec

Rate Limit Headers

Parameter	Type	Required	Description
X-RateLimit-Limit	integer	Optional	Maximum requests per window
X-RateLimit-Remaining	integer	Optional	Requests remaining in current window
X-RateLimit-Reset	integer	Optional	Unix timestamp when the window resets
Retry-After	integer	Optional	Seconds to wait (only on 429 responses)

Error Codes

Standard HTTP error codes and troubleshooting.

Code	Meaning	Resolution
400	Bad Request	Check request body and parameters
401	Unauthorized	Invalid or missing API key / session
403	Forbidden	Insufficient permissions (admin-only endpoint)
404	Not Found	Resource doesn't exist or wrong ID
409	Conflict	Duplicate resource (e.g., duplicate lead phone)
422	Unprocessable	Validation failed. Check error.details array
429	Rate Limited	Too many requests. Wait and retry with backoff
500	Server Error	Internal error. Contact support if persistent

Error Response Example

{
  "error": "Validation failed",
  "details": [
    { "field": "phone", "message": "Invalid phone number format" },
    { "field": "email", "message": "Must be a valid email address" }
  ]
}

Best Practices

Recommendations for building reliable integrations.

API Best Practices

Exponential Backoff

On 429 or 5xx responses, retry with exponential backoff (1s, 2s, 4s, 8s). Check the Retry-After header for precise timing.

Cache Responses

Cache agent lists and analytics for 60-300 seconds. These change infrequently and caching reduces your rate limit usage.

Prefer Webhooks

Use webhooks for real-time updates instead of polling. Webhooks are instant and don't count against your rate limit.

Paginate Large Results

Always use pagination for calls and leads. Request only the fields you need. Default page size is 20, max is 100.

Webhook Best Practices

Verify Signatures

Always verify the X-VoiceConsole-Signature header using HMAC-SHA256 before processing any webhook. Never skip verification in production.

Respond 200 Fast

Return a 200 status within 5 seconds. Process the payload asynchronously if your handler takes longer. We retry on timeouts.

Implement Idempotency

Use the event ID and timestamp to deduplicate. We may retry delivery, so your handler should safely handle the same event twice.

Monitor Failures

Log failed webhook processing. After 5 consecutive failures, VoiceConsole will pause delivery and send you an alert email.

Troubleshooting

Issue	Solution
401 on every request	Verify your API key starts with viq_ and is passed as a Bearer token in the Authorization header.
Calls not syncing	Check Settings > Integrations for a green status. Re-enter your Retell/Vapi API key if the connection is stale.
Webhook not firing	Verify the endpoint URL is publicly accessible (not localhost). Check the integration is active and events are selected.
Scores showing as 0	Scoring requires a transcript. Very short calls (<5s) or calls that fail to connect won't produce a transcript to score.
Rate limited unexpectedly	Check X-RateLimit-Remaining header. If you're polling, switch to webhooks. Batch multiple reads into a single call where possible.
Magic link expired	Magic links expire in 15 minutes (24h for new accounts). Request a new one from the login page.

Need Help?

Our team is here to help you integrate. Join our Discord community or contact support directly.

Get Started Free Contact Support