Skip to main content
POST
/
calls
JavaScript
import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: 'My API Key',
});

const response = await client.calls.dial({
  connection_id: '7267xxxxxxxxxxxxxx',
  from: '+18005550101',
  to: '+18005550100 or sip:username@sip.telnyx.com',
});

console.log(response.data);
{
  "data": {
    "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
    "call_leg_id": "2dc6fc34-f9e0-11ea-b68e-02420a0f7768",
    "call_session_id": "2dc1b3c8-f9e0-11ea-bc5a-02420a0f7768",
    "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
    "is_alive": false,
    "call_duration": 50,
    "record_type": "call",
    "recording_id": "d7e9c1d4-8b2a-4b8f-b3a7-9a671c9e9b0a",
    "start_time": "2019-01-23T18:10:02.574Z",
    "end_time": "2019-01-23T18:11:52.574Z"
  }
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Call request

to
required

The DID or SIP URI to dial out to. Multiple DID or SIP URIs can be provided using an array of strings

Example:

"+18005550100 or sip:username@sip.telnyx.com"

from
string
required

The from number to be used as the caller id presented to the destination (to number). The number should be in +E164 format.

Example:

"+18005550101"

connection_id
string
required

The ID of the Call Control App (formerly ID of the connection) to be used when dialing the destination.

from_display_name
string

The from_display_name string to be used as the caller id name (SIP From Display Name) presented to the destination (to number). The string should have a maximum of 128 characters, containing only letters, numbers, spaces, and -_~!.+ special characters. If ommited, the display name will be the same as the number in the from field.

Example:

"Company Name"

audio_url
string

The URL of a file to be played back to the callee when the call is answered. The URL can point to either a WAV or MP3 file. media_name and audio_url cannot be used together in one request.

Example:

"http://example.com/message.wav"

media_name
string

The media_name of a file to be played back to the callee when the call is answered. The media_name must point to a file previously uploaded to api.telnyx.com/v2/media by the same user/organization. The file must either be a WAV or MP3 file.

Example:

"my_media_uploaded_to_media_storage_api"

preferred_codecs
string

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

Example:

"G722,PCMU,PCMA,G729,OPUS,VP8,H264"

timeout_secs
integer<int32>
default:30

The number of seconds that Telnyx will wait for the call to be answered by the destination to which it is being called. If the timeout is reached before an answer is received, the call will hangup and a call.hangup webhook with a hangup_cause of timeout will be sent. Minimum value is 5 seconds. Maximum value is 600 seconds.

Example:

60

time_limit_secs
integer<int32>
default:14400

Sets the maximum duration of a Call Control Leg in seconds. If the time limit is reached, the call will hangup and a call.hangup webhook with a hangup_cause of time_limit will be sent. For example, by setting a time limit of 120 seconds, a Call Leg will be automatically terminated two minutes after being answered. The default time limit is 14400 seconds or 4 hours and this is also the maximum allowed call length.

Required range: 30 <= x <= 14400
Example:

600

answering_machine_detection
enum<string>
default:disabled

Enables Answering Machine Detection. Telnyx offers Premium and Standard detections. With Premium detection, when a call is answered, Telnyx runs real-time detection and sends a call.machine.premium.detection.ended webhook with one of the following results: human_residence, human_business, machine, silence or fax_detected. If we detect a beep, we also send a call.machine.premium.greeting.ended webhook with the result of beep_detected. If we detect a beep before call.machine.premium.detection.ended we only send call.machine.premium.greeting.ended, and if we detect a beep after call.machine.premium.detection.ended, we send both webhooks. With Standard detection, when a call is answered, Telnyx runs real-time detection to determine if it was picked up by a human or a machine and sends an call.machine.detection.ended webhook with the analysis result. If greeting_end or detect_words is used and a machine is detected, you will receive another call.machine.greeting.ended webhook when the answering machine greeting ends with a beep or silence. If detect_beep is used, you will only receive call.machine.greeting.ended if a beep is detected.

Available options:
premium,
detect,
detect_beep,
detect_words,
greeting_end,
disabled
answering_machine_detection_config
object

Optional configuration parameters to modify 'answering_machine_detection' performance.

conference_config
object

Optional configuration parameters to dial new participant into a conference.

custom_headers
Custom SIP Header · object[]

Custom headers to be added to the SIP INVITE.

Example:
[
{ "name": "head_1", "value": "val_1" },
{ "name": "head_2", "value": "val_2" }
]
billing_group_id
string<uuid>

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

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

Example:

"aGF2ZSBhIG5pY2UgZGF5ID1d"

command_id
string

Use this field to avoid duplicate commands. Telnyx will ignore others Dial commands with the same command_id.

Example:

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

Use another call's control id for sharing the same call session id

Example:

"ilditnZK_eVysupV21KzmzN_sM29ygfauQojpm4BgFtfX5hXAcjotg=="

bridge_intent
boolean
default:false

Indicates the intent to bridge this call with the call specified in link_to. When bridge_intent is true, link_to becomes required and the from number will be overwritten by the from number from the linked call.

Example:

true

bridge_on_answer
boolean
default:false

Whether to automatically bridge answered call to the call specified in link_to. When bridge_on_answer is true, link_to becomes required.

Example:

true

park_after_unbridge
string

If supplied with the value self, the current leg will be parked after unbridge. If not set, the default behavior is to hang up the leg. When park_after_unbridge is set, link_to becomes required.

Example:

"self"

media_encryption
enum<string>
default:disabled

Defines whether media should be encrypted on the call.

Available options:
disabled,
SRTP,
DTLS
sip_auth_username
string

SIP Authentication username used for SIP challenges.

sip_auth_password
string

SIP Authentication password used for SIP challenges.

sip_headers
SIP Header · object[]

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

Example:
[
{ "name": "User-to-User", "value": "value" }
]
sip_transport_protocol
enum<string>
default:UDP

Defines SIP transport protocol to be used on the call.

Available options:
UDP,
TCP,
TLS
sound_modifications
Sound modifications · object

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

Example:
{
"pitch": "0.8",
"semitone": -2,
"octaves": 0.1,
"track": "both"
}
stream_url
string

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

Example:

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

stream_track
enum<string>
default:inbound_track

Specifies which track should be streamed.

Available options:
inbound_track,
outbound_track,
both_tracks
Example:

"both_tracks"

stream_codec
enum<string>
default: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.

Available options:
PCMU,
PCMA,
G722,
OPUS,
AMR-WB,
L16,
default
Example:

"PCMA"

stream_bidirectional_mode
enum<string>
default:mp3

Configures method of bidirectional streaming (mp3, rtp).

Available options:
mp3,
rtp
Example:

"rtp"

stream_bidirectional_codec
enum<string>
default:PCMU

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

Available options:
PCMU,
PCMA,
G722,
OPUS,
AMR-WB,
L16
Example:

"G722"

stream_bidirectional_target_legs
enum<string>
default:opposite

Specifies which call legs should receive the bidirectional stream audio.

Available options:
both,
self,
opposite
Example:

"both"

stream_bidirectional_sampling_rate
enum<integer>
default:8000

Audio sampling rate.

Available options:
8000,
16000,
22050,
24000,
48000
Example:

16000

stream_establish_before_call_originate
boolean
default:false

Establish websocket connection before dialing the destination. This is useful for cases where the websocket connection takes a long time to establish.

Example:

true

send_silence_when_idle
boolean
default:false

Generate silence RTP packets when no transmission available.

Example:

true

webhook_url
string

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
enum<string>
default:POST

HTTP request type used for webhook_url.

Available options:
POST,
GET
Example:

"GET"

record
enum<string>

Start recording automatically after an event. Disabled by default.

Available options:
record-from-answer
Example:

"record-from-answer"

record_channels
enum<string>
default:dual

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

Available options:
single,
dual
Example:

"single"

record_format
enum<string>
default:mp3

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

Available options:
wav,
mp3
Example:

"wav"

record_max_length
integer<int32>
default: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).

