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 are under /api/v1/voice/dialer/.

List Dialer Sessions

GET /voice/dialer/sessions

Returns a paginated list of dialer sessions for the org.

Query Parameters

Example

curl "https://be.graph8.com/api/v1/voice/dialer/sessions?status=ACTIVE,PAUSED&page_size=20" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": {
    "sessions": [
      {
        "session_id": "...",
        "status": "PAUSED",
        "user_id": "...",
        "user_email": "...",
        "org_id": "...",
        "from_phone": "+1...",
        "campaign_id": null,
        "campaign_builder_campaign_id": null,
        "name": "Q3 Outbound",
        "session_metadata": { "list_id": "12345", "list_title": "..." },
        "total_calls": 0,
        "created_at": "...",
        "updated_at": "...",
        "contact_ids": []
      }
    ],
    "pagination": {
      "total_items": 1,
      "total_pages": 1,
      "current_page": 1,
      "page_size": 50
    }
  }
}

Create Dialer Session

POST /voice/dialer/sessions → 201 Created

Create a new dialer session. Sessions are created in PAUSED state. Call POST /voice/dialer/sessions/{session_id}/resume to begin dialing.

Request Body

Example

curl -X POST "https://be.graph8.com/api/v1/voice/dialer/sessions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 Outbound",
    "from_phone": "+15551234567",
    "list_id": "12345",
    "list_title": "Q3 Targets",
    "agent_id": "agent_uuid",
    "entity_type": "agent",
    "user_timezone": "America/New_York",
    "skip_voicemails": true
  }'

Response

{
  "data": {
    "session_id": "...",
    "status": "PAUSED",
    "name": "Q3 Outbound",
    "org_id": "...",
    "user_id": "...",
    "user_email": "...",
    "from_phone": "+15551234567",
    "session_metadata": { "list_id": "12345", "list_title": "Q3 Targets" },
    "total_calls": 0,
    "created_at": "...",
    "message": "..."
  }
}

Update Session Status

PATCH /voice/dialer/sessions/{session_id}/status

Pause, resume, or stop a dialer session.

Path Parameters

Request Body

Example

curl -X PATCH "https://be.graph8.com/api/v1/voice/dialer/sessions/ses_abc123/status" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "PAUSED" }'

Response

{
  "data": {
    "session_id": "ses_abc123",
    "status": "PAUSED",
    "name": "Q3 Outbound",
    "org_id": "...",
    "user_id": "...",
    "user_email": "...",
    "from_phone": "+15551234567",
    "session_metadata": { "list_id": "12345", "list_title": "Q3 Targets" },
    "total_calls": 0,
    "created_at": "...",
    "updated_at": "..."
  }
}

Resume Dialer Session

POST /voice/dialer/sessions/{session_id}/resume

Resume a paused session and dial the next batch of contacts. This endpoint places real outbound calls immediately.

Path Parameters

Request Body

Example

curl -X POST "https://be.graph8.com/api/v1/voice/dialer/sessions/ses_abc123/resume" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "max_contacts": 4 }'

Response

{
  "data": {
    "session_id": "ses_abc123",
    "status": "ACTIVE",
    "from_phone": "+15551234567",
    "session_metadata": { "list_id": "12345", "list_title": "Q3 Targets" },
    "total_calls": 0,
    "dialed_count": 4,
    "created_at": "...",
    "updated_at": "...",
    "message": "..."
  }
}

Dialer Stats

GET /voice/dialer/stats

Returns aggregated dialer analytics. Supports daily or total aggregation with optional date and session filters.

Query Parameters

Example

curl "https://be.graph8.com/api/v1/voice/dialer/stats?aggregation=DAILY&date_from=2026-05-01&date_to=2026-05-31" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": {
    "filters": {
      "session_id": null,
      "user_email": null,
      "org_id": "...",
      "date_from": "...",
      "date_to": "...",
      "aggregation": "DAILY"
    },
    "metrics": [
      {
        "date": "2026-05-26",
        "sdr_name": "...",
        "org_id": "...",
        "list_title": "...",
        "total_dials": 100,
        "total_connections": 30,
        "connection_rate": 0.3,
        "total_voicemails": 10,
        "voicemail_rate": 0.1,
        "talk_time_minutes": 45.5,
        "avg_call_duration_minutes": 1.5,
        "dispositions": { "booked": 2, "callback": 5 },
        "success_rate": 0.02,
        "unique_sessions": 1,
        "avg_calls_per_session": 100,
        "redial_count": 0,
        "redial_success_rate": null,
        "peak_calling_hour": 14,
        "total_callbacks": 0
      }
    ],
    "summary": {}
  }
}

