telnyx-voice-advanced-ruby

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Telnyx Voice Advanced - Ruby

Telnyx高级语音功能 - Ruby

Installation

安装

bash

gem install telnyx

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.

ruby

require "telnyx"

client = Telnyx::Client.new(
  api_key: ENV["TELNYX_API_KEY"], # 这是默认配置，可省略
)

以下所有示例均假设

client

已按上述方式完成初始化。

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)

更新客户端状态

PUT /calls/{call_control_id}/actions/client_state_update

— 必填参数：

client_state

ruby

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

puts(response)

SIP Refer a call

SIP Refer呼叫

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)

在呼叫控制会话中发起SIP Refer操作。

POST /calls/{call_control_id}/actions/refer

— 必填参数：

sip_address

可选参数：

client_state

（字符串）、

command_id

（字符串）、

custom_headers

（对象数组）、

sip_auth_password

（字符串）、

sip_auth_username

（字符串）、

sip_headers

（对象数组）

ruby

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

puts(response)

Send DTMF

发送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)

从当前呼叫分支发送DTMF音。

POST /calls/{call_control_id}/actions/send_dtmf

— 必填参数：

digits

可选参数：

client_state

（字符串）、

command_id

（字符串）、

duration_millis

（32位整数）

ruby

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

puts(response)

SIPREC start

启动SIPREC会话

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会话，连接至已配置的SIPREC连接器SRS。

POST /calls/{call_control_id}/actions/siprec_start

可选参数：

client_state

（字符串）、

connector_name

（字符串）、

include_metadata_custom_headers

（枚举）、

secure

（枚举）、

session_timeout_secs

（整数）、

sip_transport

（枚举）、

siprec_track

（枚举）

ruby

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

puts(response)

SIPREC stop

停止SIPREC会话

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)

停止SIPREC会话。

POST /calls/{call_control_id}/actions/siprec_stop

可选参数：

client_state

（字符串）、

command_id

（字符串）

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)

POST /calls/{call_control_id}/actions/suppression_start

可选参数：

client_state

（字符串）、

command_id

（字符串）、

direction

（枚举）、

noise_suppression_engine

（枚举）、

noise_suppression_engine_config

（对象）

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)

POST /calls/{call_control_id}/actions/suppression_stop

可选参数：

client_state

（字符串）、

command_id

（字符串）

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)

切换桥接呼叫中监控人员的角色。

POST /calls/{call_control_id}/actions/switch_supervisor_role

— 必填参数：

role

ruby

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

puts(response)

Webhooks

Webhook事件

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事件将发送至您配置的Webhook URL。所有Webhook均包含

telnyx-timestamp

和

telnyx-signature-ed25519

头信息用于验证（兼容标准Webhook）。

事件	描述
`callReferStarted`	呼叫Refer已启动
`callReferCompleted`	呼叫Refer已完成
`callReferFailed`	呼叫Refer失败
`callSiprecStarted`	SIPREC会话已启动
`callSiprecStopped`	SIPREC会话已停止
`callSiprecFailed`	SIPREC会话失败

Webhook payload fields

Webhook负载字段

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.

callReferStarted

字段	类型	描述
`data.record_type`	枚举	标识资源的类型。
`data.event_type`	枚举	标识所发送的事件类型。
`data.id`	UUID	标识资源的ID。
`data.occurred_at`	日期时间	事件发生的ISO 8601格式时间。
`data.payload.call_control_id`	字符串	用于控制呼叫的唯一ID。
`data.payload.call_leg_id`	字符串	呼叫的唯一ID，可用于关联Webhook事件。
`data.payload.call_session_id`	字符串	呼叫会话的唯一ID，可用于关联Webhook事件。
`data.payload.connection_id`	字符串	呼叫中使用的呼叫控制应用ID（原Telnyx连接ID）。
`data.payload.client_state`	字符串	从命令中接收的状态。
`data.payload.from`	字符串	发起呼叫的号码或SIP URI。
`data.payload.sip_notify_response`	整数	用于跟踪REFER尝试状态的SIP NOTIFY事件状态码。
`data.payload.to`	字符串	呼叫的目标号码或SIP URI。

callReferCompleted

