Mailbox detection
Detect voicemail and other machines on outbound calls, and retry a lead list safely, for example from n8n.
Mailbox detection tells you whether an outbound call reached a person or a machine. Turn it on per call, then read the result from getCall. This guide shows how a workflow tool such as n8n can use it to work through a lead list. Walido places each call; the retry schedule is yours.
Start a call with detection
Detection is off unless you set mailbox_detection: true:
curl -X POST https://api.walido.it/api/v1/calls \
-H "Authorization: Bearer <your_api_key>" \
-H "Content-Type: application/json" \
-d '{ "assistant_id": "<assistant_id>", "to": "+491701234999", "mailbox_detection": true }'Detection works for assistants whose language is de. For any other
language, including de-CH, the call runs normally and detection reports
skipped with the reason language_not_supported.
Read the result
Poll the call until done is true. The result is in mailbox_detection;
connection tells how the attempt ended at the telephone network:
{
"data": {
"id": "65f8fa6f1a9d8e0012ab34cd",
"done": true,
"ended_at": "2026-07-01T10:00:00.000Z",
"connection": {
"status": "answered",
"answered_at": "2026-07-01T09:59:42.000Z",
"sip_status": 200
},
"mailbox_detection": {
"status": "completed",
"category": "machine-vm",
"reason": "Voicemail instructions permit leaving a message.",
"greeting": "Bitte hinterlassen Sie eine Nachricht nach dem Signalton.",
"decided_at_ms": 10400
}
}
}A machine category (machine-vm, machine-ivr, machine-unavailable) ends
the call. human and uncertain leave the conversation running. See
getCall for every field.
Detection only runs on a call that was accepted. A call that nobody accepted,
or that met a busy line, reports connection.status no_answer or busy, and
its detection is skipped. An accepted call that ended before the verdict
reports skipped too, so read connection first. Every ended outbound call
carries connection, with or without detection. started_at,
duration_seconds, an empty transcript and success do not tell whether a
call was answered.
Poll every 5 seconds for the first minute, then every 15 seconds. If a call has no result after 30 minutes, mark the lead for review instead of calling again.
Keep an attempt ledger
For each lead, store its ID, phone number, attempt count, current call ID, processed call IDs, next attempt time, and status. Use a store with atomic updates so one lead never has two active attempts, and so a repeated poll or a restarted workflow never counts an attempt twice.
Reserve the attempt before you create the call, and save the returned call ID right after. Set your own attempt limit and count attempts in total, not retries. This guide uses three.
Creating a call is not idempotent. Turn off automatic retries on the request that creates the call. If it times out or returns an unclear error, the call may already exist: pause the lead and check before trying again.
Decide once per ended call
connection.status | Detection result | Action |
|---|---|---|
no_answer or busy | any | Nobody was reached. Schedule the next attempt on your own schedule, or mark the lead exhausted at your attempt limit. |
answered | completed with a machine category | Schedule the next attempt no earlier than the call's ended_at plus two hours, or mark the lead exhausted at your attempt limit. |
answered | completed with human or uncertain | Use your qualification analysis (below). |
answered | failed, skipped, or missing | Mark the lead for review. |
Any other value, or connection missing | any | Mark the lead for review. |
The other two values are no proof that nobody was reached. failed covers
declined calls and numbers the network could not reach; sip_status carries
the code if you want to sort them. "status": "unknown" means the call ended
without a recorded telephony result. Carriers signal a manually declined call
differently: as busy, as failed, or by diverting it to voicemail, which
reads as answered with a machine category.
Schedule in UTC. Example: a machine answer ending at 10:00 UTC allows the next attempt from 12:00 UTC.
Space calls from the same assistant at least 60 seconds apart. By default each API key can create 60 calls per hour and make 1,000 reads per minute; see Errors & Rate Limits.
Qualification is a separate result
Analyses, CRM actions, and notifications run for every call, including
machine calls, so check the detection result before acting on them. An ended
call can still have an analysis running: wait for your qualification
analysis to complete, and send failed or missing results to review. On a
transferred call, an analysis that uses didTryForwarding or
didForwardingSucceed starts only once the transfer has ended, at most 43
minutes later; allow for that before you treat its result as missing. The
call's success field says whether anything was left open after the call, not
whether the lead qualified.
Test the workflow with a few controlled leads before a real campaign, including duplicate runs, restarts, and unclear responses.
