AI Streaming (V3)

Stream your live call audio to your own WebSocket server in real time. Compared to the V2 streaming API, V3 adds stereo audio, a selectable sample rate, call direction filtering and your own custom variables.

Each API request in TeleCMI platform includes App id and secret. Get your App id and secret in TeleCMI dashboard. After getting the app id and secret, make a POST request to the below base URL to enable or disable streaming.

Base URL

Send your POST method request with valid parameters, to the following base URL.

https://rest.telecmi.com/v3/setting/stream

Required Parameters

These are the required POST method parameters with description

Parameter Name	Type	Description
*appid	number	Your app ID
*secret	string	Your app secret
*enable	boolean	Set to true to enable streaming or false to disable it. When false, all other parameters are ignored.
*ws_url	string	The WebSocket URL where the audio stream will be sent. Must start with ws:// or wss://. Required only when enable is true.

Optional Parameters

These parameters are optional. If you do not send them, the default value is used.

Parameter Name	Type	Default	Description
listen_mode	string	"caller"	Which part of the call audio is streamed caller: only the voice of the person who initiated the call. callee: only the voice of the person who received the call. both: the voices of both the caller and the callee.
audio_type	string	"mono"	Audio channel layout mono: single channel, both voices mixed together. stereo: two channels, caller on the left channel and callee on the right channel. Only allowed when listen_mode is "both".
sample_rate	string	"8k"	Audio quality of the generated stream 8k: 8000 Hz sample rate will be generated. 16k: 16000 Hz sample rate will be generated.
direction	string	"both"	Which calls are streamed inbound: stream only incoming calls. outbound: stream only outgoing calls. both: stream every call.
custom_variables	object	{}	Your own key and value pairs, for example a CRM ID or a team name. They are delivered to your WebSocket server along with the stream, so you can match the audio with your own records.

Note

All parameter values are case insensitive, so "STEREO" and "stereo" both work. An invalid value is rejected with an error, it is never silently replaced by the default.

Custom Variables Rules

Rule	Limit
Structure	Flat object only. Nested objects and arrays are not allowed.
Maximum keys	10
Key length	1 to 64 characters
Key format	Must not contain a dot . or start with a dollar sign $
Value types	string, number or boolean
Value length	Maximum 256 characters

Sample JSON Requests

Below are sample JSON POST method requests for the most common cases.

1. Basic streaming

Streams only the caller voice at 8000 Hz, for every call. This is the same behaviour as the V2 API.

{
    "appid": 2221121,
    "secret": "122xxxx-xxxx-xxxx-xxxx-xxxxa25",
    "enable": true,
    "ws_url": "wss://example.tcp.ngrok.url"
}

2. Stereo streaming with high quality audio

Streams both voices as stereo at 16000 Hz. The caller is on the left channel and the callee is on the right channel.

{
    "appid": 2221121,
    "secret": "122xxxx-xxxx-xxxx-xxxx-xxxxa25",
    "enable": true,
    "ws_url": "wss://example.tcp.ngrok.url",
    "listen_mode": "both",
    "audio_type": "stereo",
    "sample_rate": "16k"
}

3. Stream only incoming calls

Use direction when you want to stream one type of call only. Set it to "outbound" to stream only outgoing calls.

{
    "appid": 2221121,
    "secret": "122xxxx-xxxx-xxxx-xxxx-xxxxa25",
    "enable": true,
    "ws_url": "wss://example.tcp.ngrok.url",
    "listen_mode": "both",
    "direction": "inbound"
}

4. Streaming with custom variables

The values you send in custom_variables are delivered back to your WebSocket server, so you can link the audio to your own CRM record or team.

{
    "appid": 2221121,
    "secret": "122xxxx-xxxx-xxxx-xxxx-xxxxa25",
    "enable": true,
    "ws_url": "wss://example.tcp.ngrok.url",
    "listen_mode": "both",
    "audio_type": "stereo",
    "sample_rate": "16k",
    "direction": "inbound",
    "custom_variables": {
        "crm_id": "CRM-99871",
        "team": "sales",
        "region": "india",
        "priority": true
    }
}

