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 in support of 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:

There are currently no webhooks associated with the Forking start command.

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, so that we humans can easily
   visually 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

    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.

    tx string

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

    stream_type string

    Possible values: [raw, decrypted]

    Default value: raw

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

    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 commands with the same "command_id".

Responses ​

200: Successful response

Schema

    result stringrequired

422: Error response

Schema

    code stringrequired
    title stringrequired
    detail stringrequired

Request samples

curl -L 'https://api.telnyx.com/calls/:call_control_id/actions/fork_start' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "target": "udp:186.52.113.6:9000",
  "rx": "186.52.113.6:9000",
  "tx": "186.52.113.6:9001",
  "stream_type": "decrypted",
  "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}'

Response samples

{
  "result": "ok"
}