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

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

Error Handling

错误处理

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:

ruby

begin
  result = client.messages.send_(to: "+13125550001", from: "+13125550002", text: "Hello")
rescue Telnyx::Errors::APIConnectionError
  puts "Network error — check connectivity and retry"
rescue Telnyx::Errors::RateLimitError
  # 429: rate limited — wait and retry with exponential backoff
  sleep(1) # Check Retry-After header for actual delay
rescue Telnyx::Errors::APIStatusError => e
  puts "API error #{e.status}: #{e.message}"
  if e.status == 422
    puts "Validation error — check required fields and formats"
  end
end

Common error codes:

invalid API key,

insufficient permissions,

resource not found,

validation error (check field formats),

rate limited (retry with exponential backoff).

所有API调用都可能因网络错误、速率限制（429）、校验错误（422）或认证错误（401）而失败，生产环境代码请务必做好错误处理：

ruby

begin
  result = client.messages.send_(to: "+13125550001", from: "+13125550002", text: "Hello")
rescue Telnyx::Errors::APIConnectionError
  puts "网络错误 — 检查网络连接后重试"
rescue Telnyx::Errors::RateLimitError
  # 429: 触发速率限制 — 等待后使用指数退避策略重试
  sleep(1) # 可查看Retry-After请求头获取官方建议的等待时长
rescue Telnyx::Errors::APIStatusError => e
  puts "API错误 #{e.status}: #{e.message}"
  if e.status == 422
    puts "校验错误 — 检查必填字段和格式是否正确"
  end
end

常见错误码：

无效API密钥、

权限不足、

资源不存在、

校验错误（检查字段格式）、

触发速率限制（使用指数退避策略重试）。

Join AI Assistant Conversation

加入AI助手对话

Add a participant to an existing AI assistant conversation. Use this command to bring an additional call leg into a running AI conversation.

POST /calls/{call_control_id}/actions/ai_assistant_join

— Required:

conversation_id

participant

Optional:

client_state

(string),

command_id

(string)

ruby

response = client.calls.actions.join_ai_assistant(
  "call_control_id",
  conversation_id: "v3:abc123",
  participant: {id: "v3:abc123def456", role: :user}
)

puts(response)

Returns:

conversation_id

(uuid),

result

(string)

将参与者添加到现有AI助手对话中，使用该命令可以将额外的通话支路加入正在运行的AI对话。

POST /calls/{call_control_id}/actions/ai_assistant_join

— 必填参数：

conversation_id

、

participant

可选参数：

client_state

（字符串）、

command_id

（字符串）

ruby

response = client.calls.actions.join_ai_assistant(
  "call_control_id",
  conversation_id: "v3:abc123",
  participant: {id: "v3:abc123def456", role: :user}
)

puts(response)

返回值：

conversation_id

（uuid）、

result

（字符串）

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)

Returns:

result

(string)

更新客户端状态

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)

返回值：

result

（字符串）

Send DTMF

发送DTMF

Sends DTMF tones from this leg. DTMF tones will be heard by the other end of the call. Expected Webhooks:

There are no webhooks associated with this command.

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)

Returns:

result

(string)

从当前通话支路发送DTMF音，通话另一端会听到该DTMF音。预期触发的Webhook：

该命令没有关联的Webhook。

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)

返回值：

result

（字符串）

SIPREC start

开启SIPREC

Start siprec session to configured in SIPREC connector SRS.

Expected Webhooks:

```
siprec.started
```
```
siprec.stopped
```
```
siprec.failed
```

POST /calls/{call_control_id}/actions/siprec_start

Optional:

client_state

(string),

connector_name

(string),

include_metadata_custom_headers

(boolean),

secure

(boolean),

session_timeout_secs

(integer),

sip_transport

(enum: udp, tcp, tls),

siprec_track

(enum: inbound_track, outbound_track, both_tracks)

ruby

response = client.calls.actions.start_siprec("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")

puts(response)

Returns:

result

(string)

为配置的SIPREC连接器SRS启动siprec会话。

