voice

Start a two-party telephony bridge

Business-first two-party bridge: dials the business number, navigates its IVR (optional single-step DTMF plan), confirms a live human answered via Premium AMD, speaks an AI prep line, then dials the consumer and bridges both legs. Requires the voice:bridge scope. Gated by a server feature flag: returns 503 when disabled.

post/voice/bridge

Request

  • Base URL: https://corebee.ai/api/v1
  • URL: https://corebee.ai/api/v1/voice/bridge
  • Auth: HTTP bearer

Request body

business_numberstring required

E.164 number dialed FIRST (the business).

consumer_numberstring required

E.164 number dialed only after a live human is confirmed on the business leg.

from_numberstring

Optional E.164 caller-ID. Must be a Telnyx DID owned by the credential org; a default connected DID is used when omitted.

prep_linestring

Optional short line about why the consumer is calling. On the AI-conversation leg it becomes the agent's reasonForCall: spoken as soon as the business agrees to help, before the consumer is bridged in. ⚠️ ONLY THE FIRST ~180 CHARACTERS ARE SPOKEN ON THAT LEG. Longer text is cut at the last sentence boundary inside that budget (or, failing one, at a word boundary), so anything after it is never heard: measured on live traffic, prep lines average ~300 characters and ~40% of the text was discarded unannounced. Put the specifics the person answering needs, the vehicle, the request, the reference, in the FIRST sentence. The full text IS spoken on a briefing-only call (up to 500 characters, in the closing message) and on the legacy leg, verbatim with the required AI-disclosure prefixed.

idempotency_keystring

Optional client key ([A-Za-z0-9._:-]). Reusing a key for a live session returns 409 with a reference to the existing session.

request_recording_consentboolean

Optional. The A/B toggle for consumer recording on THIS call. When true AND consumer recording is enabled server-side, the consumer hears a spoken recording-consent disclosure before being bridged; if they stay on the line (implied consent) the bridged consumer<->business conversation is recorded and transcribed, and if they hang up during the disclosure the call is simply not recorded (it is never dropped for declining). Necessary but NOT sufficient: recording is additionally gated by a server-side flag that is OFF by default pending legal sign-off, so in current production this field records nothing and the bridge is byte-identical whether it is true or false. Default false is the control arm. A non-boolean value is rejected with 400 validation_error.

briefing_onlyboolean

Optional test flag. When true the business is dialed and AMD-verified and the prep line is spoken, then the session COMPLETES without ever dialing the consumer and without bridging, so nothing is billed and no second person is called. Absent or false is the full production flow. A non-boolean value is a 400 validation_error, never coerced. Note that briefing-only sessions are excluded from GET /voice/bridge/usage, including from its total.

metadataobject

Free-form bag echoed back on the status projection. customer_ref (string, <=255 chars) is the one key we treat specially: it is your correlation id, it is echoed on webhooks and on the usage feed, and it is what customer_ref= filters on. No other key in here is interpreted.

Example request

{
  "business_number": "+15551230000",
  "consumer_number": "+15559874444",
  "from_number": "+17635550123",
  "dtmf_plan": [
    {
      "digits": "2",
      "wait_ms": 3000
    }
  ],
  "consent": {
    "method": "web_form",
    "captured_at": "2026-08-20T16:04:00Z",
    "reference": "consent_9f31c2"
  }
}

Response

Created

Example response

{
  "data": {
    "id": 4021,
    "state": "dialing_business",
    "business_number": "+15551230000",
    "consumer_number": "+15559874444",
    "status_url": "/api/v1/voice/bridge/4021"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.