@sayvona/voice
v0.1.0
Published
Browser calling for Sayvona: a headless WebRTC phone your web app drives with events and methods, signed in with short-lived access tokens. React hook included.
Maintainers
Readme
@sayvona/voice
Browser calling for Sayvona. A headless WebRTC phone your web app drives with events and
methods: make and take real phone calls from a page, with no plugin and no desk phone. A React
hook is included at @sayvona/voice/react.
npm install @sayvona/voiceQuickstart (5 minutes)
1. Your server mints a token for the signed-in user with
@sayvona/node and your API key:
// server - npm install @sayvona/node express
import { Sayvona } from '@sayvona/node';
const sayvona = new Sayvona(); // reads SAYVONA_API_KEY
app.get('/voice-token', async (req, res) => {
const { token } = await sayvona.voice.tokens.create({ agent_id: req.user.agentId });
res.json({ token });
});2. The page connects with it and calls:
import { createVoiceClient } from '@sayvona/voice';
const voice = createVoiceClient({
// Called at connect and again before the session lapses; fetch a fresh one each time.
getAccessToken: () => fetch('/voice-token').then(r => r.json()).then(j => j.token),
});
voice.on('registered', () => console.log('Ready'));
voice.on('incoming', call => confirm(`Answer ${call.number}?`) && voice.answer(call.id));
voice.on('callConfirmed', call => console.log('Talking to', call.number));
voice.on('callEnded', ({ id }) => console.log('Call ended', id));
await voice.connect();
voice.call('+254712345678');The page needs HTTPS (or localhost) and the user's permission to use the microphone. Audio
plays by itself; remoteStream hands you the stream if you want to render it.
React
import { useVoiceClient } from '@sayvona/voice/react';
function Phone() {
const { status, incoming, calls, client } = useVoiceClient({
getAccessToken: () => fetch('/voice-token').then(r => r.json()).then(j => j.token),
});
if (status !== 'registered') return <span>Connecting…</span>;
if (incoming) return <button onClick={() => client.answer(incoming.id)}>Answer {incoming.number}</button>;
return <button onClick={() => client.call('+254712345678')}>Call</button>;
}The hook connects on mount and disconnects on unmount. react 18 or later is an optional peer dependency.
Methods and events
connect(), disconnect(), isReady(), call(number), answer(id), hangup(id), hold(id),
unhold(id), mute(id), unmute(id), dtmf(id, digits), getCalls().
Events (voice.on(name, handler)): registered, registrationFailed, disconnected, incoming,
callStarted, callConfirmed, callEnded, remoteStream.
How the session works
connect() trades the token for a phone login made for this session alone. It rings together
with the person's other phones and its calls carry their caller ID. Before it lapses the SDK
calls getAccessToken() again and renews it; disconnect() ends it at once. If you stop
issuing tokens, the session is ended soon after the last one expires. Up to three sessions per
person; a fourth replaces the oldest.
With an access token, voice.server (transfer, park, presence) is not available yet and throws.
Notes
- ESM only. Importing it during server-side rendering is safe: nothing touches the DOM until
connect(). apiBaseUrldefaults tohttps://api.sayvona.com.
Licensed MIT.
