Phone (dialpad)
The Phone component embeds a complete dialpad in your application, letting end users place outbound voice calls directly from your UI. It pairs with Surge's voice API and one-click integrations to AI voice agents.
When to use it
- You're building a contact-center or SaaS dialer and you want a working dialpad on day one
- You don't want to build call setup, mute, hold, and DTMF UI yourself
- Your end users expect to make calls from inside your product without leaving the page
If you only need to place programmatic calls (no UI), use the Calls API directly (POST /accounts/:account_id/calls).
Embed snippet
<script src="https://embed.surge.app/v1/embed.js"></script>
<div id="surge-phone"></div>
<script>
Surge.Phone.mount({
target: "#surge-phone",
token: "YOUR_SIGNED_JWT_TOKEN",
accountId: "acct_01jrzhe8d9enptypyx360pcmxj",
fromNumber: "+18015551234",
onCallEnded: (call) => {
console.log("Call ended:", call.id, call.duration);
},
});
</script>Props
| Prop | Type | Required | Description |
|---|---|---|---|
target | string (CSS selector) | Yes | Where to mount the dialpad |
token | string (JWT) | Yes | Signed JWT scoping the user. See Authentication. |
accountId | string | Yes | Account the call is placed under. Determines billing and which campaign rules apply. |
fromNumber | string (E.164) | Yes | The Surge phone number that will appear as the caller ID. Must be attached to the account. |
onCallEnded | (call) => void | No | Fires when the call wraps up. Useful for logging or unlocking your UI. |
onError | (error) => void | No | Fires for setup errors (token invalid, number not provisioned, microphone denied). |
What the user sees
A standard 3×4 dialpad, a number-entry display, a mute toggle, and a green/red call/hangup button. During an active call, the timer counts up. After hangup, the component returns to the idle dialpad state.
Microphone permissions
The dialpad asks for microphone access on first call. If the browser denies it, onError fires with error.code: "microphone_denied" and you should surface a clear message — the embed cannot recover that permission on its own.
Phone calls vs voice agents
Outbound calls placed from this component go to the dialled number directly. If you want the call to flow through an AI voice agent (ElevenLabs, Retell, Vapi), that's configured on the Surge phone number itself — see Channels Roadmap → Voice. The dialpad doesn't need to know whether the number on the other end is a human or an agent.