Outbound call · Heppu API

POST/api/v1/calls/outboundkey or session

The direct line. No job, no schedule, just "call this person with this worker". Queued and dialled within seconds.

For anything with more than one contact or any retry logic, use a job instead.

agentIduuidrequired

Must be a voice worker with status active.

phoneNumberstringrequired

E.164.

callerIdstring

One of the worker's numbers. Default is its first.

priorityint 0–10

Lower dials first.default 5

metadataobject

Context for the worker.

curl -X POST https://v2.heppu.ai/api/v1/calls/outbound \
  -H "x-api-key: hep_..." -H "Content-Type: application/json" \
  -d '{"agentId":"6f0c…","phoneNumber":"+358401234567","metadata":{"orderId":"A-1041"}}'

201

{
  "data": {
    "id": "V1StGXR8_Z5jdHi6B-myT",
    "status": "queued",
    "agentId": "…",
    "phoneNumber": "+358401234567",
    "callerId": "+358…",
    "startedAt": "…",
    "agent": { "id": "…", "name": "…", "type": "voice" },
    "metadata": { "caller_id": "+358…", "priority": 5, "orderId": "A-1041" }
  },
  "meta": { "timestamp": "…", "message": "Outbound call queued. Poll GET /api/v1/calls/{id} for dial progress." }
}

Poll GET /v1/calls/{id} if you care about ringing state. Otherwise wait for the call.completed webhook.

Errors: 403 number is on your blocklist, 400 worker isn't voice or isn't active, 404 worker not found, 500 telephony not configured for the org (talk to us).