Skip to main content

Gather

Overview​

The gather action collects DTMF digits from the caller. Use it to build IVR menus, collect simple confirmation codes, or choose a routing path. Place it in the actions array returned by your answer_url. MiniVoice executes actions in order, so put gather before the action that depends on its result and after any prompt or setup the caller should experience first.

Business Use Case​

Use gather to build a simple IVR such as Sales versus Support routing. The caller hears a prompt, presses one digit, and your webhook or redirected answer_url uses that digit to choose the next destination.

JSON Example​

{
  "actions": [
    {
      "gather": {
        "prompt": "Press 1 for Sales or 2 for Support.",
        "num_digits": 1,
        "timeout_seconds": 5,
        "finish_on_key": "#"
      }
    }
  ]
}

Parameters​

FieldTypeRequiredDescription
promptstringNoOptional text prompt to play before listening for digits.
num_digitsnumberNoNumber of digits to collect. Defaults to one when not supplied.
max_digitsnumberNoMaximum digits to collect.
min_digitsnumberNoMinimum digits required before completion.
timeout_secondsnumberNoHow long to wait for input. Must be between one and thirty seconds.
finish_on_keystringNoOne DTMF key that ends input early, often #.

Execution Flow​

  1. MiniVoice plays the prompt when provided.
  2. MiniVoice listens for DTMF input until enough digits are collected, finish_on_key is pressed, the caller hangs up, or timeout_seconds is reached.
  3. The gathered digits are added to the gather event payload.
  4. Your webhook handler can use the digits to update state, log intent, or return different actions through redirect.

Webhook Behaviour​

MiniVoice sends call.gathered after the gather action completes or times out. The event includes digits, status, timed_out, min_digits, max_digits, timeout_seconds, and finish_on_key.

Success Example​

A successful answer_url response includes the action in a valid actions array:

{
  "actions": [
    {
      "gather": {
        "prompt": "Press 1 for Sales or 2 for Support.",
        "num_digits": 1,
        "timeout_seconds": 5,
        "finish_on_key": "#"
      }
    }
  ]
}

Your application should store the MiniVoice call ID from webhooks or API responses so you can correlate the action with the call.

Failure Behaviour​

If the caller enters no digits before timeout, call.gathered is still sent with timed_out true. Invalid gather parameters cause the answer_url payload to be rejected.

Expected Result​

MiniVoice collects the digit and sends call.gathered with the collected value. Your application can store the selected department and continue the call flow through a later redirect or transfer.

Testing​

Use a test phone to call your DID. Press each menu digit and verify your webhook receives call.gathered with the expected digits. Repeat with no input to confirm timeout handling. During testing, log every webhook payload and compare the call ID, action timing, and final call status with the behavior you expected.

Copy/Paste Examples​

Real Request​

Return this from your answer_url:

{
  "actions": [
    {
      "gather": {
        "prompt": "Press 1 for Sales or 2 for Support.",
        "num_digits": 1,
        "timeout_seconds": 5,
        "finish_on_key": "#"
      }
    }
  ]
}

Real Response​

A valid answer_url response is the JSON action payload itself. MiniVoice accepts the response when it contains an actions array:

{
  "actions": [
    {
      "gather": {
        "prompt": "Press 1 for Sales or 2 for Support.",
        "num_digits": 1,
        "timeout_seconds": 5,
        "finish_on_key": "#"
      }
    }
  ]
}

Real Webhook Example​

{
  "event": "call.gathered",
  "created_at": "2026-05-29T12:00:10Z",
  "call": {
    "id": "call_123",
    "status": "in_progress",
    "direction": "inbound",
    "from": "+15551230001",
    "to": "+15551230002"
  },
  "variables": {},
  "data": {
    "step": 0,
    "digits": "1",
    "status": "completed",
    "timed_out": false
  }
}

Common Use Case​

Use gather to build a simple IVR such as Sales versus Support routing. The caller hears a prompt, presses one digit, and your webhook or redirected answer_url uses that digit to choose the next destination.

Common Failure Case​

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

Invalid fields or malformed JSON cause MiniVoice to reject the answer_url payload. Log the exact response your server returned while testing.