Skip to main content

Call Flows

Call Flows are JSON instructions that allow you to programmatically handle calls.

What is a Flow URL?​

The Flow URL is an HTTPS endpoint that Teler uses to retrieve call flows.

info

For incoming calls, Teler will use the Incoming Call URL to retrieve call flows.

For outgoing calls, Teler will use the flow_url value provided while initiating the call using the HTTP API.

A typical request from Teler to your Flow URL has the following schema.

Method: POST

Content-Type: application/json

Request Body:

{
  "call_id": {CALL_ID},
  "account_id": {ACCOUNT_ID},
  "from_number": {FROM_NUMBER},
  "to_number": {TO_NUMBER},
  "direction": {CALL_DIRECTION}
}

Supported Flows​

Stream​

A Stream flow is used to start Media streams. It supports the following parameters.

  • ws_url (Required): The WebSocket URL where you want to receive the call media.
  • chunk_size: Size of the audio chunks streamed by Teler, in milliseconds. Must be a value between 20 and 2000, and a multiple of 20. Default is 400.
  • sample_rate: The sampling rate of audio chunks streamed by Teler, expressed in kHz. Must be one of either "8k" or "16k". Default is "8k".

Sample Flow​

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

To ensure smooth playback and prevent distorted or choppy audio, we recommend streaming audio chunks of at least 500 ms from your application to Teler.

Play​

A Play flow is used to play an audio file over the call. It supports the following parameters.

  • media_url (Required): A publicly accessible URL of the audio file.

Sample Flow​

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

Hangup​

A Hangup flow is used to disconnect a call. It does not support extra parameters.

Sample Flow​

{
  "action": "hangup"
}