预期触发的Webhook：

```
siprec.started
```
```
siprec.stopped
```
```
siprec.failed
```

POST /calls/{call_control_id}/actions/siprec_start

可选参数：

client_state

（字符串）、

connector_name

（字符串）、

include_metadata_custom_headers

（布尔值）、

secure

（布尔值）、

session_timeout_secs

（整数）、

sip_transport

（枚举值：udp、tcp、tls）、

siprec_track

（枚举值：inbound_track、outbound_track、both_tracks）

ruby

response = client.calls.actions.start_siprec("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")

puts(response)

返回值：

result

（字符串）

SIPREC stop

停止SIPREC

Stop SIPREC session. Expected Webhooks:

```
siprec.stopped
```

POST /calls/{call_control_id}/actions/siprec_stop

Optional:

client_state

(string),

command_id

(string)

ruby

response = client.calls.actions.stop_siprec("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")

puts(response)

Returns:

result

(string)

停止SIPREC会话。预期触发的Webhook：

```
siprec.stopped
```

POST /calls/{call_control_id}/actions/siprec_stop

可选参数：

client_state

（字符串）、

command_id

（字符串）

ruby

response = client.calls.actions.stop_siprec("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")

puts(response)

返回值：

result

（字符串）

Noise Suppression Start (BETA)

开启噪声抑制（测试版）

POST /calls/{call_control_id}/actions/suppression_start

Optional:

client_state

(string),

command_id

(string),

direction

(enum: inbound, outbound, both),

noise_suppression_engine

(enum: Denoiser, DeepFilterNet, Krisp, AiCoustics),

noise_suppression_engine_config

(object)

ruby

response = client.calls.actions.start_noise_suppression("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")

puts(response)

Returns:

result

(string)

POST /calls/{call_control_id}/actions/suppression_start

可选参数：

client_state

（字符串）、

command_id

（字符串）、

direction

（枚举值：inbound、outbound、both）、

noise_suppression_engine

（枚举值：Denoiser、DeepFilterNet、Krisp、AiCoustics）、

noise_suppression_engine_config

（对象）

ruby

response = client.calls.actions.start_noise_suppression("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")

puts(response)

返回值：

result

（字符串）

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("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")

puts(response)

Returns:

result

(string)

POST /calls/{call_control_id}/actions/suppression_stop

可选参数：

client_state

（字符串）、

command_id

（字符串）

ruby

response = client.calls.actions.stop_noise_suppression("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")

puts(response)

返回值：

result

（字符串）

Switch supervisor role

切换主管角色

Switch the supervisor role for a bridged call. This allows switching between different supervisor modes during an active 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)

Returns:

result

(string)

为桥接通话切换主管角色，支持在活跃通话过程中切换不同的主管模式。

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)

返回值：

result

（字符串）

Webhooks

Webhook Verification

Webhook校验

Telnyx signs webhooks with Ed25519. Each request includes

telnyx-signature-ed25519

and

telnyx-timestamp

headers. Always verify signatures in production:

ruby

undefined

Telnyx使用Ed25519对Webhook进行签名，每个请求都包含

telnyx-signature-ed25519

和

telnyx-timestamp

请求头，生产环境请务必校验签名：

ruby

undefined

In your webhook handler (e.g., Sinatra — use raw body):

在你的Webhook处理逻辑中（例如Sinatra — 请使用原始请求体）：

post "/webhooks" do payload = request.body.read headers = { "telnyx-signature-ed25519" => request.env["HTTP_TELNYX_SIGNATURE_ED25519"], "telnyx-timestamp" => request.env["HTTP_TELNYX_TIMESTAMP"], } begin event = client.webhooks.unwrap(payload, headers) rescue => e halt 400, "Invalid signature: #{e.message}" end

Signature valid — event is the parsed webhook payload

puts "Received event: #{event.data.event_type}" status 200 end


The following webhook events are sent to your configured webhook URL.
All webhooks include `telnyx-timestamp` and `telnyx-signature-ed25519` headers for Ed25519 signature verification. Use `client.webhooks.unwrap()` to verify.