List Phone Numbers

GET /voice/dialer/numbers

Returns the phone numbers provisioned for the org, with usage and health stats.

Query Parameters

Example

curl "https://be.graph8.com/api/v1/voice/dialer/numbers" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": {
    "numbers": [
      {
        "number": "+15551234",
        "inbound_type": "ai",
        "telephony_provider": "twilio",
        "calls_today": 5,
        "calls_7d": 40,
        "connect_rate_7d": 0.3,
        "is_valid": true,
        "daily_limit": 40,
        "assigned_to": "[email protected]",
        "created_at": "..."
      }
    ]
  }
}

List Missed Callbacks

GET /voice/dialer/missed-callbacks

Returns inbound calls that arrived while no SDR was available to answer.

Query Parameters

Example

curl "https://be.graph8.com/api/v1/voice/dialer/missed-callbacks?limit=50" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": {
    "missed_callbacks": [
      {
        "id": 1,
        "caller_phone": "...",
        "inbound_number": "...",
        "first_name": "...",
        "last_name": "...",
        "email": "...",
        "contact_id": 101,
        "parallel_session_id": "...",
        "created_at": "...",
        "call_duration": null,
        "is_callback": false
      }
    ],
    "count": 1
  }
}

Get Call Grading

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

Returns the AI-graded talk-track feedback for a call. If grading is still being computed, status will be "pending".

Path Parameters

Example

curl "https://be.graph8.com/api/v1/voice/dialer/calls/room_abc123/grading" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": {
    "room_name": "...",
    "status": "ready",
    "grading": {},
    "reviewed": false,
    "reviewed_at": null
  }
}

status is "pending" while grading is still being computed.

Get Call Transcript

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

Returns the full transcript for a call, along with the summary, disposition, and recording URL.

Path Parameters

Example

curl "https://be.graph8.com/api/v1/voice/dialer/calls/room_abc123/transcript" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": {
    "room_name": "...",
    "status": "ready",
    "transcript": [
      { "speaker": "SDR", "content": "...", "timestamp": "..." }
    ],
    "summary": "...",
    "disposition": "booked",
    "contact_id": "101",
    "call_duration": 90,
    "recording_url": "...",
    "parallel_session_id": "...",
    "created_at": "..."
  }
}

List Calls

GET /voice/dialer/calls

Returns calls matching the given filters. At least one of contact_id, user_email, or parallel_session_id is required.

Query Parameters

Example

curl "https://be.graph8.com/api/v1/voice/dialer/calls?contact_id=101&limit=20" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": {
    "contact_id": "101",
    "user_email": null,
    "parallel_session_id": null,
    "count": 1,
    "calls": [
      {
        "room_name": "...",
        "created_at": "...",
        "disposition": "booked",
        "summary": "...",
        "call_duration": 90,
        "recording_url": "...",
        "parallel_session_id": "...",
        "contact_id": "101",
        "from_": "+1...",
        "to": "+1...",
        "has_transcript": true
      }
    ]
  }
}

List Voice Agents

GET /voice/dialer/agents

Returns available voice agents and digital twins for the org.

Query Parameters

Example

curl "https://be.graph8.com/api/v1/voice/dialer/agents?entity_type=agent&agent_status=active" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": {
    "agents": [
      {
        "agent_id": "uuid",
        "agent_name": "...",
        "role": "SDR",
        "agent_status": "active",
        "entity_type": "agent",
        "description": "...",
        "phone": "+1...",
        "is_template": false
      }
    ],
    "total_count": 1
  }
}

Credit Costs

Errors

The full error envelope: { "error": { "code": "...", "message": "...", "field": "...", "request_id": "..." } }. Include request_id in any support ticket.