Skip to Content
HallolaraDocs
Public API

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. Hallolara 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.hallolara.ai/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.statusDetection resultAction
no_answer or busyanyNobody was reached. Schedule the next attempt on your own schedule, or mark the lead exhausted at your attempt limit.
answeredcompleted with a machine categorySchedule the next attempt no earlier than the call's ended_at plus two hours, or mark the lead exhausted at your attempt limit.
answeredcompleted with human or uncertainUse your qualification analysis (below).
answeredfailed, skipped, or missingMark the lead for review.
Any other value, or connection missinganyMark 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.

On this page