5. Disable streaming

To turn streaming off, send enable as false. You do not need to send any other parameter.

{
    "appid": 2221121,
    "secret": "122xxxx-xxxx-xxxx-xxxx-xxxxa25",
    "enable": false
}

cURL example

curl -X POST https://rest.telecmi.com/v3/setting/stream \
  -H "Content-Type: application/json" \
  -d '{
    "appid": 2221121,
    "secret": "122xxxx-xxxx-xxxx-xxxx-xxxxa25",
    "enable": true,
    "ws_url": "wss://example.tcp.ngrok.url",
    "listen_mode": "both",
    "audio_type": "stereo",
    "sample_rate": "16k",
    "direction": "inbound",
    "custom_variables": { "crm_id": "CRM-99871", "team": "sales" }
  }'

Sample Response

If the provided information is valid, your web server will get a sample response from TeleCMI Platform as given below

{
    "code": 200,
    "msg": "Stream Enabled"
}

When you disable streaming, the response is

{
    "code": 200,
    "msg": "Stream Disabled"
}

Get Current Stream Settings

To read the stream settings that are currently saved for your app, make a POST request to the below base URL.

https://rest.telecmi.com/v3/setting/stream/get

Required Parameters

Parameter Name	Type	Description
*appid	number	Your app ID
*secret	string	Your app secret

Sample JSON Request

{
    "appid": 2221121,
    "secret": "122xxxx-xxxx-xxxx-xxxx-xxxxa25"
}

Sample Response

{
    "code": 200,
    "stream": {
        "stream": true,
        "ws_url": "wss://example.tcp.ngrok.url",
        "listen_mode": "both",
        "audio_type": "stereo",
        "sample_rate": 16000,
        "direction": "inbound",
        "custom_variables": {
            "crm_id": "CRM-99871",
            "team": "sales"
        },
        "version": 3
    }
}

Note

In the response the sample_rate is returned as a number, so "8k" is returned as 8000 and "16k" is returned as 16000. If streaming was never enabled for your app, the stream object is returned with "stream": false and no other settings inside it.

Audio Format Reference

Use this table to know what your WebSocket server will receive for each combination. The mix and sample_rate columns are the values your server gets as connection headers.

You send listen_mode	You send audio_type	You send sample_rate	Header mix	Header sample_rate	What your server receives
caller	mono	8k	mono	8000	One channel, caller voice only
callee	mono	8k	mono	8000	One channel, callee voice only
both	mono	8k	mixed	8000	One channel, caller and callee mixed together
both	stereo	8k	stereo	8000	Two channels, caller on left and callee on right
both	stereo	16k	stereo	16000	Two channels, caller on left and callee on right, high quality

Build Your WebSocket Server

Once streaming is enabled, the platform connects to your ws_url and sends the call audio. See Build Your Streaming Server for the connection headers your server receives, the audio format, and ready to run example code.

HTTP status codes

TeleCMI API platform represents the following status code to identity the errors.

Status code	Status type	Description
200	OK	Stream Enabled, Stream Disabled
403	Error	You dont have permission. Streaming is not enabled for your app
407	Error	Authentication Failed. Invalid app id or secret
500	Error	Invalid parameter, see the error messages below

Error messages

Message	Reason
Invalid Stream options	enable is missing or it is not a boolean
Invalid Stream URL	ws_url is missing or it does not start with ws:// or wss://
Invalid Listener Mode	listen_mode is not caller, callee or both
Invalid Audio Type	audio_type is not mono or stereo
Stereo requires listen_mode both	audio_type is stereo but listen_mode is not both
Invalid Sample Rate	sample_rate is not 8k or 16k
Invalid Direction	direction is not inbound, outbound or both
Invalid Custom Variables	custom_variables does not follow the custom variables rules given above

Sample Error Response

{
    "code": 500,
    "error": true,
    "msg": "Stereo requires listen_mode both"
}