Quick start

Backend middleware, one React hook, and your agents are making calls.

1. Install

npm install @dialer/node

npm install @dialer/react

2. Add the middleware

The middleware mints short-lived agent tokens. It sits on any route your frontend can reach.

import { DialerAuth } from '@dialer/node'

app.use(DialerAuth({
  apiKey: process.env.DIALER_API_KEY,
  getAgentId: (req) => req.user.id
}))

This creates a POST /dialer-auth endpoint that the React SDK calls automatically.

3. Render the agent UI

import { useDialer, CallCard } from '@dialer/react'

export default function Agent() {
  const { activeCall, endCall, status } =
    useDialer({ authUrl: '/dialer-auth' })

  if (!activeCall) {
    return <div>Waiting for a call...</div>
  }

  return <CallCard call={activeCall} onEnd={endCall} />
}

Start a campaign from the dashboard. When a contact answers, the call appears in your agent UI.

Authentication

Two token types, two use cases.

All API requests use the Authorization: Bearer <token> header. Rate limit: 100 req/min.

Backend setup

The @dialer/node middleware handles agent token minting. It's the only backend code you write.

DialerAuth options

Manual token minting

If you don't use the middleware, mint tokens directly:

const res = await fetch('https://api.withdialer.com/api/auth/token', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    member_id: 'mem_abc123',
    expires_in: 3600
  })
})

Frontend (React)

The @dialer/react SDK connects your UI to live calls via SSE. One hook gives you everything.

useDialer

The main hook. Connects to the SSE stream, manages call state, and exposes actions.

const {
  status,          // 'connecting' | 'available' | 'on_call' | 'away'
  activeCall,      // Call object or null
  phase,           // 'idle' | 'active' | 'post_call'
  summary,         // AI summary after call ends
  endedCallId,     // ID of the just-ended call (for disposition)
  endCall,         // () => void
  submitDisposition, // (disposition, notes?) => void
  setAvailable,    // () => void
  setAway,         // () => void
} = useDialer({ authUrl: '/dialer-auth' })

Components

Pre-built UI components. Fully stylable via className.

Full example

import {
  useDialer, CallCard, LiveTranscript,
  DispositionPicker, AgentStatus
} from '@dialer/react'

export default function Agent() {
  const {
    activeCall, endCall, status, setAvailable, setAway,
    summary, phase, endedCallId, submitDisposition
  } = useDialer({ authUrl: '/dialer-auth' })

  return (
    <div>
      <AgentStatus
        status={status}
        onAvailable={setAvailable}
        onAway={setAway}
      />

      {phase === 'post_call' && endedCallId && (
        <DispositionPicker
          onSubmit={(d, notes) => submitDisposition(d, notes)}
          summaryText={summary?.text}
          suggestedDisposition={summary?.suggested_disposition}
        />
      )}

      {activeCall && (
        <CallCard call={activeCall} onEnd={endCall}>
          <LiveTranscript callId={activeCall.id} />
        </CallCard>
      )}

      {!activeCall && status === 'available' && (
        <div>Waiting for a call...</div>
      )}
    </div>
  )
}

Events (SSE)

All state changes stream over Server-Sent Events. No webhooks, no public URLs. Works on localhost.

Endpoints

Reconnect with Last-Event-Id header to resume from where you left off. Heartbeat every 30s.

Event types

Event shape

{
  "id": "evt_01hx...",
  "type": "call.connected",
  "data": {
    "call_id": "call_abc",
    "campaign_id": "camp_xyz",
    "contact": {
      "name": "Sarah Chen",
      "phone": "+14155550182",
      "metadata": { "deal_stage": "Negotiation" }
    }
  },
  "timestamp": "2026-03-31T14:22:08Z"
}

Campaigns

Create a campaign, upload contacts, assign agents, start dialing.

Campaign states

Calls

Dispositions

answered callback_requested not_interested converted voicemail no_answer other

Contacts

Contacts are uploaded via POST /api/campaigns/:id/contacts. Phone numbers must be E.164 format (+14155550182).

Agents

Agent statuses

connecting available on_call away offline

DNC (Do Not Call)

DNC is checked before every dial. Adding a number blocks it immediately across all campaigns.

SMS

SMS follow-ups are sent automatically on voicemail or no-answer (when enabled on the campaign). You can also send manually.