Telnyx Voice Advanced - Ruby

Installation

bash

gem install telnyx

Setup

ruby

require "telnyx"

client = Telnyx::Client.new(
  api_key: ENV["TELNYX_API_KEY"], # This is the default and can be omitted
)

All examples below assume

client

is already initialized as shown above.

Update client state

Updates client state

PUT /calls/{call_control_id}/actions/client_state_update

— Required:

client_state

ruby

response = client.calls.actions.update_client_state("call_control_id", client_state: "aGF2ZSBhIG5pY2UgZGF5ID1d")

puts(response)

SIP Refer a call

Initiate a SIP Refer on a Call Control call.

POST /calls/{call_control_id}/actions/refer

— Required:

sip_address

Optional:

client_state

(string),

command_id

(string),

custom_headers

(array[object]),

sip_auth_password

(string),

sip_auth_username

(string),

sip_headers

(array[object])

ruby

response = client.calls.actions.refer("call_control_id", sip_address: "sip:username@sip.non-telnyx-address.com")

puts(response)

Send DTMF

Sends DTMF tones from this leg.

POST /calls/{call_control_id}/actions/send_dtmf

— Required:

digits

Optional:

client_state

(string),

command_id

(string),

duration_millis

(int32)

ruby

response = client.calls.actions.send_dtmf("call_control_id", digits: "1www2WABCDw9")

puts(response)

SIPREC start

Start siprec session to configured in SIPREC connector SRS.

POST /calls/{call_control_id}/actions/siprec_start

Optional:

client_state

(string),

connector_name

(string),

include_metadata_custom_headers

(enum),

secure

(enum),

session_timeout_secs

(integer),

sip_transport

(enum),

siprec_track

(enum)

ruby

response = client.calls.actions.start_siprec("call_control_id")

puts(response)

SIPREC stop

Stop SIPREC session.

POST /calls/{call_control_id}/actions/siprec_stop

Optional:

client_state

(string),

command_id

(string)

ruby

response = client.calls.actions.stop_siprec("call_control_id")

puts(response)

Noise Suppression Start (BETA)

POST /calls/{call_control_id}/actions/suppression_start

Optional:

client_state

(string),

command_id

(string),

direction

(enum),

noise_suppression_engine

(enum),

noise_suppression_engine_config

(object)

ruby

response = client.calls.actions.start_noise_suppression("call_control_id")

puts(response)

Noise Suppression Stop (BETA)

POST /calls/{call_control_id}/actions/suppression_stop

Optional:

client_state

(string),

command_id

(string)

ruby

response = client.calls.actions.stop_noise_suppression("call_control_id")

puts(response)

Switch supervisor role

Switch the supervisor role for a bridged call.

POST /calls/{call_control_id}/actions/switch_supervisor_role

— Required:

role

ruby

response = client.calls.actions.switch_supervisor_role("call_control_id", role: :barge)

puts(response)

Webhooks

The following webhook events are sent to your configured webhook URL. All webhooks include

telnyx-timestamp

and

telnyx-signature-ed25519

headers for verification (Standard Webhooks compatible).

Event	Description
`callReferStarted`	Call Refer Started
`callReferCompleted`	Call Refer Completed
`callReferFailed`	Call Refer Failed
`callSiprecStarted`	Call Siprec Started
`callSiprecStopped`	Call Siprec Stopped
`callSiprecFailed`	Call Siprec Failed

Webhook payload fields

callReferStarted

Field	Type	Description
`data.record_type`	enum	Identifies the type of the resource.
`data.event_type`	enum	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Unique ID for controlling the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.client_state`	string	State received from a command.
`data.payload.from`	string	Number or SIP URI placing the call.
`data.payload.sip_notify_response`	integer	SIP NOTIFY event status for tracking the REFER attempt.
`data.payload.to`	string	Destination number or SIP URI of the call.

callReferCompleted

Field	Type	Description
`data.record_type`	enum	Identifies the type of the resource.
`data.event_type`	enum	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Unique ID for controlling the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.client_state`	string	State received from a command.
`data.payload.from`	string	Number or SIP URI placing the call.
`data.payload.sip_notify_response`	integer	SIP NOTIFY event status for tracking the REFER attempt.
`data.payload.to`	string	Destination number or SIP URI of the call.

