@oncallclerk/sdk

Official TypeScript SDK for OnCallClerk — the programmable AI voice agent platform for building virtual receptionists, after-hours support lines, appointment booking agents, and inbound sales responders.

Build, deploy, and manage AI phone agents entirely through code. Each agent gets a real phone number, answers calls with a natural voice, and can book appointments, look up data, transfer calls, and more — all configurable via this SDK.

Resources:

• Developer docs — Guides, authentication, and getting started
• SDK reference — Full method-by-method documentation
• Dashboard — Create an account and generate your API key

Installation

npm install @oncallclerk/sdk

Works with Node.js 18+, Deno, and edge runtimes. Ships with full TypeScript definitions.

Authentication

Get your API key from the OnCallClerk dashboard. See the authentication guide for details.

import OnCallClerk from '@oncallclerk/sdk'

const client = new OnCallClerk({
  apiKey: process.env.ONCALLCLERK_API_KEY!,
})

| Option | Type | Required | Description | |---|---|---|---| | apiKey | string | Yes | Your OnCallClerk API key (starts with orag_) | | baseUrl | string | No | Override the API URL. Defaults to https://api.oncallclerk.com | | timeout | number | No | Request timeout in ms. Defaults to 30000 |

Quick Start

// List all your agents
const agents = await client.agents.list()

// Create a new agent
const agent = await client.agents.create({
  business_name: 'Acme Corp',
  agent_name: 'After-Hours Support',
  voice_id: 'KR1TkIhkSykEjI4B0DtH',    // Sarah — run client.voices.list() for options
  greeting: 'Thanks for calling Acme Corp.',
  system_prompt: 'You are a helpful support agent for Acme Corp.',
  escalation_policy: 'requested',          // 'never' | 'complex' | 'requested' | 'always'
  forwarding_number: '+14155559876',
  business_hours: {
    enabled: true,
    timezone: 'America/New_York',
    schedule: {
      monday: { open: '09:00', close: '17:00', enabled: true },
      tuesday: { open: '09:00', close: '17:00', enabled: true },
      // ...
    },
  },
  faq: [
    { question: 'What are your hours?', answer: 'We are open Monday–Friday, 9 AM to 5 PM Eastern.' },
  ],
})

// Update an agent
await client.agents.update(agent.id, { greeting: 'Hey! Thanks for calling.' })

// Delete an agent
await client.agents.delete(agent.id)

Phone Numbers

Search for available numbers and assign them to agents. See the phone number docs for international number requirements.

// Search for available phone numbers
const numbers = await client.phoneNumbers.search({
  country: 'US',
  areaCode: '415',
  pageSize: 5,
})

// Assign a number to an agent
await client.agents.assignPhone(agent.id, numbers[0].phoneNumber)

// International numbers may require regulatory bundles
const bundles = await client.phoneNumbers.getRegulatoryBundles('GB')
const approved = bundles.filter(b => b.status === 'twilio-approved')

// Create a regulatory bundle if needed
const bundle = await client.phoneNumbers.createRegulatoryBundle({
  isoCountryCode: 'GB',
  complianceType: 'business',
  complianceData: {
    businessName: 'Acme Corp Ltd',
    registrationNumber: '12345678',
    businessStreet: '10 Downing Street',
    businessCity: 'London',
    businessPostalCode: 'SW1A 2AA',
    businessCountry: 'GB',
    repFirstName: 'Jane',
    repLastName: 'Doe',
    repEmail: '[email protected]',
    repPhoneNumber: '+447700900000',
  },
})

Transcripts

Access call transcripts and conversation logs. See transcript docs for more on filtering and call types.

// List recent transcripts for an agent
const transcripts = await client.transcripts.list(agent.id, { limit: 10 })

// Filter by call type and outcome
const leads = await client.transcripts.list(agent.id, {
  type: 'Sales Inquiry',
  outcome: 'Lead Captured',
  limit: 25,
})

for (const t of transcripts) {
  console.log(`[${t.date}] ${t.caller} — ${t.outcome}`)
  console.log(`  Summary: ${t.summary}`)
  console.log(`  Duration: ${t.duration_minutes}m`)
}

Voices

Browse available AI voices. Each voice has a unique ID you pass to agents.create().

const voices = await client.voices.list()

for (const voice of voices) {
  console.log(`${voice.name} (${voice.accent}, ${voice.gender}) — ${voice.id}`)
}
// Kevin (American, Male) — f5HLTX707KIM4SzJYzSz
// Sarah (American, Female) — KR1TkIhkSykEjI4B0DtH
// Lucy (British, Female) — 4BWwbsA70lmV7RMG0Acs
// ...

Integrations

OnCallClerk agents can connect to external services — calendars, CRMs, email, spreadsheets, webhooks, and more. Use the SDK to discover what's available and configure them on your agents. See the full integrations guide for setup details.

Browse the integration catalog

const catalog = await client.integrations.catalog()

for (const integration of catalog.integrations) {
  console.log(`${integration.name} (${integration.auth_type})`)
  console.log(`  Functions: ${integration.functions.join(', ')}`)
}
// Google Calendar (oauth)
//   Functions: schedule_meeting, cancel_meeting, reschedule_meeting, check_availability
// Webhook (Custom API) (config)
//   Functions: fetch_data, send_data
// HubSpot CRM (config)
//   Functions: create_hubspot_contact, get_hubspot_contact

Enable & configure functions on an agent

