Skip to main content

Bridge

Overview​

The bridge action connects the current caller to another destination while MiniVoice keeps call context. Use bridge when you want a controlled connection between the original call and a second leg. Place it in the actions array returned by your answer_url. MiniVoice executes actions in order, so put bridge before the action that depends on its result and after any prompt or setup the caller should experience first.

Business Use Case​

Use bridge when your application needs to connect the active caller to another destination while preserving a controlled call flow. This fits call-forwarding products and receptionist escalation flows.

JSON Example​

{
  "actions": [
    {
      "bridge": {
        "to": "+15551230099",
        "from": "+15551230001",
        "timeout_seconds": 20
      }
    }
  ]
}

Parameters​

FieldTypeRequiredDescription
typestringYesMust be bridge when using typed action format.
destinationstringYesE.164 phone number or SIP URI to bridge.

Execution Flow​

  1. MiniVoice validates the bridge destination.
  2. It starts a second call leg to the destination.
  3. When the destination answers, MiniVoice connects both legs.
  4. Actions after bridge are not run because the call is now connected to the bridge destination.

Webhook Behaviour​

No bridge-specific webhook is sent. Track the call with normal lifecycle webhooks.

Success Example​

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

{
  "actions": [
    {
      "bridge": {
        "to": "+15551230099",
        "from": "+15551230001",
        "timeout_seconds": 20
      }
    }
  ]
}

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

Failure Behaviour​

Busy, no-answer, invalid SIP URI, and unreachable destination should be handled by your call flow and monitoring. Use a fallback redirect or transfer flow when your business process requires it.

Expected Result​

MiniVoice dials the bridge destination and connects audio when the destination answers. Busy or no-answer outcomes should be handled as failure paths in your application.

Testing​

Bridge to a test SIP endpoint and to a phone number. Verify audio in both directions and capture final call status in your webhook logs. 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": [
    {
      "bridge": {
        "to": "+15551230099",
        "from": "+15551230001",
        "timeout_seconds": 20
      }
    }
  ]
}

Real Response​

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

{
  "actions": [
    {
      "bridge": {
        "to": "+15551230099",
        "from": "+15551230001",
        "timeout_seconds": 20
      }
    }
  ]
}

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 bridge when your application needs to connect the active caller to another destination while preserving a controlled call flow. This fits call-forwarding products and receptionist escalation flows.

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.