Recording start

POST 
/calls/:call_control_id/actions/record_start

Start recording the call. Recording will stop on call hang-up, or can be initiated via the Stop Recording command.

Expected Webhooks (see callback schema below):

• call.recording.saved

Path Parameters

call_control_id stringrequired

Unique identifier and token for controlling the call

application/json

Body

required

Start recording audio request

format stringrequired

Possible values: [wav, mp3]

The audio file format used when storing the call recording. Can be either mp3 or wav.

channels stringrequired

Possible values: [single, dual]

When dual, final audio file will be stereo recorded with the first leg on channel A, and the rest on channel B.

client_state string

Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.

command_id string

Use this field to avoid duplicate commands. Telnyx will ignore any command with the same command_id for the same call_control_id.

play_beep boolean

If enabled, a beep sound will be played at the start of a recording.

max_length int32

Default value: 0

Defines the maximum length for the recording in seconds. The minimum value is 0. The maximum value is 14400. The default value is 0 (infinite)

timeout_secs int32

Default value: 0

The number of seconds that Telnyx will wait for the recording to be stopped if silence is detected. The timer only starts when the speech is detected. Please note that call transcription is used to detect silence and the related charge will be applied. The minimum value is 0. The default value is 0 (infinite)

recording_track string

Possible values: [both, inbound, outbound]

Default value: both

The audio track to be recorded. Can be either both, inbound or outbound. If only single track is specified (inbound, outbound), channels configuration is ignored and it will be recorded as mono (single channel).

trim string

Possible values: [trim-silence]

When set to trim-silence, silence will be removed from the beginning and end of the recording.

custom_file_name string

Possible values: non-empty and <= 40 characters

The custom recording file name to be used instead of the default call_leg_id. Telnyx will still add a Unix timestamp suffix.

transcription boolean

Enable post recording transcription. The default value is false.

transcription_engine string

Possible values: [A, B]

Default value: A

Engine to use for speech recognition. A - Google, B - Telnyx.

transcription_language

object

oneOf

• Google transcription engine list of languages
• Telnyx transcription engine list of languages

Language to use for speech recognition

string

Possible values: [af, sq, am, ar, hy, az, eu, bn, bs, bg, my, ca, yue, zh, hr, cs, da, nl, en, et, fil, fi, fr, gl, ka, de, el, gu, iw, hi, hu, is, id, it, ja, jv, kn, kk, km, ko, lo, lv, lt, mk, ms, ml, mr, mn, ne, no, fa, pl, pt, pa, ro, ru, rw, sr, si, sk, sl, ss, st, es, su, sw, sv, ta, te, th, tn, tr, ts, uk, ur, uz, ve, vi, xh, zu]

Language to use for speech recognition

string

Possible values: [en, zh, de, es, ru, ko, fr, ja, pt, tr, pl, ca, nl, ar, sv, it, id, hi, fi, vi, he, uk, el, ms, cs, ro, da, hu, ta, no, th, ur, hr, bg, lt, la, mi, ml, cy, sk, te, fa, lv, bn, sr, az, sl, kn, et, mk, br, eu, is, hy, ne, mn, bs, kk, sq, sw, gl, mr, pa, si, km, sn, yo, so, af, oc, ka, be, tg, sd, gu, am, yi, lo, uz, fo, ht, ps, tk, nn, mt, sa, lb, my, bo, tl, mg, as, tt, haw, ln, ha, ba, jw, su, auto_detect]

200: Successful response upon making a call control command.

application/json

• Schema
• Example (from schema)

Schema

data

object

result string

{
  "data": {
    "result": "ok"
  }
}

default: Unexpected error

application/json

• Schema
• Example (from schema)

Schema

errors

Error[]

Array [

code integerrequired

title stringrequired

detail string

source

object

pointer json-pointer

JSON pointer (RFC6901) to the offending entity.

parameter string

Indicates which query parameter caused the error.

meta object

]

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}

Request samples

• cURL

---

curl -L 'https://api.telnyx.com/v2/calls/:call_control_id/actions/record_start' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
  "format": "wav",
  "channels": "single",
  "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  "play_beep": true,
  "max_length": 0,
  "timeout_secs": 0,
  "transcription": true,
  "transcription_engine": "B",
  "transcription_language": "en-US"
}'

Response samples

• 200
• default

---

{
  "data": {
    "result": "ok"
  }
}

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}