Example:

1000

record_timeout_secs
integer<int32>
default: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).

Example:

100

record_track
enum<string>
default: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).

Available options:
both,
inbound,
outbound
Example:

"outbound"

record_trim
enum<string>

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

Available options:
trim-silence
Example:

"trim-silence"

record_custom_file_name
string

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

Required string length: 1 - 40
Example:

"my_recording_file_name"

supervise_call_control_id
string

The call leg which will be supervised by the new call.

Example:

"v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg"

supervisor_role
enum<string>
default:barge

The role of the supervisor call. 'barge' means that supervisor call hears and is being heard by both ends of the call (caller & callee). 'whisper' means that only supervised_call_control_id hears supervisor but supervisor can hear everything. 'monitor' means that nobody can hear supervisor call, but supervisor can hear everything on the call.

Available options:
barge,
whisper,
monitor
enable_dialogflow
boolean
default:false

Enables Dialogflow for the current call. The default value is false.

Example:

true

dialogflow_config
Dialogflow Config · object
transcription
boolean
default:false

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

Example:

true

transcription_config
Transcription start request · object
Example:
{
"language": "en",
"client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
"command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
sip_region
enum<string>
default:US

Defines the SIP region to be used for the call.

Available options:
US,
Europe,
Canada,
Australia,
Middle East
Example:

"Canada"

Response

Successful response with details about a call status that includes recording_id.

data
Call With Recording ID · object
Example:
{
"call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
"call_leg_id": "2dc6fc34-f9e0-11ea-b68e-02420a0f7768",
"call_session_id": "2dc1b3c8-f9e0-11ea-bc5a-02420a0f7768",
"client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
"is_alive": false,
"call_duration": 50,
"record_type": "call",
"recording_id": "d7e9c1d4-8b2a-4b8f-b3a7-9a671c9e9b0a",
"start_time": "2019-01-23T18:10:02.574Z",
"end_time": "2019-01-23T18:11:52.574Z"
}