IVR Outbound Call API

Place a call

POST /v1/ivr/calls with your API key in X-API-Key (or Authorization: Bearer). The base URL is shared with your API key.

{
  "flow_id": "5b1c2f0e-...",
  "to": "+919800000000",
  "variables": { "order_id": "A123", "name": "Ravi", "amount": 499 },
  "reference_id": "crm-lead-42",
  "status_callback_url": "https://crm.example.com/ivr/status",
  "ring_timeout_sec": 45
}

The response is 202 Accepted with a call_sid and status queued. GET /v1/ivr/calls/{call_sid} returns the call log: status, duration, price, keys pressed, variables and every HTTP request the flow made.

curl -X POST "$EDESY_API_BASE/v1/ivr/calls" \
  -H "X-API-Key: $EDESY_API_KEY" \
  -H "Idempotency-Key: order-A123-confirm" \
  -H "Content-Type: application/json" \
  -d '{"flow_id": "5b1c2f0e-...", "to": "9800000000", "variables": {"order_id": "A123"}, "reference_id": "A123"}'

Safe retries with Idempotency-Key

Send Idempotency-Key with a unique value. A repeat of the same request with the same key within 24 hours returns the original response and does not dial again. The same key with a different body is rejected, so a bug in your retry logic can't call a customer twice.

Speak per-call details

In Say text and Menu prompts, {{var.order_id}} is replaced with that call's value: "Your order {{var.order_id}} is ready." A variable the call doesn't have is spoken as nothing. Up to 20 variables per call.

Call your API on a keypress

Add an HTTP Request step after a Menu branch, so each key calls a different endpoint. URL, headers and body can use {{var.*}}, {{digits}}, {{reference_id}}, {{call_sid}} and more. Values are escaped for where they land, so a variable can't break your JSON or change the host.

Every request is logged in the portal, and a failed background request can be retried from there.

Status callback

When the call ends we POST to your status_callback_url, retried up to 5 times:

{
  "event": "ivr.call.completed",
  "timestamp": "2026-10-09T10:15:00Z",
  "data": {
    "call_sid": "...",
    "reference_id": "crm-lead-42",
    "status": "completed",
    "duration_sec": 42,
    "dtmf_path": ["1"],
    "variables": { "order_id": "A123" },
    "http_requests": [{ "node_id": "http-1", "status": "delivered", "response_code": 200 }]
  }
}

event is ivr.call.completed, ivr.call.no-answer, ivr.call.busy or ivr.call.failed.

Verify that a request came from Edesy

Status callbacks and HTTP Request steps carry X-Edesy-Timestamp and X-Edesy-Signature: sha256=<hex>, the HMAC-SHA256 of the timestamp, a dot and the raw body, using the signing secret from your portal. HTTP Request steps also send X-Edesy-Idempotency-Key so you can drop duplicates.

import hmac, hashlib, time

def verify(headers, raw_body: bytes, secret: str) -> bool:
    ts = headers["X-Edesy-Timestamp"]
    expected = "sha256=" + hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(ts)) < 300 and hmac.compare_digest(expected, headers.get("X-Edesy-Signature", ""))

Reject requests whose timestamp is more than 5 minutes old.