// Enable Google Calendar on an agent
const config = await client.agents.enableFunction(agent.id, 'google_calendar', {
  enabled: true,
  params: { timezone: 'America/New_York' },
})

// List all enabled functions
const functions = await client.agents.listFunctions(agent.id)

// Disable a function
await client.agents.disableFunction(agent.id, 'google_calendar')

Check integration status

// List all integrations and their connection status
const { integrations, summary } = await client.agents.listIntegrations(agent.id)

console.log(`${summary.connected_integrations}/${summary.total_integrations} connected`)

for (const i of integrations) {
  console.log(`${i.metadata.display_name}: connected=${i.connected}, enabled=${i.enabled}`)
}

// Get a specific integration's detail
const detail = await client.agents.getIntegration(agent.id, 'google_calendar')
console.log(detail.integration.metadata)

// Update integration params (e.g., webhook URL)
await client.agents.updateIntegrationConfig(agent.id, 'fetch_data', {
  url: 'https://api.example.com/lookup',
  headers: { Authorization: 'Bearer ...' },
})

Google Sheets helpers

The Sheets integration uses the narrow drive.file OAuth scope, so the API cannot enumerate the user's Drive. Drive a Google Picker in your browser-based dashboard with a short-lived token from getSheetsPickerSession, then use the chosen spreadsheet_id with the other helpers.

// 1. Get a short-lived token for the Google Picker (browser-only step)
const session = await client.agents.getSheetsPickerSession(agent.id)
// hand session.access_token to the Google Picker JS SDK in your dashboard

// 2. Once the user has picked a spreadsheet, use its ID with the other helpers
const tabs = await client.agents.listSheetTabs(agent.id, pickedSpreadsheetId)
const headers = await client.agents.getSheetHeaders(agent.id, pickedSpreadsheetId, tabs[0].title)
console.log(headers[0].suggested_headers)

OAuth integrations

Some integrations (Google Calendar, Gmail, Google Sheets) require OAuth authorization. Start the flow with the SDK, then open the returned URL in a browser to complete it.

// Start Google Calendar OAuth
const { authUrl } = await client.oauth.startGoogleCalendar({
  agent_id: agent.id,
  user_id: 'your-user-id',  // from client.user.get()
})
// Open authUrl in a browser to complete authorization

// Google Sheets & Gmail work the same way
await client.oauth.startGoogleSheets({ agent_id: agent.id, user_id: 'your-user-id' })
await client.oauth.startGmail({ agent_id: agent.id, user_id: 'your-user-id' })

Webhooks — connect any external API

Webhooks let your agent call any HTTP endpoint during or after a call — no pre-built integration needed.

// Enable the fetch_data webhook on an agent
await client.agents.enableFunction(agent.id, 'fetch_data', {
  enabled: true,
  params: {
    url: 'https://api.example.com/crm/lookup',
    headers: { 'X-Api-Key': 'your-key' },
  },
})

// Check the webhook function schemas from the catalog
const catalog = await client.integrations.catalog()
console.log(catalog.function_schemas['fetch_data'])
// { description: 'GET data from configured webhook URL.',
//   parameters: { params: { type: 'object', required: false, ... } } }

Account & Subscription

// Get your user profile (also useful for retrieving your user_id for OAuth)
const profile = await client.user.get()
console.log(profile.email, profile.timezone)

// Check subscription and usage
const sub = await client.subscription.get()
console.log(`${sub.plan} — ${sub.usage.used}/${sub.usage.limit} calls used`)

Testing Your Agent

The SDK ships with a browser-based test dialer so you can talk to your agent through your microphone — no phone call or dashboard login needed.

Open the dialer programmatically (recommended)

The simplest way — works on Windows, macOS, and Linux. Opens your default browser with the agent ID pre-filled:

import { openDialer } from '@oncallclerk/sdk'

const agent = await client.agents.create({ /* ... */ })

openDialer(agent.id)
// Browser opens to: file:///.../@oncallclerk/sdk/src/dialer.html?agentId=...

If you'd rather just get the URL (e.g. to log it or open it yourself):

import { getDialerUrl, getDialerPath } from '@oncallclerk/sdk'

console.log(getDialerUrl(agent.id))   // file:// URL with agentId pre-filled
console.log(getDialerPath())          // absolute filesystem path

Open the dialer manually

The dialer is a single HTML file bundled with the SDK. From a shell:

# macOS
open "$(node -p "require('@oncallclerk/sdk').getDialerUrl('YOUR_AGENT_ID')")"

# Windows (PowerShell)
Start-Process (node -p "require('@oncallclerk/sdk').getDialerUrl('YOUR_AGENT_ID')")

# Linux
xdg-open "$(node -p "require('@oncallclerk/sdk').getDialerUrl('YOUR_AGENT_ID')")"

Talk to your agent

Your browser will ask for microphone permission — grant it and you'll be connected to your agent in seconds. The dialer shows a live transcript in real time. Click Hang Up when you're done.

Error Handling

All API errors throw OnCallClerkError with the HTTP status code attached.

import OnCallClerk, { OnCallClerkError } from '@oncallclerk/sdk'

try {
  await client.agents.delete('nonexistent-id')
} catch (err) {
  if (err instanceof OnCallClerkError) {
    console.error(err.message)  // 'Voice agent not found'
    console.error(err.status)   // 404
  }
}

API Reference

Full method-by-method documentation: oncallclerk.com/developers/sdk

Developer guides and authentication: oncallclerk.com/developers

License

MIT