POST
Call a lead now
Somebody who filled in a form a minute ago still remembers why. Somebody called the next morning often does not. This endpoint is for that first minute: send the lead, and the agent rings them from its own number, usually within a few seconds of your request. Call it from wherever leads arrive: your website’s form handler, your CRM, or an automation tool such as Zapier or Make sitting behind Meta or Google lead ads.

Before the first lead

  1. Attach a Twilio number to the agent in the console. The call goes out from that number. To use a different one, pass it as from.
  2. Create an API token on the API Tokens page.
  3. Write the agent for an outbound call: it rang them, so it should say who it is, why it is calling, and ask whether now is a good time. The Real-estate sales template is written this way.

Sending a lead

variables are filled into the agent’s instructions and greeting, so an agent written with {{unit}} opens knowing what the lead asked about. name is available as {{name}}.

What happens to a lead

Every lead lands in one standing campaign per agent, named Instant leads, on the Outbound page. That is where you see who answered, who did not, and each conversation. The same rules as any campaign apply:
  • Calling window. Leads are called between 09:00 and 20:00 Riyadh time. One that arrives at night is called when the window opens.
  • No answer. Retried twice more, 15 minutes apart. A voicemail counts as no answer, and the agent hangs up on it rather than talking to the tone.
  • Do not call. A number on your do-not-call list is never called.
  • Double submissions. The same number sent again while a call to it is under way does not place a second call. Sent again later, it is a new lead and gets the full set of attempts.
  • Pausing. Pause Instant leads on the Outbound page and new leads are refused with 409 until you resume it.

Cost

A call is billed per connected minute at the live call rate, from the same balance as everything else. A call that is not answered costs nothing.
Outbound calls need a Twilio number today. SIP trunks can receive calls but cannot yet place them.

Authorizations

Authorization
string
header
required

API token from the Voho console. Begins with voho_sk_live_.

Path Parameters

id
string
required

The agent's ID, from /v1/agents.

Body

application/json
to
string
required

The lead's phone number, in international format.

Example:

"+966512345678"

name
string

The lead's name. Also available to the agent as {{name}}.

Example:

"سارة"

variables
object

What the lead asked about, filled into the agent's instructions and greeting as {{unit}} and the like, so it opens knowing why it is calling. Up to 10 keys, letters, digits and underscores.

Example:
from
string

Call from this number instead of the agent's own. Must be a Twilio number on your account.

Example:

"+966112345678"

Response

The lead was accepted.

status
enum<string>

calling: the phone is ringing now. queued: it will be called at the next opportunity, see reason. skipped: it will not be called, see reason.

Available options:
calling,
queued,
skipped
lead_id
string
batch_id
string

The agent's Instant leads campaign.

reason
string

Why the lead was queued or skipped.

seconds_to_call
number

From receiving the request to placing the call, when status is calling.