Call Flows

A Call Flow is the JSON your server returns when Teler asks what to do on a call. Teler POSTs a request to your flow URL with call metadata; you respond with a flow describing one action: stream, play, hangup or dial.

Mental model

⤢

For incoming calls Teler hits the Incoming Call URL on the Voice App. For outgoing calls Teler hits the flow_url you passed to voice.calls.create().

What Teler sends

Teler’s request to your flow endpoint:

POST /flow
Content-Type: application/json

The field set is identical on both webhook versions, but the call_id and account_id formats depend on the pin of the owning Voice App / SIP Trunk. Parse them accordingly.

2026-06-01

{
  "call_id":     "cs_01H...",
  "account_id":  "acc_01H...",
  "from_number": "+91XXXXXXXXXX",
  "to_number":   "+91XXXXXXXXXX",
  "direction":   "inbound"
}

call_id and account_id are prefixed, resource-typed IDs (cs_…, acc_…). The call_id here matches the call_id in 2026-06-01 webhooks for the same call.

2025-08-01

{
  "call_id":     "<uuid>",
  "account_id":  "<uuid>",
  "from_number": "+91XXXXXXXXXX",
  "to_number":   "+91XXXXXXXXXX",
  "direction":   "inbound"
}

call_id and account_id are raw UUIDs — the same raw values that appear in 2025-08-01 webhooks for the same call.

Field	Type	Description
call_id	UUID (2025-08-01) / prefixed ID cs_… (2026-06-01)	Unique ID for this call. Use it to correlate with webhooks — the format matches the webhooks fired on the same pin.
account_id	UUID (2025-08-01) / prefixed ID acc_… (2026-06-01)	Your Teler account.
from_number	string (E.164)	Calling party.
to_number	string (E.164)	Called party.
direction	enum	"inbound" or "outbound" (same values on both versions).

Your endpoint must respond within 5 seconds with 200 OK and a Call Flow body.

The call_id and account_id formats above depend on the webhook version pinned to the owning resource; see API versioning for the full identifier scheme. The response below also depends on the version — its available actions differ.

Actions

A Call Flow body is a single JSON object with an action field. Teler executes exactly one action per flow request. Availability by webhook version:

Action	2025-08-01	2026-06-01
stream	Yes	Yes
play	Yes	Yes
hangup	Yes	Yes
dial	No	Yes

See API versioning to change the pin on your Voice App or SIP Trunk.

The flow endpoint accepts a single JSON object (one action). Arrays of actions are rejected.

stream

Open a bidirectional WebSocket carrying real-time call audio.

Field	Type	Required	Default	Constraints
action	string	yes	must be provided	Must be "stream".
ws_url	string	yes	must be provided	Secure WebSocket URL (wss://).
chunk_size	integer	no	400	Audio chunk size in milliseconds. Range: 20 to 2000, and must be divisible by 20.
sample_rate	enum	no	"8k"	"8k" or "16k".

{
  "action": "stream",
  "ws_url": "wss://yourdomain.com/media-stream",
  "chunk_size": 1000,
  "sample_rate": "16k"
}

Tip

chunk_size and sample_rate configure only the audio Teler streams to your ws_url. They don’t affect the audio your application sends back over the same connection. Smaller chunks reduce latency but increase WebSocket overhead; for most conversational use cases, 400 to 1000 ms chunks are a good balance.

Note

Teler requires 8k (8000 Hz) sample rate as input, so downsample accordingly before sending audio to Teler.

See Media Streaming for the WebSocket protocol Teler uses on this connection.

play

Play an audio file into the call.

Field	Type	Required	Constraints
action	string	yes	Must be "play".
media_url	string	yes	Publicly reachable HTTPS URL serving an MP3 or WAV file.

{
  "action": "play",
  "media_url": "https://example.com/media-file.mp3"
}

hangup

End the call immediately.

Field	Type	Required	Constraints
action	string	yes	Must be "hangup".

{
  "action": "hangup"
}

dial

Originate an outbound leg and bridge it into the current call. Available only on webhook version 2026-06-01. Full schema and examples: dial.

{
  "action": "dial",
  "to":     "+14155550123"
}

Response requirements

Constraint	Value
Status code	200 OK
Content-Type	application/json
Response time	≤ 5 seconds
Body	Single JSON object with one action

If your endpoint times out, returns a non-2xx, or returns invalid JSON, the call ends and a call.failed webhook is delivered.

Next steps

Voice Apps Configure the Incoming Call URL Teler uses to fetch flows.

Media Streaming Stream call audio over a WebSocket in real time.

Call Webhooks Lifecycle events sent to your Call Status URL.