Package Exports
- @oncallclerk/sdk
Readme
@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/sdkWorks 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: 'jane@acmecorp.co.uk',
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_contactEnable & 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
// List spreadsheets accessible by the agent's connected account
const sheets = await client.agents.listSheets(agent.id)
// List tabs in a spreadsheet
const tabs = await client.agents.listSheetTabs(agent.id, sheets[0].id)
// Get header suggestions for a tab
const headers = await client.agents.getSheetHeaders(agent.id, sheets[0].id, 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.
1. Open the dialer
The dialer is a single HTML file bundled with the SDK. Open it in any browser:
# macOS
open node_modules/@oncallclerk/sdk/src/dialer.html
# Windows
start node_modules/@oncallclerk/sdk/src/dialer.html
# Linux
xdg-open node_modules/@oncallclerk/sdk/src/dialer.html2. Enter your Agent ID
Paste the agent ID from client.agents.create() or client.agents.list() into the input field and click Call. Your browser will ask for microphone permission — grant it and you'll be connected to your agent in seconds.
3. Talk to your agent
The dialer shows a live transcript of the conversation in real time. Click Hang Up when you're done.
Pre-fill the Agent ID from a URL
Append ?agentId=YOUR_AGENT_ID to the dialer URL to skip the copy-paste step:
dialer.html?agentId=abc123Open the dialer programmatically
import { getDialerUrl } from '@oncallclerk/sdk'
const agent = await client.agents.create({ /* ... */ })
// Returns a path with the agentId pre-filled as a query param
console.log(getDialerUrl(agent.id))
// → node_modules/@oncallclerk/sdk/src/dialer.html?agentId=abc123Error 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