Skip to main content

Simple IVR

Business Scenario​

Route callers to Sales or Support based on one digit. This pattern is useful when you want a small, testable call flow that can be expanded later. Start with the exact JSON shown here, verify it works with a test DID or outbound call, then add your own routing and customer lookup logic.

Call Flow Diagram​

Customer calls your DID
↓
MiniVoice asks for a digit
↓
Digit 1 transfers to Sales
↓
Digit 2 transfers to Support
↓
No input repeats or routes to a fallback in your application logic.

Webhook Flow​

call.created, call.answered, call.gathered, then call.completed. Store each webhook by call ID so your application can reconstruct the call journey after the call ends.

JSON Actions​

{
  "actions": [
    {
      "gather": {
        "prompt": "Press 1 for sales or 2 for support.",
        "num_digits": 1,
        "timeout_seconds": 5,
        "finish_on_key": "#"
      }
    },
    {
      "type": "redirect",
      "url": "https://example.com/minivoice/route-menu"
    }
  ]
}

Expected Result​

The caller hears a menu, enters a digit, and your webhook or redirect handler chooses the next destination. During manual testing, confirm the caller experience first, then confirm your application received the expected webhooks. For production use, add logging around every answer_url response and webhook handler so you can investigate individual call IDs quickly.

How To Adapt​

Replace example URLs with your HTTPS endpoints, replace phone numbers with verified destinations, and keep metadata values small and consistent. Test one change at a time: first answer_url, then webhook receiver, then call routing, then AI or recording features if the flow uses them.

Implementation Notes​

Before using this pattern with real callers, run it in a test application and capture the full webhook timeline. Confirm that the first webhook creates or updates your local call record, that action-specific webhooks update the current step, and that the terminal webhook closes the workflow.

Keep the example JSON small while you test. After the basic version works, add customer lookup, business hours checks, agent availability, or CRM updates one piece at a time. When a change breaks the caller experience, roll back to the last working JSON response and compare the webhook payloads.

A production version should include clear fallback behaviour. Decide what happens when a caller does not press a digit, a destination is busy, a webhook is retried, or recording and AI results arrive later than expected.

Copy/Paste Examples​

Real Request​

curl -sS https://api.minivoice.eu/v1/calls/call_123 \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY'

Real Response​

{
  "id": "call_123",
  "status": "completed",
  "direction": "outbound",
  "from": "+15551230001",
  "to": "+15551230002"
}

Real Webhook Example​

{
  "event": "call.completed",
  "created_at": "2026-05-29T12:10:00Z",
  "call": {
    "id": "call_123",
    "customer_id": "cust_123",
    "application_id": "app_123",
    "status": "completed",
    "direction": "inbound",
    "from": "+15551230001",
    "to": "+15551230002"
  },
  "variables": {},
  "data": {}
}

Common Use Case​

Use one known call ID to verify each integration test.

Common Failure Case​

{
  "error": {
    "code": "answer_url_error",
    "message": "invalid action payload"
  }
}

Use the error code for branching and log the full response body while testing.