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 (see callback schema below):
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
Unique identifier and token for controlling the call
- application/json
Body
required
Fork media request
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.
The network target, udp:ip_address:port, where the call's incoming RTP media packets should be forwarded.
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.
The network target, udp:ip_address:port, where the call's outgoing RTP media packets should be forwarded.
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded 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.
- application/json
default: Unexpected error
- application/json
Request samples
curl -L 'https://api.telnyx.com/v2/calls/:call_control_id/actions/fork_start' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
"target": "udp:192.0.2.1:9000",
"rx": "udp:192.0.2.1:9000",
"tx": "udp:192.0.2.1:9001",
"client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
"command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}'
Response samples
{
"data": {
"result": "ok"
}
}
{
"errors": [
{
"code": "string",
"title": "string",
"detail": "string",
"source": {
"pointer": "string",
"parameter": "string"
},
"meta": {}
}
]
}