Skip to main content

Transfer

Overview​

The transfer action moves the caller to another E.164 number or SIP URI. Use transfer for straightforward call forwarding, after-hours routing, and IVR menu destinations. Place it in the actions array returned by your answer_url. MiniVoice executes actions in order, so put transfer before the action that depends on its result and after any prompt or setup the caller should experience first.

Business Use Case​

Use transfer for call forwarding to a person, queue, or department number. A receptionist flow might gather a department choice and then transfer Sales callers to the sales desk.

JSON Example​

{
  "actions": [
    {
      "transfer": {
        "to": "+15551230099",
        "from": "+15551230001"
      }
    }
  ]
}

Parameters​

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

Execution Flow​

  1. MiniVoice validates the destination.
  2. It attempts to transfer the active call to that destination.
  3. When transfer begins, remaining actions after transfer are not executed.
  4. Call lifecycle webhooks continue to report final call outcome.

Webhook Behaviour​

No transfer-specific webhook is sent. Use call.completed or call.failed to track final outcome.

Success Example​

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

{
  "actions": [
    {
      "transfer": {
        "to": "+15551230099",
        "from": "+15551230001"
      }
    }
  ]
}

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

Failure Behaviour​

Invalid destinations are rejected. If the destination is unreachable, busy, or does not answer, the call can fail or complete depending on carrier behavior.

Expected Result​

MiniVoice attempts to connect the caller to the destination number. Final success or failure is reflected in normal call lifecycle status and webhook events.

Testing​

Start with a verified mobile number, then test a SIP URI. Confirm caller audio reaches the destination and your webhook receiver sees the final call event. During testing, log every webhook payload and compare the call ID, action timing, and final call status with the behavior you expected.

Integration guidance

Place this action in a short answer_url response first, then combine it with other actions after you have confirmed the single-action behaviour. Always log the answer_url response your application returned for the call. If the caller experience differs from what you expected, compare the logged response with the webhook timeline for that call ID.

When this action is part of a larger IVR, keep each step explicit. For example, play a prompt before collecting input, redirect after collecting input, and transfer only after your application has selected the final destination. This makes the flow easier to test and easier to change later.

For production integrations, build a fallback path. A caller may hang up, enter no digits, reach a busy destination, or disconnect before the flow completes. Your webhook handler should update the call record with the last known step so support teams can understand what happened.

Copy/Paste Examples​

Real Request​

Return this from your answer_url:

{
  "actions": [
    {
      "transfer": {
        "to": "+15551230099",
        "from": "+15551230001"
      }
    }
  ]
}

Real Response​

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

{
  "actions": [
    {
      "transfer": {
        "to": "+15551230099",
        "from": "+15551230001"
      }
    }
  ]
}

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 transfer for call forwarding to a person, queue, or department number. A receptionist flow might gather a department choice and then transfer Sales callers to the sales desk.

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.