| Event | Description |
|-------|-------------|
| `callConversationEnded` | Call Conversation Ended |
| `callConversationInsightsGenerated` | Call Conversation Insights Generated |
| `callDtmfReceived` | Call Dtmf Received |
| `callMachineDetectionEnded` | Call Machine Detection Ended |
| `callMachineGreetingEnded` | Call Machine Greeting Ended |
| `callMachinePremiumDetectionEnded` | Call Machine Premium Detection Ended |
| `callMachinePremiumGreetingEnded` | Call Machine Premium Greeting Ended |
| `callReferCompleted` | Call Refer Completed |
| `callReferFailed` | Call Refer Failed |
| `callReferStarted` | Call Refer Started |
| `callSiprecFailed` | Call Siprec Failed |
| `callSiprecStarted` | Call Siprec Started |
| `callSiprecStopped` | Call Siprec Stopped |

签名校验通过 — event为解析后的Webhook payload

puts "收到事件: #{event.data.event_type}" status 200 end


以下Webhook事件会发送到你配置的Webhook地址，所有Webhook都包含`telnyx-timestamp`和`telnyx-signature-ed25519`请求头用于Ed25519签名校验，可使用`client.webhooks.unwrap()`方法完成校验。

| 事件 | 描述 |
|-------|-------------|
| `callConversationEnded` | 通话对话已结束 |
| `callConversationInsightsGenerated` | 已生成通话对话洞察 |
| `callDtmfReceived` | 收到通话DTMF信号 |
| `callMachineDetectionEnded` | 通话机器检测完成 |
| `callMachineGreetingEnded` | 机器问候音播放完成 |
| `callMachinePremiumDetectionEnded` | 高级版通话机器检测完成 |
| `callMachinePremiumGreetingEnded` | 高级版机器问候音播放完成 |
| `callReferCompleted` | 通话转移完成 |
| `callReferFailed` | 通话转移失败 |
| `callReferStarted` | 通话转移已启动 |
| `callSiprecFailed` | 通话SIPREC启动失败 |
| `callSiprecStarted` | 通话SIPREC已启动 |
| `callSiprecStopped` | 通话SIPREC已停止 |

Webhook payload fields

Webhook payload字段

callConversationEnded

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.conversation.ended	The type of event being delivered.
`data.id`	uuid	Unique identifier for the event.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.created_at`	date-time	Timestamp when the event was created in the system.
`data.payload.assistant_id`	string	Unique identifier of the assistant involved in the call.
`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 leg.
`data.payload.call_session_id`	string	ID that is unique to the call session (group of related call legs).
`data.payload.client_state`	string	Base64-encoded state received from a command.
`data.payload.calling_party_type`	enum: pstn, sip	The type of calling party connection.
`data.payload.conversation_id`	string	ID unique to the conversation or insight group generated for the call.
`data.payload.duration_sec`	integer	Duration of the conversation in seconds.
`data.payload.from`	string	The caller's number or identifier.
`data.payload.to`	string	The callee's number or SIP address.
`data.payload.llm_model`	string	The large language model used during the conversation.
`data.payload.stt_model`	string	The speech-to-text model used in the conversation.
`data.payload.tts_provider`	string	The text-to-speech provider used in the call.
`data.payload.tts_model_id`	string	The model ID used for text-to-speech synthesis.
`data.payload.tts_voice_id`	string	Voice ID used for TTS.

callConversationInsightsGenerated

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.conversation_insights.generated	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.calling_party_type`	enum: pstn, sip	The type of calling party connection.
`data.payload.insight_group_id`	string	ID that is unique to the insight group being generated for the call.
`data.payload.results`	array[object]	Array of insight results being generated for the call.

callDtmfReceived

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.dtmf.received	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	Identifies the type of resource.
`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.from`	string	Number or SIP URI placing the call.
`data.payload.to`	string	Destination number or SIP URI of the call.
`data.payload.digit`	string	The received DTMF digit or symbol.

callMachineDetectionEnded

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.machine.detection.ended	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.from`	string	Number or SIP URI placing the call.
`data.payload.to`	string	Destination number or SIP URI of the call.
`data.payload.result`	enum: human, machine, not_sure	Answering machine detection result.

