Skip to main content

Call-through-API

Call-through-API lets you place calls from your own product, using Lead Hero's numbers, billing, recordings, and answering machine detection, without your agents ever opening the Lead Hero app.

Requires access to be enabled

Call-through-API is not self-serve. It has to be enabled on your organization by Lead Hero before any of these endpoints will work. Until then, every call-through-API request returns 403.

Contact Lead Hero to request access for your organization before you start integrating.

Use the npm package​

The easiest way to integrate is the official @leadhero/dialer package. It wraps the endpoints below, answers the agent's WebRTC leg in the browser, manages microphone and speaker devices, and emits live pickup and answering machine detection events.

npm install @leadhero/dialer

It ships two entry points so your organization API key can never end up in browser code:

import { DialerServer } from '@leadhero/dialer/server'; // Node only, holds the API key
import { Dialer } from '@leadhero/dialer/browser'; // Browser only, never sees the API key

See the package README for a full backend and frontend quick start.

How a call works​

A call-through-API call happens in two places at once:

  1. Your backend authenticates with your organization API key, makes sure an API calling user exists for the agent, mints a short-lived session for them, and places the call.
  2. Your frontend uses that session to register a WebRTC softphone that answers the agent's leg of the call. Without it, the call rings for an instant and is torn down.

In terms of the Call-through-API endpoints:

  1. Create an API calling user (POST /calls/api-users/{organization}) for each agent. If the email already belongs to a Lead Hero member, the API calling user shares that member's seat. Otherwise it reserves a free seat on your organization.
  2. Mint a session (POST /calls/api-users/{organization}/{id}/session). Returns a 5 minute websocket token and WebRTC token scoped to that one user. This is safe to send to the browser.
  3. Connect the softphone in the browser with that session, and wait for it to be ready.
  4. Dial (POST /calls/api-users/{organization}/{id}/dial) with the number to call and, optionally, the lead to attach it to.
  5. Hang up or send DTMF with the regular Calls endpoints, which work for call-through-API calls too.

Requirements for dialing​

Besides call-through-API being enabled, a dial only goes through when:

  • Your organization is not suspended for low balance and has billing set up.
  • The API calling user is active, covered by a seat, and has finished provisioning.

Each endpoint's page in the API reference lists the exact errors it can return.