Voice & Dialer

The Voice API exposes graph8’s parallel dialer — session management, real-time call records, transcripts, AI grading, agent rosters, and phone number pools. All endpoints sit on /api/v1/voice/dialer/* and require a server-side API key (Bearer + X-Org-Id).

30-second start

List the active dialer sessions for your org:

curl 'https://be.graph8.com/api/v1/voice/dialer/sessions?status=active&page_size=20' \
  -H "Authorization: Bearer $G8_API_KEY"

import { g8 } from '@graph8/sdk';
g8.init({ apiKey: process.env.G8_API_KEY! });

const { data } = await g8.voice.dialer.listSessions({ status: 'active' });
console.log(data); // → DialerSessionSummary[]

g8 voice-list-calls --limit 20

Ask your agent: “Show me today’s dialer sessions” → tool: g8_voice_list_dialer_sessions.

Quick reference

Endpoint	Method	Purpose
`/voice/dialer/sessions`	GET	List dialer sessions
`/voice/dialer/sessions`	POST	Create a new (paused) session
`/voice/dialer/sessions/{id}`	PATCH	Update session status (`paused`, `running`, `stopped`)
`/voice/dialer/sessions/{id}/resume`	POST	Resume + dial next batch (real calls)
`/voice/dialer/stats`	GET	Aggregated dialer analytics
`/voice/dialer/numbers`	GET	Phone numbers the org owns
`/voice/dialer/agents`	GET	Available voice agents
`/voice/dialer/missed-callbacks`	GET	Missed inbound callbacks / voicemails
`/voice/dialer/calls`	GET	List calls, filterable by contact / SDR / campaign / date
`/voice/dialer/calls/{room_name}/transcript`	GET	Full transcript of one call
`/voice/dialer/calls/{room_name}/grading`	GET	AI grading + talk-track feedback

Sessions

List sessions

GET /api/v1/voice/dialer/sessions?status=active&user_email=[email protected]&page=1&page_size=50

Filterable params: status, user_email, name, campaign_id, list_id, list_name, date_from, date_to, sort_by.

Response shape:

{
  "data": [
    {
      "session_id": "ses_abc123",
      "status": "active",
      "user_email": "[email protected]",
      "campaign_id": "cmp_q3_outbound",
      "from_phone": "+14155551234",
      "total_calls": 42,
      "created_at": "2026-05-25T14:30:00Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 50, "total_items": 12 }
}

Create a session

POST /api/v1/voice/dialer/sessions
Content-Type: application/json

{
  "list_id": 637,
  "agent_id": "ag_default",
  "from_number": "+14155551234",
  "campaign_id": "cmp_q3_outbound"
}

Session is created in PAUSED state. The SDR opens the dialer UI and calls POST /resume to start dialing.

Resume / pause / stop

POST /api/v1/voice/dialer/sessions/{session_id}/resume
# Body: { "max_contacts": 4 }

PATCH /api/v1/voice/dialer/sessions/{session_id}
# Body: { "status": "paused" }   // or "stopped"

Resume kicks off real outbound calls — credits accrue per minute of call audio.

Calls

List calls

GET /api/v1/voice/dialer/calls?contact_id=5028106&limit=25&page=1

Filterable: contact_id, user_email, campaign_id, date_from, date_to, limit, page.

Get call transcript

GET /api/v1/voice/dialer/calls/{room_name}/transcript

Returns status: "ready" with a transcript array of { speaker, text, timestamp } entries. Returns status: "empty" (with transcript: []) when the call ended but the transcript wasn’t flushed — rare, usually a sub-30-second hang-up.

Get AI grading

GET /api/v1/voice/dialer/calls/{room_name}/grading

Returns the AI-graded talk-track feedback for the call. Includes per-segment quality scores, talk/listen ratio, objections handled, next-best-action.

Stats, numbers, agents

GET /api/v1/voice/dialer/stats?aggregation=daily&date_from=2026-05-01
GET /api/v1/voice/dialer/numbers
GET /api/v1/voice/dialer/agents
GET /api/v1/voice/dialer/missed-callbacks?limit=50

stats supports aggregation=daily|total and the standard date filters. Returns dial count, connection rate, talk time, average call length, disposition breakdown.

Credit costs

Operation	Credits
Read endpoints (sessions, calls, transcripts, grading, stats)	Free
Outbound call audio	20 per minute
Booked meeting	20 per booking
Inbound callback (handled by AI receptionist)	20 per minute

The 5 rps rate limit applies to every read endpoint. Outbound dialer placements are throttled separately by the agent pool — see Rate Limits.

Errors

Status	Cause	Fix
`401`	Missing or invalid `Authorization: Bearer` header	Get a key
`402`	Out of credits (waterfall enrichment, AI generation, voice minutes)	Top up in Settings → Billing, or switch to Platform
`404`	Resource ID doesn’t exist	List first to verify the ID
`422`	Validation error in request body	Inspect `error.message` + `error.field` in the response
`429`	Rate limit (5 rps per org)	Backoff per `Retry-After` header. See Rate Limits
`5xx`	graph8 error	Retry with exponential backoff (5s → 30s → 120s)

The full error envelope shape: { "error": { "code": "...", "message": "...", "field": "...", "request_id": "..." } }. Include the request_id in any support ticket. See Errors for the canonical reference.