Node / TypeScript

npm install @trysaperly/sdk

import { configure, connections, numbers } from '@trysaperly/sdk'

configure({ apiKey: process.env.SAPERLY_API_KEY! })

// 1. The connection is the handler — a hosted, in-network voice assistant.
const { data: connection, error: connErr } = await connections.create({
  body: {
    name: 'support',
    mode: 'hosted',
    instructions: 'You are a helpful assistant answering calls for Acme Inc.',
  },
})
if (connErr) throw new Error(connErr._tag)

// 2. Provision a number (here, in the 415 area code).
const { data: number } = await numbers.provision({ body: { areaCode: '415' } })
console.log(number!.phoneNumber) // → +1...

// 3. Bind the connection to the number.
await numbers.assignConnection({
  path: { id: number!.id },
  body: { connectionId: connection!.id },
})

import { configure } from '@trysaperly/sdk'

configure({ apiKey: process.env.SAPERLY_API_KEY! })

import { createSaperlyClient, numbers } from '@trysaperly/sdk'

const client = createSaperlyClient({ apiKey: 'sap_sk_live_...' })
const { data } = await numbers.list({ client })

await numbers.list()                          // no args
await numbers.get({ path: { id } })           // path params
await numbers.provision({ body: { areaCode: '415' } }) // request body
await consent.check({ query: { numberId, peerNumber } }) // query params

const { data: connection } = await connections.create({
  body: {
    name: 'support',
    mode: 'hosted',
    instructions: 'You are Acme support.',
    llm: { kind: 'managed', model: 'gpt-4o' },
  },
})

await connections.list()
await connections.get({ path: { id: connection!.id } })
await connections.update({ path: { id: connection!.id }, body: { instructions: 'Updated prompt.' } })
await connections.delete({ path: { id: connection!.id } })

const { data: number } = await numbers.provision({
  body: { areaCode: '415' }, // or { country: 'US', numberType: 'local' }
})

await numbers.list()
await numbers.get({ path: { id: number!.id } })
await numbers.assignConnection({ path: { id: number!.id }, body: { connectionId } })
await numbers.setCallerIdName({ path: { id: number!.id }, body: { callerIdName: 'ACME INC' } })
await numbers.release({ path: { id: number!.id } })

const { data: message } = await messaging.send({
  body: {
    fromNumberId: number!.id,
    to: '+15555550123',
    body: 'Hi from my agent 👋',
  },
})

await messaging.list()

const { data: call } = await voice.place({
  body: {
    fromNumberId: number!.id,
    to: '+14155551234',
    connectionId: connection!.id,
    instructions: 'Confirm the 3pm appointment.',
  },
})

await voice.list()
await voice.get({ path: { id: call!.id } })
await voice.transfer({ path: { id: call!.id }, body: { to: '+14155559999' } })
await voice.end({ path: { id: call!.id } }) // issues the carrier hangup; billing settles from the carrier event

// Artifacts once the call completes.
await voice.recording({ path: { id: call!.id } })
await voice.transcript({ path: { id: call!.id } })

await consent.record({
  body: {
    numberId: number!.id,
    peerNumber: '+15555550123',
    consentType: 'explicit_outbound',
    source: 'web-form',
  },
})

const { data } = await consent.check({
  query: { numberId: number!.id, peerNumber: '+15555550123' },
})
data!.hasConsent // → boolean

await consent.list()
await consent.revoke({ body: { numberId: number!.id, peerNumber: '+15555550123' } })

const { data: key } = await keys.mint({
  body: {
    name: 'voice-agent-prod',
    scopes: ['write'],
    numberScope: [number!.id], // optional allow-list
    spendLimitCents: 5000, // optional cap
    spendLimitResetPeriod: 'monthly',
  },
})

console.log(key!.token) // save it now — never re-emitted

await keys.list()
await keys.revoke({ path: { id: key!.id } })

const { data: quote } = await pricing.quote({ query: { country: 'US', numberType: 'local' } })
const { data: usage } = await usage.summary()

import { verifyWebhook } from '@trysaperly/sdk'

// Pass the RAW body string — the exact bytes, never a re-serialized object.
const rawBody = await req.text()
const result = await verifyWebhook(rawBody, process.env.SAPERLY_WEBHOOK_SECRET!, req.headers)

if (!result.valid) {
  return new Response(`Invalid: ${result.reason}`, { status: 400 })
}
// result.deliveryId — dedup on this to defeat replays.

import { agentBrain } from '@trysaperly/sdk/agent'

// Mount on any Web-`Request` runtime (Workers, Deno, Bun.serve, Next.js, Hono…).
export default {
  fetch: agentBrain({
    secret: process.env.SAPERLY_MANUAL_SECRET!, // the connection's manualSecret
    onInboundCall: ({ event }) => `Hi, you've reached ${event.to}. How can I help?`,
    onTurn: ({ event }) => `You said: ${event.userText}`, // a string → speak(...)
    onCallEnded: () => {}, // terminal — the directive is ignored
  }),
}

import { messaging } from '@trysaperly/sdk'

const { data, error } = await messaging.send({
  body: { fromNumberId, to, body: 'Hello' },
})

if (error) {
  switch (error._tag) {
    case 'RecipientOptedOut':
      // recipient opted out — capture fresh consent first (error.to)
      break
    case 'InsufficientFunds':
      // top up the balance — error.balanceCents / error.requestedCents
      break
    case 'SpendLimitExceeded':
      // this key's spend cap is spent — error.limitCents / error.priorSpendCents
      break
    case 'RateLimited':
      // back off — error.bucket
      break
    default:
      console.error(error._tag)
  }
} else {
  console.log(data!.id)
}

const { data } = await numbers.provision({
  body: { areaCode: '415' },
  throwOnError: true, // throws the typed error body on a non-2xx
})