> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yotel.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Dial notice (call.dialing)

> Get a signed call.dialing POST the moment Yotel dials a lead for your voice agent, so you can load the lead's details while the phone rings.

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:

1. **On the voice agent:** an address and a secret (`dial_notify_url` and
   `dial_notify_secret`).
2. **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

```bash theme={null}
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](https://docs.yotel.in/webhooks/signature-verification.md):

| 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):

```json theme={null}
{
  "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](https://docs.yotel.in/voice-agents/quickstart.md) 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**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.