@seamlessvoip/node
v0.1.0
Published
The official Node.js library for SeamlessVoIP: place calls, send SMS, read call history and recordings, verify webhooks, and mint voice tokens for browser calling.
Maintainers
Readme
@seamlessvoip/node
The official Node.js library for SeamlessVoIP. Place calls, send SMS, read your call history and
recordings, receive signed webhooks, answer calls from your own server, and mint voice tokens
so your users can call straight from the browser with
@seamlessvoip/voice.
npm install @seamlessvoip/nodeNode 18 or later. No dependencies. Works with import and require, with TypeScript types included.
Quickstart (5 minutes)
1. Get an API key. Sign up at https://seamlessvoip.com/developers, or in SeamlessVoIP open
Integrations → API keys. Keys start with sv_live_. Keep the key on your server.
export SEAMLESSVOIP_API_KEY=sv_live_...2. Check it works.
import { SeamlessVoIP } from '@seamlessvoip/node';
const seamlessvoip = new SeamlessVoIP(); // reads SEAMLESSVOIP_API_KEY
const { account, key } = await seamlessvoip.account.get();
console.log(`Connected to ${account.name} as "${key.name}"`);3. Calling from your web app. Your server mints a short-lived token for the signed-in user;
the page hands it to @seamlessvoip/voice. The browser never sees your API key or a SIP password.
// server.js - npm install @seamlessvoip/node express
import express from 'express';
import { SeamlessVoIP } from '@seamlessvoip/node';
const seamlessvoip = new SeamlessVoIP();
const app = express();
// The page calls this to get (and later renew) its token.
app.get('/voice-token', async (req, res) => {
// Map your signed-in user to their agent (see seamlessvoip.agents.list()).
const { token, expires_at } = await seamlessvoip.voice.tokens.create({ agent_id: req.user.agentId });
res.json({ token, expires_at });
});
// Click-to-call: ring the agent's phone first, then dial the customer.
app.post('/call-customer', express.json(), async (req, res) => {
const call = await seamlessvoip.calls.create({ agent_id: req.user.agentId, to: req.body.phone });
res.json(call); // { status: 'DIALLING', pbx_call_id, agent, to }
});
app.listen(3000);// in the browser - npm install @seamlessvoip/voice
import { createVoiceClient } from '@seamlessvoip/voice';
const voice = createVoiceClient({
getAccessToken: () => fetch('/voice-token').then(r => r.json()).then(j => j.token),
});
voice.on('incoming', call => voice.answer(call.id));
await voice.connect();
voice.call('+254712345678');What you can do
| | |
|---|---|
| account.get() | The key and the account it acts on |
| calls.list(filters) · calls.iterate(filters) | Call history: direction, outcome, from, to, agent_id, phone |
| calls.get(id) | One call, by id or pbx_call_id |
| calls.live() | Calls up right now |
| calls.missed(filters) · calls.iterateMissed(filters) | Unanswered inbound calls; follow_up_status: 'PENDING' for those not called back |
| calls.create({ agent_id \| extension, to }) | Click-to-call |
| calls.recording(id) | { data, contentType, filename } WAV bytes |
| sms.send({ to, message }) · sms.get(id) | Texts through your SMS gateway |
| contacts.list({ q }) · contacts.iterate() · contacts.get(id) | Your address book |
| contacts.lookup({ phone } \| { email } \| { account }) | Match a caller, any phone format |
| callbacks.create({ agent_id \| extension, phone, due_at }) · list · iterate · get | Callbacks for agents |
| queues.list() | Queues, who is waiting, who is free |
| agents.list() · agents.get(id) | Agents and their live state |
| voicemails.list({ unheard }) · voicemails.iterate() | Voicemail, with transcripts |
| webhooks.list() · create · get · update · delete · deliveries · test | Event webhooks |
| webhooks.verify(body, headers, secret) | Check and parse an event we sent you |
| voice.tokens.create({ agent_id, ttl_seconds }) | A token for browser calling (60 s - 24 h, default 1 h) |
| voice.verifyRequest(body, headers, secret) | Check and parse a call-control request |
| request({ method, path, query, body }) | Any endpoint not wrapped yet |
Fields are named exactly as in the API reference: snake_case, times in ISO 8601 UTC (pass a
Date or a string), phone numbers in E.164 (send any common format).
Webhooks
Add an endpoint once and store its signing_secret, which is shown only then:
const endpoint = await seamlessvoip.webhooks.create({
url: 'https://your-app.example/webhooks',
events: ['call.started', 'call.ended', 'call.missed', 'voicemail.received'],
});
// save endpoint.signing_secretVerify every event against the raw body:
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
let event;
try {
event = seamlessvoip.webhooks.verify(req.body, req.headers, process.env.WEBHOOK_SECRET);
} catch (e) {
return res.status(400).send(e.message);
}
if (event.type === 'call.missed') console.log('Missed call from', event.data.call.from);
res.sendStatus(200);
});Signatures are t=<unix seconds>,v1=<HMAC-SHA256 of "t.body">. Requests older than 5 minutes
are refused ({ toleranceSeconds } changes it). signPayload(secret, body) makes one for your tests.
Answering calls from your server
Point a number at your server ("Ask our server" under Numbers). When it rings we POST
call.incoming; answer within 5 seconds with one step. Steps can carry what happens next:
app.post('/voice', express.raw({ type: 'application/json' }), (req, res) => {
const call = seamlessvoip.voice.verifyRequest(req.body, req.headers, process.env.VOICE_SIGNING_SECRET);
if (call.event === 'gather.completed') {
return res.json(call.digits === '1' ? { type: 'queue' } : { type: 'voicemail' });
}
res.json({
type: 'gather', prompt: 'sound:press-1-for-sales', digits: 1, timeoutSeconds: 5,
action: 'https://your-app.example/voice', fallback: { type: 'queue' },
});
});The voice signing secret is in SeamlessVoIP under Developers. Steps: queue, ring, menu,
flow, voicemail, dial_endpoint, forward, play, gather, schedule, webhook,
hangup, ai, channel, choice, caller, sms (typed as CallStep).
Errors
Every failed request throws an ApiError with a stable code to branch on:
import { ApiError } from '@seamlessvoip/node';
try {
await seamlessvoip.calls.get('nope');
} catch (e) {
if (e instanceof ApiError && e.code === 'not_found') { /* ... */ }
// e.status, e.title, e.detail, e.errors, e.retryAfter (429), e.raw
}ApiConnectionError means no answer arrived (network); ApiTimeoutError means none within
timeoutMs (default 30 s), in which case the request may still have been carried out.
Safe retries
Calls that start something (calls.create, sms.send, callbacks.create, webhooks.create)
send an Idempotency-Key. Pass your own to make a retry return the first answer instead of
calling twice: seamlessvoip.calls.create(params, { idempotencyKey: order.id }).
Paging
Lists answer { items, total, page, size } (size up to 200). iterate() walks every page:
for await (const call of seamlessvoip.calls.iterate({ outcome: 'MISSED', from: '2026-11-01T00:00:00Z' })) {
console.log(call.from, call.started_at);
}Configuration
new SeamlessVoIP({
apiKey: 'sv_live_...', // default: process.env.SEAMLESSVOIP_API_KEY
baseUrl: 'https://api.seamlessvoip.com', // default
timeoutMs: 30_000,
});Also exported as Client. Licensed MIT.
