callcloud-partner
v0.2.0
Published
CallCloud partner SDK: embed the parallel-dialer softphone, call the Partner API, verify webhooks.
Maintainers
Readme
callcloud-partner
Build your own dialer UI on CallCloud's parallel dialer. CallCloud handles the calling: lines, carriers, voicemail handling, recordings and transcripts. You keep your leads, your screens and your outcomes.
The package has two halves:
| Where | What | Import |
|---|---|---|
| Browser | Softphone: the rep's line, embedded once in your app, with typed methods and events | callcloud-partner/softphone |
| Your server | PartnerClient for rep tokens, reps, numbers, pools, settings, recorded messages, the calls feed and abandon stats; verifyWebhook for call events | callcloud-partner/server |
It has no dependencies. The server half runs on Node 18+, Deno, Bun, Cloudflare Workers and edge runtimes.
Install
npm install callcloud-partnerBefore you start
You need a CallCloud partner workspace, which CallCloud sets up for you. Then:
- In Settings > Developers, create an API key (
ccp_...). Keep it on your server only. - In the same tab, set your webhook URL and copy the signing secret (
whsec_...). - Tell CallCloud the origin your app runs on, e.g.
https://app.example.com. The softphone only loads inside, and only talks to, origins on your workspace's list.
1. Mint a rep token (your server)
Reps never sign in to CallCloud. Your server mints a 1-hour token for the rep who is signed in to your app. The first token for a new email adds that rep as a seat.
import { PartnerClient } from 'callcloud-partner/server';
const cc = new PartnerClient({ apiKey: process.env.CALLCLOUD_API_KEY! });
// e.g. GET /api/callcloud-token, behind your own auth
export async function GET(req: Request) {
const user = await requireUser(req);
const { token } = await cc.tokens.mint({ repEmail: user.email, repName: user.name });
return Response.json({ token });
}2. Mount the softphone (browser)
Mount it once, at your app root, and keep it mounted for the whole session. Remounting it between calls drops the line and adds seconds to every call.
import { Softphone } from 'callcloud-partner/softphone';
const phone = Softphone.mount({
container: '#callcloud-phone', // keep it visible; a hidden frame can be throttled or muted
getToken: () => fetch('/api/callcloud-token').then((r) => r.json()).then((d) => d.token),
rep: { email: user.email, name: user.name },
callerId: 'rep', // or 'group:<name>', or one of your E.164 numbers
});
await phone.ready; // the rep's line is registeredgetToken is called for the first token. It is called again each time the softphone warns that the token is about to expire, and the new token is swapped in without touching the line. Calls you make before ready are held until the line is up.
Dial
phone.on('answered', ({ callId, metadata }) => openLeadCard(metadata.leadId));
phone.on('ended', (e) => saveAttempt(e.metadata.leadId, e.status, e.talkSeconds));
phone.on('error', ({ code, message }) => toast(message));
phone.dial({ to: '+14155550123', name: 'Dana Lee', metadata: { leadId: 'L1' } });
// or ring up to 5 at once; the first human is put through
phone.dialBatch({ legs: [
{ to: '+14155550123', metadata: { leadId: 'L1' } },
{ to: '+12125550100', metadata: { leadId: 'L2' } },
] });Whatever you send as metadata (about 1 KB) comes back on every event and every webhook for that call. Put the data your lead card needs on the dial itself, so you can draw the card the moment answered fires. Drive your UI from these events, never from webhooks: webhooks arrive later.
In-call controls:
phone.mute(); phone.unmute();
phone.dtmf('1');
phone.judge(callId, 'voicemail'); // or 'skip': the rep's call on what picked up
phone.hangup();
const state = await phone.getState(); // { phase, registered, callId, poolId, available, ... }Team pools
A pool is one shared dialing session for a team. CallCloud dials the pool's queue and routes each answered call to a free rep. You create and fill the pool on your server:
const pool = await cc.pools.create({ name: 'Monday blitz', lineCount: 10, routing: 'longest_idle', localPresence: true });
await cc.pools.queue(pool.id, leads.map((l) => ({ to: l.phone, name: l.name, metadata: { leadId: l.id } })));
await cc.pools.update(pool.id, { lineCount: 6 }); // takes effect at onceThen each rep joins from the browser:
phone.joinPool(poolId);
phone.on('routed', ({ callId, metadata, answerToConnectMs }) => openLeadCard(metadata.leadId));
phone.on('available', ({ available, reason }) => setRepStatus(available, reason));
phone.on('pool.idle', ({ message }) => banner(message)); // e.g. no number to call from
phone.setAvailable(true); // after wrap-up
phone.leavePool();Each number is dialed at most once per pool. If the same rep joins from a second device, the newest device takes the line and the old one gets pool.left with reason replaced.
Inbound calls and callbacks
Turn inbound on once (cc.settings.update({ inbound: 'softphone' }); a softphone already signed in picks it up at its next token refresh) and keep the rep's line open with standby. A prospect who calls one of your numbers then rings the softphone of the rep they belong to: the one who called them last, or their owner.
const phone = Softphone.mount({ container: '#phone', getToken, standby: true });
phone.on('incoming', (c) => showRinging(c)); // { callId, kind: 'inbound' | 'transfer', from, name, company, fromRep }
phone.on('incoming.ended', ({ callId, reason }) => hideRinging(callId));
phone.answer(callId); // or phone.decline(callId): forwarding phone, else voicemail + a callbackAn answered call is an ordinary call: answered (with direction: 'inbound'), then ended, and the webhooks. If no softphone line is open, the call goes to the rep's forwarding phone or voicemail and becomes a callback, as before. A pool lane is an open line too.
Live transfer to another rep
phone.transfer({ toRep: '[email protected]' }); // warm: the closer's softphone rings (incoming, kind 'transfer')
phone.on('transfer.state', (t) => render(t)); // ringing -> joined (all three on) | no_answer
phone.hangup(); // once joined: leaves the closer the call (state 'completed')
phone.cancelTransfer(); // stop ringing, or once joined send the closer back
phone.transfer({ to: '+14155550123' }); // cold, to a number: this rep drops at onceThe closer needs an open line (standby, a pool, or dialing) and must not be on a call. Their side gets answered with transfer: { fromRep }, transfer.state with role: 'closer' (joined, then completed), and their own ended when they hang up. The rep who handed it over gets ended with transferred: { toRep }. Every event and webhook keeps your metadata.
Hold, voicemail drop and call screeners
phone.hold(); // the prospect hears a soft chime; the keypad waits; at most 10 minutes
phone.resume(); // hold.state { callId, on }
phone.dropVoicemail(); // leaves the rep's recorded voicemail at the beep and ends the call (voicemail.dropped)
phone.dial({ to, metadata, voicemail: 'drop', screener: 'rep' });Upload each rep's messages first: cc.reps.messages.put(email, 'voicemail', { audioBase64, mime: 'audio/wav' }) and 'screener' (WAV or MP3, under 3 MB).
| Option | 'hangup' (default) | 'drop' | 'rep' | 'message' (pools only) |
|---|---|---|---|---|
| voicemail | hung up | the rep's voicemail at the beep | the rep hears the greeting | |
| screener | hung up | | put through to the rep, who says who they are | the rep's screener message at the screener's silence; if the person picks up they go to a free rep |
Pools take the same two settings (cc.pools.create({ voicemail, screener })). call.machine.kind on ended and the webhooks says what answered: voicemail, screener or phone_menu.
Mic and speaker
const d = await phone.getDevices(); // { inputs, outputs, micId, speakerId }
phone.setDevices({ micId: d.inputs[1].id, speakerId: 'default' }); // a live call moves at once
phone.on('devices', (d) => render(d)); // also sent when a headset is plugged in or outThe choice is kept for this computer. Labels appear once the rep has allowed the microphone. The panel has its own Audio picker too.
Listen in
Turn monitoring on (cc.settings.update({ monitoring: true })), then from a free softphone (no call, not in a pool):
phone.listen(callId); // muted; listen.state connecting -> on
phone.setListenMode('whisper'); // only the rep hears you; 'barge' = everyone does; 'listen' = muted again
phone.stopListening(); // also ends by itself when the call does (listen.state ended)callId is the one your app got on that rep's answered or routed.
Softphone events
ready, registering, registered, error, tokenExpiring, state, call.state, answered, ended, batch.started, pool.joined, pool.left, available, routed, pool.idle, pool.resumed, incoming, incoming.ended, transfer.state, hold.state, voicemail.dropped, devices, line.state, listen.state. Every payload is typed (SoftphoneEvents). phone.onAny((type, payload) => ...) receives all of them.
3. Receive webhooks (your server)
import { verifyWebhook } from 'callcloud-partner/server';
export async function POST(req: Request) {
const rawBody = await req.text(); // the untouched body; a re-serialised one won't verify
let event;
try {
event = await verifyWebhook({ rawBody, headers: req.headers, secret: process.env.CALLCLOUD_WEBHOOK_SECRET! });
} catch {
return new Response('bad signature', { status: 401 });
}
if (await alreadySeen(event.id)) return new Response('ok'); // ids are stable across retries
queueWork(event); // answer fast, work after
return new Response('ok');
}On Express, use express.raw({ type: 'application/json' }) for this route and pass req.body (a Buffer) plus req.headers.
Recording links (recording.url, recording.shareUrl) are served by dialer.callcloud.app and do not expire.
| Event | When | Extra field |
|---|---|---|
| call.ended | every leg, once it's over | |
| call.abandoned | someone answered while the rep was on another line | |
| call.machine_detected | a voicemail or screener was caught | call.machine |
| recording.ready | the stereo recording is stored (left = prospect, right = rep) | recording |
| transcript.ready | the call is transcribed (only calls where the rep talked) | transcript |
| summary.ready | the AI summary is done | summary |
Every event carries call: id, from, to, status, answeredBy, talkSeconds, hangupCause, sipCode, repEmail, poolId, requeued, metadata and more (WebhookCall). If requeued is true, the dialer cut that ring itself and put the number back in the queue, so don't count it as a try. Deliveries from Send test events have event.test === true. A delivery that doesn't get a 2xx is retried with backoff for up to 24 hours.
Catch up on missed events: the calls feed
Webhooks are the fast path; the feed is the safety net. It has every call your softphones and pools placed (and inbound calls to them), with the same call object as the webhooks plus the recording, transcript and summary once they exist.
for await (const c of cc.calls.all({ since: lastSyncedAt })) {
upsert(c.call.id, c); // c.final === false: still live, it comes back with its end next time
}
const one = await cc.calls.get(callId);cc.calls.list({ since, cursor, limit }) gives one page ({ calls, nextCursor }, oldest first, up to 30 days back).
Settings
await cc.settings.get();
await cc.settings.update({ repeatCap: { day: 8, week: 20 } }); // null = back to 5 and 15| Setting | Default | What |
|---|---|---|
| repeatCap | { day: 5, week: 15 } | How often ONE rep may ring ONE number: 1 to 10 a day, up to 30 a week. A dial past it is refused with repeat_cap; override: true rings it anyway. |
| inbound | 'forward' | 'softphone': calls to your numbers ring the rep's open softphone line. |
| monitoring | false | Calls get a listening room, so a softphone can listen in. |
Numbers
const options = await cc.numbers.search(415);
const num = await cc.numbers.buy(options[0].phone); // billed monthly from today
await cc.numbers.update(num.id, { repEmail: '[email protected]' }); // Sam's caller ID
await cc.numbers.update(num.id, { group: 'west' }); // dial with callerId 'group:west'
await cc.numbers.release(num.id);Errors
Partner API failures throw PartnerApiError with status, code and message, the same { error: { code, message } } the API returns. For example, buying a number during a card-free trial gives 402. Softphone failures arrive as error events. phone.ready rejects with a SoftphoneError, either invalid_token or ready_timeout.
Anything not wrapped yet: cc.request(method, path, body?, query?).
Questions or a new origin to allow: email [email protected].