callMachineGreetingEnded

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.machine.greeting.ended	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.from`	string	Number or SIP URI placing the call.
`data.payload.to`	string	Destination number or SIP URI of the call.
`data.payload.result`	enum: beep_detected, ended, not_sure	Answering machine greeting ended result.

callMachinePremiumDetectionEnded

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.machine.premium.detection.ended	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.from`	string	Number or SIP URI placing the call.
`data.payload.to`	string	Destination number or SIP URI of the call.
`data.payload.result`	enum: human_residence, human_business, machine, silence, fax_detected, not_sure	Premium Answering Machine Detection result.

callMachinePremiumGreetingEnded

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.machine.premium.greeting.ended	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.from`	string	Number or SIP URI placing the call.
`data.payload.to`	string	Destination number or SIP URI of the call.
`data.payload.result`	enum: beep_detected, no_beep_detected	Premium Answering Machine Greeting Ended result.

callReferCompleted

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.refer.completed	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: event	Identifies the type of the resource.
`data.event_type`	enum: call.refer.failed	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.

callReferStarted

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.refer.started	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.

callSiprecFailed

Field	Type	Description
`data.record_type`	enum: event	Identifies the resource.
`data.event_type`	enum: siprec.failed	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.

callSiprecStarted

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: siprec.started	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: event	Identifies the type of the resource.
`data.event_type`	enum: siprec.stopped	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.

callConversationEnded

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: call.conversation.ended	推送的事件类型
`data.id`	uuid	事件唯一标识符
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间戳
`data.created_at`	date-time	事件在系统中创建的时间戳
`data.payload.assistant_id`	string	参与通话的助手唯一标识符
`data.payload.call_control_id`	string	用于通过通话控制API下发指令的通话ID
`data.payload.connection_id`	string	通话使用的通话控制应用ID（原Telnyx连接ID）
`data.payload.call_leg_id`	string	通话支路的唯一ID
`data.payload.call_session_id`	string	通话会话的唯一ID（一组关联的通话支路共享）
`data.payload.client_state`	string	从命令中接收的Base64编码状态
`data.payload.calling_party_type`	枚举值: pstn, sip	主叫方连接类型
`data.payload.conversation_id`	string	为通话生成的对话或洞察组的唯一ID
`data.payload.duration_sec`	integer	对话持续时长，单位秒
`data.payload.from`	string	主叫号码或标识符
`data.payload.to`	string	被叫号码或SIP地址
`data.payload.llm_model`	string	对话过程中使用的大语言模型
`data.payload.stt_model`	string	对话中使用的语音转文本模型
`data.payload.tts_provider`	string	通话中使用的文本转语音服务商
`data.payload.tts_model_id`	string	用于文本转语音合成的模型ID
`data.payload.tts_voice_id`	string	TTS使用的音色ID

callConversationInsightsGenerated

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: call.conversation_insights.generated	推送的事件类型
`data.id`	uuid	资源类型标识符
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间戳
`data.payload.call_control_id`	string	用于通过通话控制API下发指令的通话ID
`data.payload.connection_id`	string	通话使用的通话控制应用ID（原Telnyx连接ID）
`data.payload.call_leg_id`	string	通话的唯一ID，可用于关联Webhook事件
`data.payload.call_session_id`	string	通话会话的唯一ID，可用于关联Webhook事件
`data.payload.client_state`	string	从命令中接收的状态
`data.payload.calling_party_type`	枚举值: pstn, sip	主叫方连接类型
`data.payload.insight_group_id`	string	为通话生成的洞察组的唯一ID
`data.payload.results`	array[object]	为通话生成的洞察结果数组

callDtmfReceived

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: call.dtmf.received	推送的事件类型
`data.id`	uuid	资源类型标识符
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间戳
`data.payload.call_control_id`	string	用于通过通话控制API下发指令的通话ID
`data.payload.connection_id`	string	资源类型标识符
`data.payload.call_leg_id`	string	通话的唯一ID，可用于关联Webhook事件
`data.payload.call_session_id`	string	通话会话的唯一ID，可用于关联Webhook事件
`data.payload.client_state`	string	从命令中接收的状态
`data.payload.from`	string	发起通话的号码或SIP URI
`data.payload.to`	string	通话的目标号码或SIP URI
`data.payload.digit`	string	收到的DTMF数字或符号

callMachineDetectionEnded

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: call.machine.detection.ended	推送的事件类型
`data.id`	uuid	资源类型标识符
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间戳
`data.payload.call_control_id`	string	用于通过通话控制API下发指令的通话ID
`data.payload.connection_id`	string	通话使用的通话控制应用ID（原Telnyx连接ID）
`data.payload.call_leg_id`	string	通话的唯一ID，可用于关联Webhook事件
`data.payload.call_session_id`	string	通话会话的唯一ID，可用于关联Webhook事件
`data.payload.client_state`	string	从命令中接收的状态
`data.payload.from`	string	发起通话的号码或SIP URI
`data.payload.to`	string	通话的目标号码或SIP URI
`data.payload.result`	枚举值: human, machine, not_sure	应答机检测结果

callMachineGreetingEnded

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: call.machine.greeting.ended	推送的事件类型
`data.id`	uuid	资源类型标识符
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间戳
`data.payload.call_control_id`	string	用于通过通话控制API下发指令的通话ID
`data.payload.connection_id`	string	通话使用的通话控制应用ID（原Telnyx连接ID）
`data.payload.call_leg_id`	string	通话的唯一ID，可用于关联Webhook事件
`data.payload.call_session_id`	string	通话会话的唯一ID，可用于关联Webhook事件
`data.payload.client_state`	string	从命令中接收的状态
`data.payload.from`	string	发起通话的号码或SIP URI
`data.payload.to`	string	通话的目标号码或SIP URI
`data.payload.result`	枚举值: beep_detected, ended, not_sure	应答机问候音结束检测结果

callMachinePremiumDetectionEnded

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: call.machine.premium.detection.ended	推送的事件类型
`data.id`	uuid	资源类型标识符
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间戳
`data.payload.call_control_id`	string	用于通过通话控制API下发指令的通话ID
`data.payload.connection_id`	string	通话使用的通话控制应用ID（原Telnyx连接ID）
`data.payload.call_leg_id`	string	通话的唯一ID，可用于关联Webhook事件
`data.payload.call_session_id`	string	通话会话的唯一ID，可用于关联Webhook事件
`data.payload.client_state`	string	从命令中接收的状态
`data.payload.from`	string	发起通话的号码或SIP URI
`data.payload.to`	string	通话的目标号码或SIP URI
`data.payload.result`	枚举值: human_residence, human_business, machine, silence, fax_detected, not_sure	高级版应答机检测结果

callMachinePremiumGreetingEnded

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: call.machine.premium.greeting.ended	推送的事件类型
`data.id`	uuid	资源类型标识符
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间戳
`data.payload.call_control_id`	string	用于通过通话控制API下发指令的通话ID
`data.payload.connection_id`	string	通话使用的通话控制应用ID（原Telnyx连接ID）
`data.payload.call_leg_id`	string	通话的唯一ID，可用于关联Webhook事件
`data.payload.call_session_id`	string	通话会话的唯一ID，可用于关联Webhook事件
`data.payload.client_state`	string	从命令中接收的状态
`data.payload.from`	string	发起通话的号码或SIP URI
`data.payload.to`	string	通话的目标号码或SIP URI
`data.payload.result`	枚举值: beep_detected, no_beep_detected	高级版应答机问候音结束检测结果

callReferCompleted

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: call.refer.completed	推送的事件类型
`data.id`	uuid	资源类型标识符
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间戳
`data.payload.call_control_id`	string	用于控制通话的唯一ID
`data.payload.call_leg_id`	string	通话的唯一ID，可用于关联Webhook事件
`data.payload.call_session_id`	string	通话会话的唯一ID，可用于关联Webhook事件
`data.payload.connection_id`	string	通话使用的通话控制应用ID（原Telnyx连接ID）
`data.payload.client_state`	string	从命令中接收的状态
`data.payload.from`	string	发起通话的号码或SIP URI
`data.payload.sip_notify_response`	integer	用于跟踪REFER尝试的SIP NOTIFY事件状态
`data.payload.to`	string	通话的目标号码或SIP URI

callReferFailed

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: call.refer.failed	推送的事件类型
`data.id`	uuid	资源类型标识符
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间戳
`data.payload.call_control_id`	string	用于控制通话的唯一ID
`data.payload.call_leg_id`	string	通话的唯一ID，可用于关联Webhook事件
`data.payload.call_session_id`	string	通话会话的唯一ID，可用于关联Webhook事件
`data.payload.connection_id`	string	通话使用的通话控制应用ID（原Telnyx连接ID）
`data.payload.client_state`	string	从命令中接收的状态
`data.payload.from`	string	发起通话的号码或SIP URI
`data.payload.sip_notify_response`	integer	用于跟踪REFER尝试的SIP NOTIFY事件状态
`data.payload.to`	string	通话的目标号码或SIP URI

callReferStarted

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: call.refer.started	推送的事件类型
`data.id`	uuid	资源类型标识符
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间戳
`data.payload.call_control_id`	string	用于控制通话的唯一ID
`data.payload.call_leg_id`	string	通话的唯一ID，可用于关联Webhook事件
`data.payload.call_session_id`	string	通话会话的唯一ID，可用于关联Webhook事件
`data.payload.connection_id`	string	通话使用的通话控制应用ID（原Telnyx连接ID）
`data.payload.client_state`	string	从命令中接收的状态
`data.payload.from`	string	发起通话的号码或SIP URI
`data.payload.sip_notify_response`	integer	用于跟踪REFER尝试的SIP NOTIFY事件状态
`data.payload.to`	string	通话的目标号码或SIP URI

callSiprecFailed

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: siprec.failed	推送的事件类型
`data.id`	uuid	资源类型标识符
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间戳
`data.payload.call_control_id`	string	用于通过通话控制API下发指令的通话ID
`data.payload.connection_id`	string	通话使用的通话控制应用ID（原Telnyx连接ID）
`data.payload.call_leg_id`	string	通话的唯一ID，可用于关联Webhook事件
`data.payload.call_session_id`	string	通话会话的唯一ID，可用于关联Webhook事件
`data.payload.client_state`	string	从命令中接收的状态
`data.payload.failure_cause`	string	siprec会话失败的Q850原因

callSiprecStarted

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: siprec.started	推送的事件类型
`data.id`	uuid	资源类型标识符
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间戳
`data.payload.call_control_id`	string	用于通过通话控制API下发指令的通话ID
`data.payload.connection_id`	string	通话使用的通话控制应用ID（原Telnyx连接ID）
`data.payload.call_leg_id`	string	通话的唯一ID，可用于关联Webhook事件
`data.payload.call_session_id`	string	通话会话的唯一ID，可用于关联Webhook事件
`data.payload.client_state`	string	从命令中接收的状态

callSiprecStopped

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: siprec.stopped	推送的事件类型
`data.id`	uuid	资源类型标识符
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间戳
`data.payload.call_control_id`	string	用于通过通话控制API下发指令的通话ID
`data.payload.connection_id`	string	通话使用的通话控制应用ID（原Telnyx连接ID）
`data.payload.call_leg_id`	string	通话的唯一ID，可用于关联Webhook事件
`data.payload.call_session_id`	string	通话会话的唯一ID，可用于关联Webhook事件
`data.payload.client_state`	string	从命令中接收的状态
`data.payload.hangup_cause`	string	SIPREC会话停止的Q850原因