Telnyx Developers

Answer call

posthttps://api.telnyx.com/v2/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:

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

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"billing_group_id":"f5586561-8ff0-4291-a0ac-84fe544797bd","client_state":"aGF2ZSBhIG5pY2UgZGF5ID1d"}' \
  https://api.telnyx.com/v2/calls/{call_control_id}/actions/answer

Parameters

In Path

call_control_id

string

required

Unique identifier and token for controlling the call

In Body (application/json)

billing_group_id

string

(uuid)

optional

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

Example: "f5586561-8ff0-4291-a0ac-84fe544797bd"

client_state

string

()

optional

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

Example: "aGF2ZSBhIG5pY2UgZGF5ID1d"

command_id

string

()

optional

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

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"

custom_headers

array of object

()

optional

Custom headers to be added to the SIP INVITE response.

sip_headers

array of object

()

optional

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

sound_modifications

object

()

optional

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

stream_track

string

()

optional

Specifies which track should be streamed.

Default:

"inbound_track"

Example: "both_tracks"Options: [ "inbound_track", "outbound_track", "both_tracks" ]

stream_url

string

()

optional

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

Example: "wss://www.example.com/websocket"

webhook_url

string

()

optional

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

Example: "https://www.example.com/server-b/"

webhook_url_method

string

()

optional

HTTP request type used for `webhook_url`.

Default:

"POST"

Example: "GET"Options: [ "POST", "GET" ]

Responses

200

Successful response upon making a call control command.

default

Unexpected error

Success Response

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

Expected Webhooks

call Answered

{
  "data": {
    "event_type": "call.answered",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "from": "+35319605860",
      "state": "answered",
      "to": "+35319605860"
    },
    "record_type": "event"
  }
}

streaming Failed

{
  "data": {
    "event_type": "streaming.failed",
    "id": "25dc3731-e51e-4927-a50d-a61cc25984b1",
    "occurred_at": "2021-12-15T14:11:24.613295Z",
    "payload": {
      "call_control_id": "31f19208-5db0-11ec-9ea7-02420a0d3a69",
      "call_leg_id": "31f19208-5db0-11ec-9ea7-02420a0d3a69",
      "call_session_id": "31f19208-5db0-11ec-9ea7-02420a0d3a69",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "failure_reason": "connection_failed",
      "stream_id": "1edb94f9-7ef0-4150-b502-e0ebadfd9491",
      "stream_params": {
        "stream_track": "inbound_track",
        "stream_url": "wss://www.example.com/websocket"
      },
      "stream_type": "websocket"
    },
    "record_type": "event"
  }
}

streaming Started

{
  "data": {
    "event_type": "streaming.started",
    "id": "7d743d69-f7e8-4761-b7d4-8cacf9d3c031",
    "occurred_at": "2021-12-15T14:06:32.059436Z",
    "payload": {
      "call_control_id": "31f19208-5db0-11ec-9ea7-02420a0d3a69",
      "call_leg_id": "31f19208-5db0-11ec-9ea7-02420a0d3a69",
      "call_session_id": "31f19208-5db0-11ec-9ea7-02420a0d3a69",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "stream_url": "wss://www.example.com/websocket"
    },
    "record_type": "event"
  }
}

streaming Stopped

{
  "data": {
    "event_type": "streaming.stopped",
    "id": "25dc3731-e51e-4927-a50d-a61cc25984b1",
    "occurred_at": "2021-12-15T14:11:24.613295Z",
    "payload": {
      "call_control_id": "31f19208-5db0-11ec-9ea7-02420a0d3a69",
      "call_leg_id": "31f19208-5db0-11ec-9ea7-02420a0d3a69",
      "call_session_id": "31f19208-5db0-11ec-9ea7-02420a0d3a69",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "stream_url": "wss://www.example.com/websocket"
    },
    "record_type": "event"
  }
}

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/bridge

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/enqueue

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/fork_start

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/fork_stop

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/gather

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/gather_using_audio

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/gather_using_speak

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/gather_stop

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/hangup

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/playback_start

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/playback_stop

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/record_start

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/record_pause

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/record_resume

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/record_stop

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/reject

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/leave_queue

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/send_dtmf

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/refer

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/speak

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/streaming_start

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/streaming_stop

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/transfer

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/transcription_start

...

...

Parameters

Responses

Success Response

...

posthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/transcription_stop

...

...

Parameters

Responses

Success Response

...

puthttps://api.telnyx.com/v2/calls/{call_control_id}/actions/client_state_update

...

...

Parameters

Responses

Success Response

Was this page helpful?