Answer call

POST 
/calls/:call_control_id/actions/answer

Answer an incoming call. You must issue this command before executing subsequent commands on an incoming call.

Expected Webhooks (see callback schema below):

• call.answered
• streaming.started, streaming.stopped or streaming.failed if stream_url was set

Path Parameters

call_control_id stringrequired

Unique identifier and token for controlling the call

application/json

Body

required

Answer call request

billing_group_id uuid

Use this field to set the Billing Group ID for the call. Must be a valid and existing Billing Group ID.

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.

custom_headers

object[]

Custom headers to be added to the SIP INVITE response.

Array [

name stringrequired

The name of the header to add.

value stringrequired

The value of the header.

]

Custom headers to be added to the SIP INVITE response.

preferred_codecs string

Possible values: [G722,PCMU,PCMA,G729,OPUS,VP8,H264]

The list of comma-separated codecs in a preferred order for the forked media to be received.

sip_headers

object[]

SIP headers to be added to the SIP INVITE response. Currently only User-to-User header is supported.

Array [

name stringrequired

Possible values: [User-to-User]

The name of the header to add.

value stringrequired

The value of the header.

]

SIP headers to be added to the SIP INVITE response. Currently only User-to-User header is supported.

sound_modifications

object

Use this field to modify sound effects, for example adjust the pitch.

pitch double

Set the pitch directly, value should be > 0, default 1 (lower = lower tone)

semitone double

Adjust the pitch in semitones, values should be between -14 and 14, default 0

octaves double

Adjust the pitch in octaves, values should be between -1 and 1, default 0

track string

Default value: outbound

The track to which the sound modifications will be applied. Accepted values are inbound or outbound

Use this field to modify sound effects, for example adjust the pitch.

stream_url string

The destination WebSocket address where the stream is going to be delivered.

stream_track string

Possible values: [inbound_track, outbound_track, both_tracks]

Default value: inbound_track

Specifies which track should be streamed.

stream_bidirectional_mode Stream Bidirectional Mode (string)

Possible values: [mp3, rtp]

Default value: mp3

Configures method of bidirectional streaming (mp3, rtp).

stream_bidirectional_codec Stream Bidirectional Codec (string)

Possible values: [PCMU, PCMA, G722]

Default value: PCMU

Indicates codec for bidirectional streaming RTP payloads. Used only with stream_bidirectional_mode=rtp. Case sensitive.

stream_bidirectional_target_legs Stream Bidirectional Target Legs (string)

Possible values: [both, self, opposite]

Default value: opposite

Specifies which call legs should receive the bidirectional stream audio.

send_silence_when_idle boolean

Generate silence RTP packets when no transmission available.

webhook_url string

Use this field to override the URL for which Telnyx will send subsequent webhooks to for this call.

webhook_url_method string

Possible values: [POST, GET]

Default value: POST

HTTP request type used for webhook_url.

transcription boolean

Enable transcription upon call answer. The default value is false.

transcription_config

object

transcription_engine string

Possible values: [A, B]

Default value: A

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

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]

interim_results boolean

Whether to send also interim results. If set to false, only final results will be sent. Applies to google engine only.

enable_speaker_diarization boolean

Enables speaker diarization. Applies to google engine only.

min_speaker_count int32

Default value: 2

Defines minimum number of speakers in the conversation. Applies to google engine only.

max_speaker_count int32

Default value: 6

Defines maximum number of speakers in the conversation. Applies to google engine only.

client_state string

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

transcription_tracks string

Default value: inbound

Indicates which leg of the call will be transcribed. Use inbound for the leg that requested the transcription, outbound for the other leg, and both for both legs of the call. Will default to inbound.

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.

record string

Possible values: [record-from-answer]

Start recording automatically after an event. Disabled by default.

record_channels string

Possible values: [single, dual]

Default value: dual

Defines which channel should be recorded ('single' or 'dual') when record is specified.

record_format string

Possible values: [wav, mp3]

Default value: mp3

Defines the format of the recording ('wav' or 'mp3') when record is specified.

record_max_length int32

Default value: 0

Defines the maximum length for the recording in seconds when record is specified. The minimum value is 0. The maximum value is 43200. The default value is 0 (infinite).

record_timeout_secs int32

Default value: 0

The number of seconds that Telnyx will wait for the recording to be stopped if silence is detected when record is specified. 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).

record_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).

record_trim string

Possible values: [trim-silence]

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

record_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.

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/answer' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
  "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  "webhook_url": "https://www.example.com/server-b/",
  "webhook_url_method": "POST",
  "send_silence_when_idle": true
}'

Response samples

• 200
• default

---

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

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