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

When the record parameter is set to record-from-answer, the response will include a recording_id field.

Request

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_codec StreamCodec (string)

Possible values: [PCMA, PCMU, default]

Default value: default

Specifies the codec to be used for the streamed audio. When set to 'default' or when transcoding is not possible, the codec from the call will be used. Currently, transcoding is only supported between PCMU and PCMA codecs.

stream_bidirectional_mode Bidirectional Stream Mode (string)

Possible values: [mp3, rtp]

Default value: mp3

Configures method of bidirectional streaming (mp3, rtp).

stream_bidirectional_codec Bidirectional Stream Codec (string)

Possible values: [PCMU, PCMA, G722, OPUS, AMR-WB]

Default value: PCMU

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

stream_bidirectional_target_legs Bidirectional Stream 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.

transcription_engine_config

object

oneOf

language Google transcription engine list of languages (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]

Default value: en

Language to use for speech recognition

interim_results boolean

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

enable_speaker_diarization boolean

Enables speaker diarization.

min_speaker_count int32

Default value: 2

Defines minimum number of speakers in the conversation.

max_speaker_count int32

Default value: 6

Defines maximum number of speakers in the conversation.

profanity_filter boolean

Enables profanity_filter.

use_enhanced boolean

Enables enhanced transcription, this works for models phone_call and video.

model string

Possible values: [latest_long, latest_short, command_and_search, phone_call, video, default, medical_conversation, medical_dictation]

The model to use for transcription.

hints string[]

Default value: ``

Hints to improve transcription accuracy.

speech_context

object[]

Speech context to improve transcription accuracy.

Array [

phrases string[]

Default value: ``

boost number

Possible values: <= 20

Default value: 1

Boost factor for the speech context.

]

Speech context to improve transcription accuracy.

language Telnyx transcription engine list of languages (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]

Default value: en

Language to use for speech recognition

transcription_model string

Possible values: [openai/whisper-tiny, openai/whisper-large-v3-turbo]

Default value: openai/whisper-tiny

The model to use for transcription.

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.

Responses

200: Successful response upon making a call control command that includes recording_id.

application/json

Schema

data

object

result string

recording_id uuid

The ID of the recording. Only present when the record parameter is set to record-from-answer.

{
  "data": {
    "result": "ok",
    "recording_id": "d7e9c1d4-8b2a-4b8f-b3a7-9a671c9e9b0a"
  }
}

default: Unexpected error

application/json

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": {}
    }
  ]
}

Callbacks

Request samples

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

{
  "data": {
    "result": "ok",
    "recording_id": "d7e9c1d4-8b2a-4b8f-b3a7-9a671c9e9b0a"
  }
}

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

Answer call

Request ​

Path Parameters

Body

Responses ​

Callbacks ​

Request

Responses

Callbacks