Media streams

A media stream connection lets a partner’s contact-centre platform (SparkTG, Twilio, Plivo, Exotel or Vonage) keep its own numbers and stream each call’s audio to one of your voice agents over one WebSocket per call. The partner keeps the number, IVR, queue and CRM; Talqing runs the agent. Create one with POST /v1/streams and hand the partner the url it returns. Use it when the other side will not move a number onto a SIP trunk. Compared with a Talqing phone number, a stream agent cannot transfer to a human, and on every platform but SparkTG it cannot hang up.

Create a connection

The agent must be a published voice agent. In the dashboard: Telephony → Media Streams → New connection.

curl -X POST https://api.talqing.com/v1/streams \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SparkTG - Acme support line",
    "dialect": "sparktg",
    "agent_id": "81399608-4930-4ff1-9281-f1f4932d1999",
    "region": "in"
  }'

const connection = await talqing.telephony.streams.create({
  createStreamConnectionRequest: {
    name: "SparkTG - Acme support line",
    dialect: "sparktg",
    agent_id: "81399608-4930-4ff1-9281-f1f4932d1999",
    region: "in",
  },
});
console.log(connection.url);

connection = talqing.telephony.streams.create(
    name="SparkTG - Acme support line",
    dialect="sparktg",
    agent_id="81399608-4930-4ff1-9281-f1f4932d1999",
    region="in",
)
print(connection["url"])

The response (201) carries the full url on this and every later read. The dashboard’s setup panel has the partner-side steps and, for Twilio, Plivo and Vonage, a snippet to paste.

Platforms

dialect decides what the agent can do on the call.

`dialect`	Partner connects with	Agent can hang up	Agent can press keys	Caller’s number on the stream
`sparktg`	A URL configured per tenant at onboarding	Yes	Yes	Yes
`twilio`	`<Connect><Stream>` in TwiML	No	No	No
`plivo`	`<Stream bidirectional="true">` in XML	No	Yes	No
`exotel`	A Voicebot applet in the call flow	No	No	Yes
`vonage`	A `connect` action in an NCCO	No	No	No

On every platform but SparkTG, the agent finishing does not hang up. The stream closes and the caller returns to the partner’s flow. On Twilio and Vonage, if nothing follows the stream, the caller hears silence. Put the next step there: the TwiML verb after </Connect>, the next applet, or the next NCCO action. That is also where escalation to a person belongs.

The URL

wss://streams.{region}.talqing.com/v1/streams/connect/{dialect}/{workspace_id}/{agent_id}

region is us (default) or in. Pick the one nearest the partner’s media. Changing region changes the URL; the old host stops answering for the connection, so the partner must switch. URLs on streams.talqing.com are us.
Everything is in the path because Twilio’s <Stream url> allows no query string.
One connection per agent per dialect. Two partners on the same platform would share one URL, so give each its own agent.

The URL is not a credential and cannot be rotated. It is derived from the dialect, workspace and agent, so deleting and recreating the connection returns the same URL. Anyone holding it can place calls against your credit balance and question the agent. To stop it answering, set status: "disabled" with PATCH /v1/streams/{connection_id} or point the connection at another agent. Disabling refuses new calls at once; calls in progress continue.

Per-call metadata becomes `vars`

The platform’s per-call bag (Twilio <Parameter>, SparkTG SIP-header attributes, Plivo extraHeaders, Exotel query parameters, Vonage NCCO headers) is passed through verbatim: a key svcId reaches the agent as {{vars.svcId}}. A key that is not a valid variable name (a hyphen, a leading digit) is skipped and noted on the call’s timeline. See variables. Three keys also set call facts:

Key	Effect
`from`	The calling party’s number.
`to`	The called party’s number.
`direction`	`inbound` or `outbound` (Twilio’s `outbound-api` / `outbound-dial` accepted). Fills `{{system_vars.direction}}`; absent when not sent.

The person is from, or to when direction is outbound. Their number fills {{system_vars.human_phone_number}} and groups the call into their conversation; the other fills {{system_vars.agent_phone_number}}. A value that is not a phone number (anonymous, an unfilled placeholder) is ignored and the caller is treated as unidentified. Plivo and Vonage may send digits without +.

Twilio, Plivo and Vonage put no numbers on the stream. Without from in the metadata every call is anonymous: no caller number for the agent, no history across calls. The dashboard’s Twilio snippet passes {{From}}, {{To}} and {{Direction}} from a TwiML Bin; a partner serving TwiML from its own webhook must substitute them itself.

How a stream call differs from a phone call

A stream call is a voice call with type STREAM in Calls: transcribed, analysed and recorded per the agent’s settings, billed at the voice platform fee plus your provider spend, capped at three hours. Differences:

No transfer. A transfer operation fails on a stream; route escalation through the partner’s flow.
Background audio is off (ambient and thinking sounds). The agent’s voice is unaffected.
Keypad is out of band only; tones inside the audio are not detected. See keypad input.
A Talqing release ends calls in progress with close reason “The call was ended by a Talqing deployment”. Those calls carry no platform fee.
No per-connection concurrency cap. Only an empty credit balance refuses calls.

Audio formats

The platform announces the format per call; nothing to configure.

Format	Platforms
G.711 μ-law, 8 kHz	Twilio (always), Plivo
16-bit linear PCM, 8/16/24 kHz	SparkTG, Plivo, Exotel, Vonage
Opus	Refused, with an error naming it.

Unidirectional (listen-only) streams are not supported.

Connection reference

Field	Values
`name`	1–120 characters.
`dialect`	`sparktg`, `twilio`, `plivo`, `exotel`, `vonage`.
`agent_id`	The voice agent that answers. Changeable with `PATCH`.
`region`	`us` (default) or `in`. Changeable with `PATCH`; changes `url`.
`status`	`active` or `disabled`.
`readiness`	`live`, `needs_agent` (agent never published), `disabled`.
`url`	The WebSocket URL to give the partner.

GET /v1/streams lists connections; DELETE /v1/streams/{connection_id} removes one and keeps the calls it carried.

Debugging

Symptom	Cause
Calls never connect, nothing in Calls	The partner abandoned the call before the WebSocket handshake finished (SparkTG allows 5 seconds). Check the URL is reachable from outside your network.
Handshake refused with `403`	The URL names no connection (check dialect and agent segments), or the connection is disabled.
Call connects and ends at once	The agent was never published, or the workspace has no credit. The call shows as failed with the reason.
Agent speaks, then silence	The stream closed and nothing follows it in the partner’s flow.
Static	Sample-rate or byte-order mismatch on the partner’s side. The call detail shows the negotiated format.
Agent missed words	Audio arrived late after a network stall and was dropped. The call’s timeline says how much.
`{{vars.x}}` is empty	The key was missing or not a valid variable name; the timeline lists both.

Keypad input

Digits the caller types and digits the agent presses.

Telephony overview

Answering calls on your own carrier numbers instead.

Get started

Build

Guides

Create a connection

Platforms

The URL

Per-call metadata becomes `vars`

How a stream call differs from a phone call

Audio formats

Connection reference

Debugging

Next

Keypad input

Telephony overview

​Create a connection

​Platforms

​The URL

​Per-call metadata becomes vars

​How a stream call differs from a phone call

​Audio formats

​Connection reference

​Debugging

​Next

Keypad input

Telephony overview

Create a connection

Platforms

The URL

Per-call metadata becomes `vars`

How a stream call differs from a phone call

Audio formats

Connection reference

Debugging

Next