callReferFailed

Field	Type	Description
`data.record_type`	enum	Identifies the type of the resource.
`data.event_type`	enum	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Unique ID for controlling the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.client_state`	string	State received from a command.
`data.payload.from`	string	Number or SIP URI placing the call.
`data.payload.sip_notify_response`	integer	SIP NOTIFY event status for tracking the REFER attempt.
`data.payload.to`	string	Destination number or SIP URI of the call.

callSiprecStarted

Field	Type	Description
`data.record_type`	enum	Identifies the type of the resource.
`data.event_type`	enum	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Call ID used to issue commands via Call Control API.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.client_state`	string	State received from a command.

callSiprecStopped

Field	Type	Description
`data.record_type`	enum	Identifies the type of the resource.
`data.event_type`	enum	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Call ID used to issue commands via Call Control API.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.client_state`	string	State received from a command.
`data.payload.hangup_cause`	string	Q850 reason why the SIPREC session was stopped.

callSiprecFailed

Field	Type	Description
`data.record_type`	enum	Identifies the resource.
`data.event_type`	enum	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Call ID used to issue commands via Call Control API.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.client_state`	string	State received from a command.
`data.payload.failure_cause`	string	Q850 reason why siprec session failed.

Telnyx Voice Advanced - Ruby

Installation

bash

gem install telnyx

Setup

ruby

require "telnyx"

client = Telnyx::Client.new(
  api_key: ENV["TELNYX_API_KEY"], # This is the default and can be omitted
)

All examples below assume

client

is already initialized as shown above.

Update client state

Updates client state

PUT /calls/{call_control_id}/actions/client_state_update

— Required:

client_state

ruby

response = client.calls.actions.update_client_state("call_control_id", client_state: "aGF2ZSBhIG5pY2UgZGF5ID1d")

puts(response)

SIP Refer a call

Initiate a SIP Refer on a Call Control call.

POST /calls/{call_control_id}/actions/refer

— Required:

sip_address

Optional:

client_state

(string),

command_id

(string),

custom_headers

(array[object]),

sip_auth_password

(string),

sip_auth_username

(string),

sip_headers

(array[object])

ruby

response = client.calls.actions.refer("call_control_id", sip_address: "sip:username@sip.non-telnyx-address.com")

puts(response)

Send DTMF

Sends DTMF tones from this leg.

POST /calls/{call_control_id}/actions/send_dtmf

— Required:

digits

Optional:

client_state

(string),

command_id

(string),

duration_millis

(int32)

ruby

response = client.calls.actions.send_dtmf("call_control_id", digits: "1www2WABCDw9")

puts(response)

SIPREC start

Start siprec session to configured in SIPREC connector SRS.

POST /calls/{call_control_id}/actions/siprec_start

Optional:

client_state

(string),

connector_name

(string),

include_metadata_custom_headers

(enum),

secure

(enum),

session_timeout_secs

(integer),

sip_transport

(enum),

siprec_track

(enum)

ruby

response = client.calls.actions.start_siprec("call_control_id")

puts(response)

SIPREC stop

Stop SIPREC session.

POST /calls/{call_control_id}/actions/siprec_stop

Optional:

client_state

(string),

command_id

(string)

ruby

response = client.calls.actions.stop_siprec("call_control_id")

puts(response)

Noise Suppression Start (BETA)

POST /calls/{call_control_id}/actions/suppression_start

Optional:

client_state

(string),

command_id

(string),

direction

(enum),

noise_suppression_engine

(enum),

noise_suppression_engine_config

(object)

ruby

response = client.calls.actions.start_noise_suppression("call_control_id")

