Dial notice (call.dialing)

When a campaign dials a lead for your voice agent, the phone usually rings for 5 to 40 seconds before anyone answers. The dial notice gives your system that time: Yotel sends a signed call.dialing POST to an address you choose right before it dials, so you can load the lead’s latest details and have them ready before the call is answered. It is off by default, and it needs two things switched on:

On the voice agent: an address and a secret (dial_notify_url and dial_notify_secret).
On the campaign: the switch pre_call_lead_fetch (“Send lead details to the AI agent before the call connects” in the campaign form).

Set it up on the voice agent

curl -X PATCH https://api.yotel.in/api/v1/voice-agents/{voice_agent_id} \
  -H "X-API-Key: yt_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dial_notify_url": "https://your-system.example/yotel/dialing",
       "dial_notify_secret": "a-long-random-string-you-keep-safe"}'

The key needs the voice_agents:write scope.
dial_notify_url must be https:// and must point to a public host. Private, loopback and cloud-metadata addresses are refused (422), and the check runs again on every send.
dial_notify_secret is 16 to 256 printable characters with no spaces. It is write-only: reads return "***" when it is set and null when it is not.
An address without a secret is refused (422), so a notice is never sent unsigned.
To change only the secret, send dial_notify_secret alone. The address stays.
To turn it off, send {"dial_notify_url": null}. This clears the address and the secret. Running campaigns stop sending within about a minute; no pause is needed.

Turn it on for a campaign

Set pre_call_lead_fetch: true on the campaign (POST or PATCH /api/v1/campaigns), or switch it on in the campaign form. The switch is offered only for campaigns whose calls can reach a voice agent. Like every campaign setting, it cannot be changed while the campaign is running: pause it, change the setting, then resume.

When it is sent

For every outbound dial that actually goes out, right before the dial: voice-agent campaigns, flow campaigns whose flow can reach a voice agent (each distinct voice agent with an address gets one notice), and predictive or power campaigns whose answered calls go to a voice agent.
It is not sent for a dial that Yotel holds back (no free channel, or the voice agent is at its max_concurrent), and never for inbound calls.
It is sent for dials nobody answers too: Yotel cannot know in advance.

Delivery

The notice never delays the dial:

One attempt only, with a 1 second limit. There are no retries; a late notice is of no use.
If too many notices are already waiting, new ones are dropped, not queued.
Answer quickly with any 2xx (for example 202). Do your loading after you answer.

The request

Headers and signature are the same as for webhooks:

Header	Value
`X-Yotel-Event`	`call.dialing`
`X-Yotel-Delivery`	the `event_id`
`X-Yotel-Timestamp`	Unix seconds
`X-Yotel-Signature`	`sha256=` + hex HMAC-SHA256 of `"{timestamp}." + raw body`, keyed with your `dial_notify_secret`

Reject a request whose signature does not match or whose timestamp is more than 5 minutes old. Body (compact JSON, keys sorted):

{
  "event_id": "8a1c...-uuid",
  "event_type": "call.dialing",
  "timestamp": 1763115600,
  "data": {
    "call_id": "c2f0...-uuid",
    "tenant_id": "3b7d...-uuid",
    "campaign_id": "e1ac...-uuid",
    "voice_agent_id": "22aa...-uuid",
    "external_agent_id": "your-agent-id",
    "lead_id": "9d41...-uuid",
    "salesforce_lead_id": "00Q5g00000ABCDE",
    "variables": { "lead_name": "Asha", "salesforce_lead_id": "00Q5g00000ABCDE" },
    "dialed_at": "2026-11-14T10:20:00.123456+00:00"
  }
}

Field	Meaning
`call_id`	The call’s id. It is the same `call_id` your voice agent receives in the metadata frame when the call is answered, so you can key what you load on it.
`lead_id`	Yotel’s id for the lead.
`salesforce_lead_id`	The id the lead was sent in with (a Salesforce Lead id or your own key), or `null`.
`variables`	Exactly the `variables` the metadata frame will carry for this call.
`external_agent_id`	Your id for the voice agent, if set.
`dialed_at`	When Yotel sent the notice (UTC).

The body never contains a phone number.

Get started

OAuth

Core concepts

Voice agents

SDKs

Integrations

Set it up on the voice agent

Turn it on for a campaign

When it is sent

Delivery

The request