Skip to main content

Hold

Overview​

The hold action places the call on hold. Use it before a supervised routing step, when waiting for an agent, or while your app prepares the next action. Place it in the actions array returned by your answer_url. MiniVoice executes actions in order, so put hold before the action that depends on its result and after any prompt or setup the caller should experience first.

Business Use Case​

Use hold when a caller should wait while your application prepares a transfer, starts a conference, or performs a short routing step.

JSON Example​

{
  "actions": [
    {
      "hold": {}
    }
  ]
}

Parameters​

FieldTypeRequiredDescription
typestringYesMust be hold when using typed action format.

Execution Flow​

  1. MiniVoice reaches the hold action.
  2. The active call is placed on hold.
  3. MiniVoice continues to the next action when one is present.
  4. Use resume later in the flow to return audio to normal.

Webhook Behaviour​

No action-specific webhook is sent for hold. Normal call lifecycle webhooks continue.

Success Example​

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

{
  "actions": [
    {
      "hold": {}
    }
  ]
}

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

Failure Behaviour​

Hold can fail if the call is already ended or cannot accept media changes. Keep hold and resume near each other in flows that need predictable caller experience.

Expected Result​

The call is placed on hold until a later action resumes or redirects the flow. Your application should keep hold periods short and caller-friendly.

Testing​

Return hold followed by a short wait-style flow or resume action. Confirm the caller experiences hold behavior and then resumes. 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": [
    {
      "hold": {}
    }
  ]
}

Real Response​

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

{
  "actions": [
    {
      "hold": {}
    }
  ]
}

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 hold when a caller should wait while your application prepares a transfer, starts a conference, or performs a short routing step.

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.