Skip to main content

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

Request ​

Path Parameters

    call_control_id stringrequired

    Unique identifier and token for controlling the call

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.

    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

    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]

    interim_results boolean

    Whether to send also interim results. If set to false, only final results will be sent. 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.

Responses ​

200: Successful response upon making a call control command.

Schema

    data

    object

    result string

default: Unexpected error

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

  • ]

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"
  }
}