Skip to main content

Forking start

POST 
/calls/:call_control_id/actions/fork_start

Call forking allows you to stream the media from a call to a specific target in realtime. This stream can be used to enable realtime audio analysis to support a variety of use cases, including fraud detection, or the creation of AI-generated audio responses. Requests must specify either the target attribute or the rx and tx attributes.

Expected Webhooks:

  • call.fork.started
  • call.fork.stopped

Simple Telnyx RTP Encapsulation Protocol (STREP)

Note: This header/encapsulation is not used when the rx and tx parameters have been specified; it only applies when media is forked using the target attribute.

If the destination for forked media is specified using the "target" attribute, the RTP will be encapsulated in an extra Telnyx protocol, which adds a 24 byte header to the RTP payload in each packet. The STREP header includes the Call Control call_leg_id for stream identification, along with bits that represent the direction (inbound or outbound) of the media. This 24-byte header sits between the UDP header and the RTP header.

The STREP header makes it possible to fork RTP for multiple calls (or two RTP streams for the same call) to the same IP:port, where the streams can be demultiplexed by your application using the information in the header. Of course, it's still possible to ignore this header completely, for example, if sending forked media for different calls to different ports or IP addresses. In this case, simply strip 24 bytes (or use the second byte to find the header length) from the received UDP payload to get the RTP (RTP header and payload).

STREP Specification

  0                   1                   2                   3
  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |1 1|Version|L|D|    HeaderLen  |  reserved (2 bytes)           |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |       reserved (4 bytes, for UDP ports or anything else)      |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |               The call_leg_id                                 |
 |                   from Call Control                           |
 |                       (128 bits / 16 bytes)                   |
 |                           (this is binary data)               |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

 11
   Static bits 11, always set to 11 to easily distinguish forked media
   from RTP (10) and T.38 media (usually 00) and SIP (which begins
   with a capital letter, so begins with bits 01). This is a magic number.

 Version
   Four bits to indicate the version number of the protocol, starting at 0001.

 L
   One bit to represent the leg of the call (A or B).
   0 represents the A (first) leg of the call.
   1 represents the B (second) leg of the call.

 D
   One bit to represent the direction of this RTP stream.
   0 represents media received by Telnyx.
   1 represents media transmitted by Telnyx.

 HeaderLen (1 byte)
   The length of the header in bytes.
   Note that this value does not include the length of the payload. The total
   size of the RTP can be calculated by subtracting the HeaderLen from the UDP
   length (minus 8 for the UDP header).
   In version 1, this value will always be 24.

 Reserved (6 bytes)
   Reserved for future use and to make sure that the header is a multiple of 32 bits

 Call Leg ID
   A 128-bit identifier for the call leg.
   This is the call_leg_id from Call Control.

Request​

Path Parameters

    call_control_id stringrequired

    Unique identifier and token for controlling the call

Body

required

Fork media request

    target string

    The network target, udp:ip_address:port, where the call's RTP media packets should be forwarded. Both incoming and outgoing media packets will be delivered to the specified target, and information about the stream will be included in the encapsulation protocol header, including the direction (0 = inbound; 1 = outbound), leg (0 = A-leg; 1 = B-leg), and call_leg_id.

    rx string

    The network target, udp:ip_address:port, where the call's incoming RTP media packets should be forwarded.

    stream_type string

    Possible values: [raw, decrypted]

    Default value: raw

    Optionally specify a media type to stream. If decrypted selected, Telnyx will decrypt incoming SIP media before forking to the target. rx and tx are required fields if decrypted selected.

    tx string

    The network target, udp:ip_address:port, where the call's outgoing RTP media packets should be forwarded.

    client_state string

    Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.

    command_id string

    Use this field to avoid duplicate commands. Telnyx will ignore any command with the same command_id for the same call_control_id.

Responses​

200: Successful response upon making a call control command.

Schema

    data

    object

    result string

default: Unexpected error

Schema

    errors

    Error[]

  • Array [

    • code integerrequired
    title stringrequired
    detail string

    source

    object

    pointer json-pointer

    JSON pointer (RFC6901) to the offending entity.

    parameter string

    Indicates which query parameter caused the error.

    meta object

  • ]

Callbacks​

Loading...