telnyx-voice-ruby
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinese<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->
<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->
Telnyx Voice - Ruby
Telnyx 语音服务 - Ruby 版本
Installation
安装
bash
gem install telnyxbash
gem install telnyxSetup
配置
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 is already initialized as shown above.
clientruby
require "telnyx"
client = Telnyx::Client.new(
api_key: ENV["TELNYX_API_KEY"], # 这是默认配置,可以省略
)以下所有示例都假设已经按照上述方式完成初始化。
clientError 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
response = client.calls.dial(
connection_id: "7267xxxxxxxxxxxxxx",
from: "+18005550101",
to: "+18005550100"
)
puts(response)Common error codes: invalid API key, insufficient permissions,
resource not found, validation error (check field formats),
rate limited (retry with exponential backoff).
401403404422429所有API调用都可能失败,原因包括网络错误、速率限制(429)、校验错误(422)或认证错误(401)。生产环境代码中请务必处理错误:
ruby
response = client.calls.dial(
connection_id: "7267xxxxxxxxxxxxxx",
from: "+18005550101",
to: "+18005550100"
)
puts(response)常见错误码: API密钥无效, 权限不足, 资源未找到, 校验错误(请检查字段格式), 触发速率限制(请使用指数退避策略重试)。
401403404422429Important Notes
重要说明
- Phone numbers must be in E.164 format (e.g., ). Include the
+13125550001prefix and country code. No spaces, dashes, or parentheses.+ - Pagination: Use for automatic iteration:
.auto_paging_each.page.auto_paging_each { |item| puts item.id }
- 电话号码必须采用E.164格式(例如),需要包含
+13125550001前缀和国家代码,不能包含空格、横杠或括号。+ - 分页: 使用实现自动遍历:
.auto_paging_each。page.auto_paging_each { |item| puts item.id }
Operational Caveats
操作注意事项
- Call Control is event-driven. After or an inbound webhook, issue follow-up commands from webhook handlers using the
dial()in the event payload.call_control_id - Outbound and inbound flows are different: outbound calls start with , while inbound calls must be answered from the incoming webhook before other commands run.
dial() - A publicly reachable webhook endpoint is required for real call control. Without it, calls may connect but your application cannot drive the live call state.
- 呼叫控制是事件驱动的。调用或接收入站webhook后,需要在webhook处理器中使用事件payload中的
dial()来执行后续指令。call_control_id - 外呼和入站流程不同:外呼从开始,而入呼必须先在接收的webhook中应答,才能执行其他指令。
dial() - 要实现完整的呼叫控制,需要一个公网可访问的webhook端点。如果没有该端点,通话可能可以接通,但你的应用无法控制实时通话状态。
Reference Use Rules
参考使用规则
Do not invent Telnyx parameters, enums, response fields, or webhook fields.
- If the parameter, enum, or response field you need is not shown inline in this skill, read references/api-details.md before writing code.
- Before using any operation in , read the optional-parameters section and the response-schemas section.
## Additional Operations - Before reading or matching webhook fields beyond the inline examples, read the webhook payload reference.
请勿自行编造Telnyx参数、枚举值、响应字段或webhook字段。
- 如果你需要的参数、枚举值或响应字段没有在本教程中列出,请在编写代码前阅读references/api-details.md。
- 在使用中的任何接口前,请先阅读可选参数章节和响应结构章节。
## 其他操作 - 如果你需要读取或匹配的webhook字段超出了内置示例的范围,请先阅读webhook payload参考。
Core Tasks
核心任务
Dial an outbound call
拨打外呼电话
Primary voice entrypoint. Agents need the async call-control identifiers returned here.
client.calls.dial()POST /calls| Parameter | Type | Required | Description |
|---|---|---|---|
| string (E.164) | Yes | The DID or SIP URI to dial out to. |
| string (E.164) | Yes | The |
| string (UUID) | Yes | The ID of the Call Control App (formerly ID of the connectio... |
| integer | No | The number of seconds that Telnyx will wait for the call to ... |
| string (UUID) | No | Use this field to set the Billing Group ID for the call. |
| string | No | Use this field to add state to every subsequent webhook. |
| ... | +48 optional params in references/api-details.md |
ruby
response = client.calls.dial(
connection_id: "7267xxxxxxxxxxxxxx",
from: "+18005550101",
to: "+18005550100"
)
puts(response)Primary response fields:
response.data.call_control_idresponse.data.call_leg_idresponse.data.call_session_idresponse.data.is_aliveresponse.data.recording_idresponse.data.call_duration
主要的语音入口。调用方需要这里返回的异步呼叫控制标识符。
client.calls.dial()POST /calls| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| string (E.164) | 是 | 要拨打的DID或SIP URI |
| string (E.164) | 是 | 展示给被叫方的主叫ID号码 |
| string (UUID) | 是 | 呼叫控制应用的ID(之前也叫连接ID) |
| integer | 否 | Telnyx等待呼叫接通的秒数 |
| string (UUID) | 否 | 用于指定该通话所属的账单组ID |
| string | 否 | 用于给后续所有webhook添加自定义状态 |
| ... | 还有48个可选参数,请查看references/api-details.md |
ruby
response = client.calls.dial(
connection_id: "7267xxxxxxxxxxxxxx",
from: "+18005550101",
to: "+18005550100"
)
puts(response)主要响应字段:
response.data.call_control_idresponse.data.call_leg_idresponse.data.call_session_idresponse.data.is_aliveresponse.data.recording_idresponse.data.call_duration
Answer an inbound call
接听来电
Primary inbound call-control command.
client.calls.actions.answer()POST /calls/{call_control_id}/actions/answer| Parameter | Type | Required | Description |
|---|---|---|---|
| string (UUID) | Yes | Unique identifier and token for controlling the call |
| string (UUID) | No | Use this field to set the Billing Group ID for the call. |
| string | No | Use this field to add state to every subsequent webhook. |
| string (URL) | No | Use this field to override the URL for which Telnyx will sen... |
| ... | +26 optional params in references/api-details.md |
ruby
response = client.calls.actions.answer("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")
puts(response)Primary response fields:
response.data.resultresponse.data.recording_id
主要的入站呼叫控制指令。
client.calls.actions.answer()POST /calls/{call_control_id}/actions/answer| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| string (UUID) | 是 | 用于控制通话的唯一标识符和令牌 |
| string (UUID) | 否 | 用于指定该通话所属的账单组ID |
| string | 否 | 用于给后续所有webhook添加自定义状态 |
| string (URL) | 否 | 用于覆盖Telnyx发送事件的默认URL |
| ... | 还有26个可选参数,请查看references/api-details.md |
ruby
response = client.calls.actions.answer("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")
puts(response)主要响应字段:
response.data.resultresponse.data.recording_id
Transfer a live call
转接正在进行的通话
Common post-answer control path with downstream webhook implications.
client.calls.actions.transfer()POST /calls/{call_control_id}/actions/transfer| Parameter | Type | Required | Description |
|---|---|---|---|
| string (E.164) | Yes | The DID or SIP URI to dial out to. |
| string (UUID) | Yes | Unique identifier and token for controlling the call |
| integer | No | The number of seconds that Telnyx will wait for the call to ... |
| string | No | Use this field to add state to every subsequent webhook. |
| string (URL) | No | Use this field to override the URL for which Telnyx will sen... |
| ... | +33 optional params in references/api-details.md |
ruby
response = client.calls.actions.transfer("call_control_id", to: "+18005550100")
puts(response)Primary response fields:
response.data.result
常见的通话应答后控制流程,会触发后续webhook事件。
client.calls.actions.transfer()POST /calls/{call_control_id}/actions/transfer| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| string (E.164) | 是 | 要转接的目标DID或SIP URI |
| string (UUID) | 是 | 用于控制通话的唯一标识符和令牌 |
| integer | 否 | Telnyx等待转接接通的秒数 |
| string | 否 | 用于给后续所有webhook添加自定义状态 |
| string (URL) | 否 | 用于覆盖Telnyx发送事件的默认URL |
| ... | 还有33个可选参数,请查看references/api-details.md |
ruby
response = client.calls.actions.transfer("call_control_id", to: "+18005550100")
puts(response)主要响应字段:
response.data.result
Webhook Verification
Webhook 验证
Telnyx signs webhooks with Ed25519. Each request includes
and headers. Always verify signatures in production:
telnyx-signature-ed25519telnyx-timestampruby
undefinedTelnyx使用Ed25519对webhook进行签名。每个请求都包含和请求头。生产环境请务必验证签名:
telnyx-signature-ed25519telnyx-timestampruby
undefinedIn 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
undefinedpost "/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
签名验证通过 — event是解析后的webhook payload
puts "Received event: #{event.data.event_type}"
status 200
end
undefinedWebhooks
Webhooks
These webhook payload fields are inline because they are part of the primary integration path.
以下webhook payload字段是核心集成路径的一部分,所以直接内置展示。
Call Answered
通话已接听
| Field | Type | Description |
|---|---|---|
| enum: event | Identifies the type of the resource. |
| enum: call.answered | The type of event being delivered. |
| uuid | Identifies the type of resource. |
| date-time | ISO 8601 datetime of when the event occurred. |
| string | Call ID used to issue commands via Call Control API. |
| string | Call Control App ID (formerly Telnyx connection ID) used in the call. |
| string | ID that is unique to the call and can be used to correlate webhook events. |
| string | ID that is unique to the call session and can be used to correlate webhook ev... |
| 字段 | 类型 | 描述 |
|---|---|---|
| enum: event | 标识资源类型 |
| enum: call.answered | 触发的事件类型 |
| uuid | 资源ID |
| date-time | 事件发生的ISO 8601格式时间 |
| string | 用于通过呼叫控制API发送指令的通话ID |
| string | 通话使用的呼叫控制应用ID(之前叫Telnyx连接ID) |
| string | 通话的唯一ID,可用于关联webhook事件 |
| string | 通话会话的唯一ID,可用于关联webhook事件 |
Call Hangup
通话已挂断
| Field | Type | Description |
|---|---|---|
| enum: event | Identifies the type of the resource. |
| enum: call.hangup | The type of event being delivered. |
| uuid | Identifies the type of resource. |
| date-time | ISO 8601 datetime of when the event occurred. |
| string | Call ID used to issue commands via Call Control API. |
| string | Call Control App ID (formerly Telnyx connection ID) used in the call. |
| string | ID that is unique to the call and can be used to correlate webhook events. |
| string | ID that is unique to the call session and can be used to correlate webhook ev... |
| 字段 | 类型 | 描述 |
|---|---|---|
| enum: event | 标识资源类型 |
| enum: call.hangup | 触发的事件类型 |
| uuid | 资源ID |
| date-time | 事件发生的ISO 8601格式时间 |
| string | 用于通过呼叫控制API发送指令的通话ID |
| string | 通话使用的呼叫控制应用ID(之前叫Telnyx连接ID) |
| string | 通话的唯一ID,可用于关联webhook事件 |
| string | 通话会话的唯一ID,可用于关联webhook事件 |
Call Initiated
通话已发起
| Field | Type | Description |
|---|---|---|
| enum: event | Identifies the type of the resource. |
| enum: call.initiated | The type of event being delivered. |
| uuid | Identifies the type of resource. |
| date-time | ISO 8601 datetime of when the event occurred. |
| string | Call ID used to issue commands via Call Control API. |
| string | Call Control App ID (formerly Telnyx connection ID) used in the call. |
| string | The list of comma-separated codecs enabled for the connection. |
| string | The list of comma-separated codecs offered by caller. |
If you need webhook fields that are not listed inline here, read the webhook payload reference before writing the handler.
| 字段 | 类型 | 描述 |
|---|---|---|
| enum: event | 标识资源类型 |
| enum: call.initiated | 触发的事件类型 |
| uuid | 资源ID |
| date-time | 事件发生的ISO 8601格式时间 |
| string | 用于通过呼叫控制API发送指令的通话ID |
| string | 通话使用的呼叫控制应用ID(之前叫Telnyx连接ID) |
| string | 连接启用的编解码器列表,用逗号分隔 |
| string | 主叫方提供的编解码器列表,用逗号分隔 |
如果你需要的webhook字段没有在这里列出,请在编写处理器前阅读webhook payload参考。
Important Supporting Operations
重要支持操作
Use these when the core tasks above are close to your flow, but you need a common variation or follow-up step.
当上述核心任务和你的流程接近,但需要常见的变体或后续步骤时,可以使用这些操作。
Hangup call
挂断通话
End a live call from your webhook-driven control flow.
client.calls.actions.hangup()POST /calls/{call_control_id}/actions/hangup| Parameter | Type | Required | Description |
|---|---|---|---|
| string (UUID) | Yes | Unique identifier and token for controlling the call |
| string | No | Use this field to add state to every subsequent webhook. |
| string (UUID) | No | Use this field to avoid duplicate commands. |
| array[object] | No | Custom headers to be added to the SIP BYE message. |
ruby
response = client.calls.actions.hangup("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")
puts(response)Primary response fields:
response.data.result
从webhook驱动的控制流程中结束正在进行的通话。
client.calls.actions.hangup()POST /calls/{call_control_id}/actions/hangup| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| string (UUID) | 是 | 用于控制通话的唯一标识符和令牌 |
| string | 否 | 用于给后续所有webhook添加自定义状态 |
| string (UUID) | 否 | 用于避免重复执行指令 |
| array[object] | 否 | 添加到SIP BYE消息中的自定义请求头 |
ruby
response = client.calls.actions.hangup("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")
puts(response)主要响应字段:
response.data.result
Bridge calls
桥接通话
Trigger a follow-up action in an existing workflow rather than creating a new top-level resource.
client.calls.actions.bridge()POST /calls/{call_control_id}/actions/bridge| Parameter | Type | Required | Description |
|---|---|---|---|
| string (UUID) | Yes | The Call Control ID of the call you want to bridge with, can... |
| string (UUID) | Yes | Unique identifier and token for controlling the call |
| string | No | Use this field to add state to every subsequent webhook. |
| string (UUID) | No | Use this field to avoid duplicate commands. |
| string (UUID) | No | The ID of the video room you want to bridge with, can't be u... |
| ... | +16 optional params in references/api-details.md |
ruby
response = client.calls.actions.bridge(
"call_control_id",
call_control_id_to_bridge_with: "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg"
)
puts(response)Primary response fields:
response.data.result
在现有工作流中触发后续操作,而无需创建新的顶层资源。
client.calls.actions.bridge()POST /calls/{call_control_id}/actions/bridge| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| string (UUID) | 是 | 要桥接的目标通话的呼叫控制ID |
| string (UUID) | 是 | 用于控制当前通话的唯一标识符和令牌 |
| string | 否 | 用于给后续所有webhook添加自定义状态 |
| string (UUID) | 否 | 用于避免重复执行指令 |
| string (UUID) | 否 | 要桥接的视频房间ID,不能和其他桥接目标同时使用 |
| ... | 还有16个可选参数,请查看references/api-details.md |
ruby
response = client.calls.actions.bridge(
"call_control_id",
call_control_id_to_bridge_with: "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg"
)
puts(response)主要响应字段:
response.data.result
Reject a call
拒接通话
Trigger a follow-up action in an existing workflow rather than creating a new top-level resource.
client.calls.actions.reject()POST /calls/{call_control_id}/actions/reject| Parameter | Type | Required | Description |
|---|---|---|---|
| enum (CALL_REJECTED, USER_BUSY) | Yes | Cause for call rejection. |
| string (UUID) | Yes | Unique identifier and token for controlling the call |
| string | No | Use this field to add state to every subsequent webhook. |
| string (UUID) | No | Use this field to avoid duplicate commands. |
ruby
response = client.calls.actions.reject("call_control_id", cause: :USER_BUSY)
puts(response)Primary response fields:
response.data.result
在现有工作流中触发后续操作,而无需创建新的顶层资源。
client.calls.actions.reject()POST /calls/{call_control_id}/actions/reject| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| enum (CALL_REJECTED, USER_BUSY) | 是 | 拒接通话的原因 |
| string (UUID) | 是 | 用于控制通话的唯一标识符和令牌 |
| string | 否 | 用于给后续所有webhook添加自定义状态 |
| string (UUID) | 否 | 用于避免重复执行指令 |
ruby
response = client.calls.actions.reject("call_control_id", cause: :USER_BUSY)
puts(response)主要响应字段:
response.data.result
Retrieve a call status
获取通话状态
Fetch the current state before updating, deleting, or making control-flow decisions.
client.calls.retrieve_status()GET /calls/{call_control_id}| Parameter | Type | Required | Description |
|---|---|---|---|
| string (UUID) | Yes | Unique identifier and token for controlling the call |
ruby
response = client.calls.retrieve_status("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")
puts(response)Primary response fields:
response.data.call_control_idresponse.data.call_durationresponse.data.call_leg_idresponse.data.call_session_idresponse.data.client_stateresponse.data.end_time
在更新、删除通话或做出控制流程决策前,获取当前通话状态。
client.calls.retrieve_status()GET /calls/{call_control_id}| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| string (UUID) | 是 | 用于控制通话的唯一标识符和令牌 |
ruby
response = client.calls.retrieve_status("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")
puts(response)主要响应字段:
response.data.call_control_idresponse.data.call_durationresponse.data.call_leg_idresponse.data.call_session_idresponse.data.client_stateresponse.data.end_time
List all active calls for given connection
列出指定连接下所有活跃通话
Fetch the current state before updating, deleting, or making control-flow decisions.
client.connections.list_active_calls()GET /connections/{connection_id}/active_calls| Parameter | Type | Required | Description |
|---|---|---|---|
| string (UUID) | Yes | Telnyx connection id |
| object | No | Consolidated page parameter (deepObject style). |
ruby
page = client.connections.list_active_calls("1293384261075731461")
puts(page)Response wrapper:
- items:
page.data - pagination:
page.meta
Primary item fields:
call_control_idcall_durationcall_leg_idcall_session_idclient_staterecord_type
在更新、删除通话或做出控制流程决策前,获取当前状态。
client.connections.list_active_calls()GET /connections/{connection_id}/active_calls| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| string (UUID) | 是 | Telnyx连接ID |
| object | 否 | 统一分页参数(deepObject格式) |
ruby
page = client.connections.list_active_calls("1293384261075731461")
puts(page)响应结构:
- 列表项:
page.data - 分页信息:
page.meta
主要列表项字段:
call_control_idcall_durationcall_leg_idcall_session_idclient_staterecord_type
List call control applications
列出呼叫控制应用
Inspect available resources or choose an existing resource before mutating it.
client.call_control_applications.list()GET /call_control_applications| Parameter | Type | Required | Description |
|---|---|---|---|
| enum (created_at, connection_name, active) | No | Specifies the sort order for results. |
| object | No | Consolidated filter parameter (deepObject style). |
| object | No | Consolidated page parameter (deepObject style). |
ruby
page = client.call_control_applications.list
puts(page)Response wrapper:
- items:
page.data - pagination:
page.meta
Primary item fields:
idcreated_atupdated_atactiveanchorsite_overrideapplication_name
在修改资源前,检查可用资源或选择现有资源。
client.call_control_applications.list()GET /call_control_applications| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| enum (created_at, connection_name, active) | 否 | 指定结果的排序顺序 |
| object | 否 | 统一过滤参数(deepObject格式) |
| object | 否 | 统一分页参数(deepObject格式) |
ruby
page = client.call_control_applications.list
puts(page)响应结构:
- 列表项:
page.data - 分页信息:
page.meta
主要列表项字段:
idcreated_atupdated_atactiveanchorsite_overrideapplication_name
Additional Operations
其他操作
Use the core tasks above first. The operations below are indexed here with exact SDK methods and required params; use references/api-details.md for full optional params, response schemas, and lower-frequency webhook payloads.
Before using any operation below, read the optional-parameters section and the response-schemas section so you do not guess missing fields.
| Operation | SDK method | Endpoint | Use when | Required params |
|---|---|---|---|---|
| Create a call control application | | | Create or provision an additional resource when the core tasks do not cover this flow. | |
| Retrieve a call control application | | | Fetch the current state before updating, deleting, or making control-flow decisions. | |
| Update a call control application | | | Modify an existing resource without recreating it. | |
| Delete a call control application | | | Remove, detach, or clean up an existing resource. | |
| SIP Refer a call | | | Trigger a follow-up action in an existing workflow rather than creating a new top-level resource. | |
| Send SIP info | | | Trigger a follow-up action in an existing workflow rather than creating a new top-level resource. | |
请优先使用上述核心任务。下方的操作在此处列出了准确的SDK方法和必填参数;完整的可选参数、响应结构和低频webhook payload请查看references/api-details.md。
在使用下方任何操作前,请先阅读可选参数章节和响应结构章节,避免猜测缺失的字段。
| 操作 | SDK方法 | 接口地址 | 使用场景 | 必填参数 |
|---|---|---|---|---|
| 创建呼叫控制应用 | | | 当核心任务无法覆盖需求时,创建或provision额外资源 | |
| 获取呼叫控制应用 | | | 在更新、删除应用或做出控制流程决策前获取当前状态 | |
| 更新呼叫控制应用 | | | 修改现有资源而无需重新创建 | |
| 删除呼叫控制应用 | | | 移除、解绑或清理现有资源 | |
| SIP转接通话 | | | 在现有工作流中触发后续操作,而无需创建新的顶层资源 | |
| 发送SIP信息 | | | 在现有工作流中触发后续操作,而无需创建新的顶层资源 | |
Other Webhook Events
其他Webhook事件
| Event | | Description |
|---|---|---|
| | Call Bridged |
For exhaustive optional parameters, full response schemas, and complete webhook payloads, see references/api-details.md.
| 事件 | | 描述 |
|---|---|---|
| | 通话已桥接 |
如需完整的可选参数、全量响应结构和完整的webhook payload,请查看references/api-details.md。