puts(response)

Noise Suppression Stop (BETA)

POST /calls/{call_control_id}/actions/suppression_stop

Optional:

client_state

(string),

command_id

(string)

ruby

response = client.calls.actions.stop_noise_suppression("call_control_id")

puts(response)

Switch supervisor role

Switch the supervisor role for a bridged call.

POST /calls/{call_control_id}/actions/switch_supervisor_role

— Required:

role

ruby

response = client.calls.actions.switch_supervisor_role("call_control_id", role: :barge)

puts(response)

Webhooks

The following webhook events are sent to your configured webhook URL. All webhooks include

telnyx-timestamp

and

telnyx-signature-ed25519

headers for verification (Standard Webhooks compatible).

Event	Description
`callReferStarted`	Call Refer Started
`callReferCompleted`	Call Refer Completed
`callReferFailed`	Call Refer Failed
`callSiprecStarted`	Call Siprec Started
`callSiprecStopped`	Call Siprec Stopped
`callSiprecFailed`	Call Siprec Failed

Webhook payload fields

callReferStarted

Field	Type	Description
`data.record_type`	enum	Identifies the type of the resource.
`data.event_type`	enum	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Unique ID for controlling the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.client_state`	string	State received from a command.
`data.payload.from`	string	Number or SIP URI placing the call.
`data.payload.sip_notify_response`	integer	SIP NOTIFY event status for tracking the REFER attempt.
`data.payload.to`	string	Destination number or SIP URI of the call.

callReferCompleted

Field	Type	Description
`data.record_type`	enum	Identifies the type of the resource.
`data.event_type`	enum	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Unique ID for controlling the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.client_state`	string	State received from a command.
`data.payload.from`	string	Number or SIP URI placing the call.
`data.payload.sip_notify_response`	integer	SIP NOTIFY event status for tracking the REFER attempt.
`data.payload.to`	string	Destination number or SIP URI of the call.

callReferFailed

Field	Type	Description
`data.record_type`	enum	Identifies the type of the resource.
`data.event_type`	enum	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Unique ID for controlling the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.client_state`	string	State received from a command.
`data.payload.from`	string	Number or SIP URI placing the call.
`data.payload.sip_notify_response`	integer	SIP NOTIFY event status for tracking the REFER attempt.
`data.payload.to`	string	Destination number or SIP URI of the call.

callSiprecStarted

Field	Type	Description
`data.record_type`	enum	Identifies the type of the resource.
`data.event_type`	enum	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Call ID used to issue commands via Call Control API.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.client_state`	string	State received from a command.

callSiprecStopped

Field	Type	Description
`data.record_type`	enum	Identifies the type of the resource.
`data.event_type`	enum	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Call ID used to issue commands via Call Control API.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.client_state`	string	State received from a command.
`data.payload.hangup_cause`	string	Q850 reason why the SIPREC session was stopped.

callSiprecFailed

Field	Type	Description
`data.record_type`	enum	Identifies the resource.
`data.event_type`	enum	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Call ID used to issue commands via Call Control API.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.client_state`	string	State received from a command.
`data.payload.failure_cause`	string	Q850 reason why siprec session failed.

telnyx-voice-advanced-ruby

NPX Install

Tags

SKILL.md Content

Telnyx Voice Advanced - Ruby

Installation

Setup

Update client state

SIP Refer a call

Send DTMF

SIPREC start

SIPREC stop

Noise Suppression Start (BETA)

Noise Suppression Stop (BETA)

Switch supervisor role

Webhooks

Webhook payload fields

telnyx-voice-advanced-ruby

NPX Install

Tags

SKILL.md Content

Telnyx Voice Advanced - Ruby

Installation

Setup

Update client state

SIP Refer a call

Send DTMF

SIPREC start

SIPREC stop

Noise Suppression Start (BETA)

Noise Suppression Stop (BETA)

Switch supervisor role

Webhooks

Webhook payload fields