字段	类型	描述
`data.record_type`	枚举	标识资源的类型。
`data.event_type`	枚举	标识所发送的事件类型。
`data.id`	UUID	标识资源的ID。
`data.occurred_at`	日期时间	事件发生的ISO 8601格式时间。
`data.payload.call_control_id`	字符串	用于控制呼叫的唯一ID。
`data.payload.call_leg_id`	字符串	呼叫的唯一ID，可用于关联Webhook事件。
`data.payload.call_session_id`	字符串	呼叫会话的唯一ID，可用于关联Webhook事件。
`data.payload.connection_id`	字符串	呼叫中使用的呼叫控制应用ID（原Telnyx连接ID）。
`data.payload.client_state`	字符串	从命令中接收的状态。
`data.payload.from`	字符串	发起呼叫的号码或SIP URI。
`data.payload.sip_notify_response`	整数	用于跟踪REFER尝试状态的SIP NOTIFY事件状态码。
`data.payload.to`	字符串	呼叫的目标号码或SIP URI。

callReferFailed

字段	类型	描述
`data.record_type`	枚举	标识资源的类型。
`data.event_type`	枚举	标识所发送的事件类型。
`data.id`	UUID	标识资源的ID。
`data.occurred_at`	日期时间	事件发生的ISO 8601格式时间。
`data.payload.call_control_id`	字符串	用于控制呼叫的唯一ID。
`data.payload.call_leg_id`	字符串	呼叫的唯一ID，可用于关联Webhook事件。
`data.payload.call_session_id`	字符串	呼叫会话的唯一ID，可用于关联Webhook事件。
`data.payload.connection_id`	字符串	呼叫中使用的呼叫控制应用ID（原Telnyx连接ID）。
`data.payload.client_state`	字符串	从命令中接收的状态。
`data.payload.from`	字符串	发起呼叫的号码或SIP URI。
`data.payload.sip_notify_response`	整数	用于跟踪REFER尝试状态的SIP NOTIFY事件状态码。
`data.payload.to`	字符串	呼叫的目标号码或SIP URI。

callSiprecStarted

字段	类型	描述
`data.record_type`	枚举	标识资源的类型。
`data.event_type`	枚举	标识所发送的事件类型。
`data.id`	UUID	标识资源的ID。
`data.occurred_at`	日期时间	事件发生的ISO 8601格式时间。
`data.payload.call_control_id`	字符串	用于通过呼叫控制API下发命令的呼叫ID。
`data.payload.connection_id`	字符串	呼叫中使用的呼叫控制应用ID（原Telnyx连接ID）。
`data.payload.call_leg_id`	字符串	呼叫的唯一ID，可用于关联Webhook事件。
`data.payload.call_session_id`	字符串	呼叫会话的唯一ID，可用于关联Webhook事件。
`data.payload.client_state`	字符串	从命令中接收的状态。

callSiprecStopped

字段	类型	描述
`data.record_type`	枚举	标识资源的类型。
`data.event_type`	枚举	标识所发送的事件类型。
`data.id`	UUID	标识资源的ID。
`data.occurred_at`	日期时间	事件发生的ISO 8601格式时间。
`data.payload.call_control_id`	字符串	用于通过呼叫控制API下发命令的呼叫ID。
`data.payload.connection_id`	字符串	呼叫中使用的呼叫控制应用ID（原Telnyx连接ID）。
`data.payload.call_leg_id`	字符串	呼叫的唯一ID，可用于关联Webhook事件。
`data.payload.call_session_id`	字符串	呼叫会话的唯一ID，可用于关联Webhook事件。
`data.payload.client_state`	字符串	从命令中接收的状态。
`data.payload.hangup_cause`	字符串	SIPREC会话停止的Q850原因码。

callSiprecFailed

字段	类型	描述
`data.record_type`	枚举	标识资源的类型。
`data.event_type`	枚举	标识所发送的事件类型。
`data.id`	UUID	标识资源的ID。
`data.occurred_at`	日期时间	事件发生的ISO 8601格式时间。
`data.payload.call_control_id`	字符串	用于通过呼叫控制API下发命令的呼叫ID。
`data.payload.connection_id`	字符串	呼叫中使用的呼叫控制应用ID（原Telnyx连接ID）。
`data.payload.call_leg_id`	字符串	呼叫的唯一ID，可用于关联Webhook事件。
`data.payload.call_session_id`	字符串	呼叫会话的唯一ID，可用于关联Webhook事件。
`data.payload.client_state`	字符串	从命令中接收的状态。
`data.payload.failure_cause`	字符串	SIPREC会话失败的Q850原因码。