telnyx-messaging-ruby

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Telnyx Messaging - 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

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

Send a message

发送消息

Send a message with a Phone Number, Alphanumeric Sender ID, Short Code or Number Pool.

POST /messages

— Required:

to

Optional:

auto_detect

(boolean),

encoding

(enum),

from

(string),

media_urls

(array[string]),

messaging_profile_id

(string),

send_at

(date-time),

subject

(string),

text

(string),

type

(enum),

use_profile_webhooks

(boolean),

webhook_failover_url

(url),

webhook_url

(url)

ruby

response = client.messages.send_(to: "+18445550001")

puts(response)

可使用电话号码、字母数字发送方ID、短码或号码池发送消息。

POST /messages

— 必填参数：

to

可选参数：

auto_detect

（布尔值）、

encoding

（枚举）、

from

（字符串）、

media_urls

（字符串数组）、

messaging_profile_id

（字符串）、

send_at

（日期时间）、

subject

（字符串）、

text

（字符串）、

type

（枚举）、

use_profile_webhooks

（布尔值）、

webhook_failover_url

（URL）、

webhook_url

（URL）

ruby

response = client.messages.send_(to: "+18445550001")

puts(response)

Retrieve a message

检索消息

Note: This API endpoint can only retrieve messages that are no older than 10 days since their creation.

GET /messages/{id}

ruby

message = client.messages.retrieve("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")

puts(message)

注意：此API端点仅能检索创建时间不超过10天的消息。

GET /messages/{id}

ruby

message = client.messages.retrieve("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")

puts(message)

Cancel a scheduled message

取消已调度的消息

Cancel a scheduled message that has not yet been sent.

DELETE /messages/{id}

ruby

response = client.messages.cancel_scheduled("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")

puts(response)

取消尚未发送的已调度消息。

DELETE /messages/{id}

ruby

response = client.messages.cancel_scheduled("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")

puts(response)

Send a Whatsapp message

发送WhatsApp消息

POST /messages/whatsapp

— Required:

from

to

whatsapp_message

Optional:

type

(enum),

webhook_url

(url)

ruby

response = client.messages.send_whatsapp(from: "+13125551234", to: "+13125551234", whatsapp_message: {})

puts(response)

POST /messages/whatsapp

— 必填参数：

from

to

whatsapp_message

可选参数：

type

（枚举）、

webhook_url

（URL）

ruby

response = client.messages.send_whatsapp(from: "+13125551234", to: "+13125551234", whatsapp_message: {})

puts(response)

Send a group MMS message

发送群组MMS消息

POST /messages/group_mms

— Required:

from

to

Optional:

media_urls

(array[string]),

subject

(string),

text

(string),

use_profile_webhooks

(boolean),

webhook_failover_url

(url),

webhook_url

(url)

ruby

response = client.messages.send_group_mms(from: "+13125551234", to: ["+18655551234", "+14155551234"])

puts(response)

POST /messages/group_mms

— 必填参数：

from

to

可选参数：

media_urls

（字符串数组）、

subject

（字符串）、

text

（字符串）、

use_profile_webhooks

（布尔值）、

webhook_failover_url

（URL）、

webhook_url

（URL）

ruby

response = client.messages.send_group_mms(from: "+13125551234", to: ["+18655551234", "+14155551234"])

puts(response)

Send a long code message

发送长码消息

POST /messages/long_code

— Required:

from

to

Optional:

auto_detect

(boolean),

encoding

(enum),

media_urls

(array[string]),

subject

(string),

text

(string),

type

(enum),

use_profile_webhooks

(boolean),

webhook_failover_url

(url),

webhook_url

(url)

ruby

response = client.messages.send_long_code(from: "+18445550001", to: "+13125550002")

puts(response)

POST /messages/long_code

— 必填参数：

from

to

可选参数：

auto_detect

（布尔值）、

encoding

（枚举）、

media_urls

（字符串数组）、

subject

（字符串）、

text

（字符串）、

type

（枚举）、

use_profile_webhooks

（布尔值）、

webhook_failover_url

（URL）、

webhook_url

（URL）

ruby

response = client.messages.send_long_code(from: "+18445550001", to: "+13125550002")

puts(response)

Send a message using number pool

使用号码池发送消息

POST /messages/number_pool

— Required:

to

messaging_profile_id

Optional:

auto_detect

(boolean),

encoding

(enum),

media_urls

(array[string]),

subject

(string),

text

(string),

type

(enum),

use_profile_webhooks

(boolean),

webhook_failover_url

(url),

webhook_url

(url)

ruby

response = client.messages.send_number_pool(
  messaging_profile_id: "abc85f64-5717-4562-b3fc-2c9600000000",
  to: "+13125550002"
)

puts(response)

POST /messages/number_pool

— 必填参数：

to

messaging_profile_id

可选参数：

auto_detect

（布尔值）、

encoding

（枚举）、

media_urls

（字符串数组）、

subject

（字符串）、

text

（字符串）、

type

（枚举）、

use_profile_webhooks

（布尔值）、

webhook_failover_url

（URL）、

webhook_url

（URL）

ruby

response = client.messages.send_number_pool(
  messaging_profile_id: "abc85f64-5717-4562-b3fc-2c9600000000",
  to: "+13125550002"
)

puts(response)

Schedule a message

调度消息

Schedule a message with a Phone Number, Alphanumeric Sender ID, Short Code or Number Pool.

POST /messages/schedule

— Required:

to

Optional:

auto_detect

(boolean),

from

(string),

media_urls

(array[string]),

messaging_profile_id

(string),

send_at

(date-time),

subject

(string),

text

(string),

type

(enum),

use_profile_webhooks

(boolean),

webhook_failover_url

(url),

webhook_url

(url)

ruby

response = client.messages.schedule(to: "+18445550001")

puts(response)

可使用电话号码、字母数字发送方ID、短码或号码池调度消息。

POST /messages/schedule

— 必填参数：

to

可选参数：

auto_detect

（布尔值）、

from

（字符串）、

media_urls

（字符串数组）、

messaging_profile_id

（字符串）、

send_at

（日期时间）、

subject

（字符串）、

text

（字符串）、

type

（枚举）、

use_profile_webhooks

（布尔值）、

webhook_failover_url

（URL）、

webhook_url

（URL）

ruby

response = client.messages.schedule(to: "+18445550001")

puts(response)

Send a short code message

发送短码消息

POST /messages/short_code

— Required:

from

to

Optional:

auto_detect

(boolean),

encoding

(enum),

media_urls

(array[string]),

subject

(string),

text

(string),

type

(enum),

use_profile_webhooks

(boolean),

webhook_failover_url

(url),

webhook_url

(url)

ruby

response = client.messages.send_short_code(from: "+18445550001", to: "+18445550001")

puts(response)

POST /messages/short_code

— 必填参数：

from

to

可选参数：

auto_detect

（布尔值）、

encoding

（枚举）、

media_urls

（字符串数组）、

subject

（字符串）、

text

（字符串）、

type

（枚举）、

use_profile_webhooks

（布尔值）、

webhook_failover_url

（URL）、

webhook_url

（URL）

ruby

response = client.messages.send_short_code(from: "+18445550001", to: "+18445550001")

puts(response)

List opt-outs

列出退订记录

Retrieve a list of opt-out blocks.

GET /messaging_optouts

ruby

page = client.messaging_optouts.list

puts(page)

检索退订阻止列表。

GET /messaging_optouts

ruby

page = client.messaging_optouts.list

puts(page)

Retrieve a phone number with messaging settings

检索带消息设置的电话号码

GET /phone_numbers/{id}/messaging

ruby

messaging = client.phone_numbers.messaging.retrieve("id")

puts(messaging)

GET /phone_numbers/{id}/messaging

ruby

messaging = client.phone_numbers.messaging.retrieve("id")

puts(messaging)

Update the messaging profile and/or messaging product of a phone number

更新电话号码的消息配置文件和/或消息产品

PATCH /phone_numbers/{id}/messaging

Optional:

messaging_product

(string),

messaging_profile_id

(string),

tags

(array[string])

ruby

messaging = client.phone_numbers.messaging.update("id")

puts(messaging)

PATCH /phone_numbers/{id}/messaging

可选参数：

messaging_product

（字符串）、

messaging_profile_id

（字符串）、

tags

（字符串数组）

ruby

messaging = client.phone_numbers.messaging.update("id")

puts(messaging)

List phone numbers with messaging settings

列出带消息设置的电话号码

GET /phone_numbers/messaging

ruby

page = client.phone_numbers.messaging.list

puts(page)

GET /phone_numbers/messaging

ruby

page = client.phone_numbers.messaging.list

puts(page)

Retrieve a mobile phone number with messaging settings

检索带消息设置的移动电话号码

GET /mobile_phone_numbers/{id}/messaging

ruby

messaging = client.mobile_phone_numbers.messaging.retrieve("id")

puts(messaging)

GET /mobile_phone_numbers/{id}/messaging

ruby

messaging = client.mobile_phone_numbers.messaging.retrieve("id")

puts(messaging)

List mobile phone numbers with messaging settings

列出带消息设置的移动电话号码

GET /mobile_phone_numbers/messaging

ruby

page = client.mobile_phone_numbers.messaging.list

puts(page)

GET /mobile_phone_numbers/messaging

ruby

page = client.mobile_phone_numbers.messaging.list

puts(page)

Bulk update phone number profiles

批量更新电话号码配置文件

POST /messaging_numbers/bulk_updates

— Required:

messaging_profile_id

numbers

Optional:

assign_only

(boolean)

ruby

messaging_numbers_bulk_update = client.messaging_numbers_bulk_updates.create(
  messaging_profile_id: "00000000-0000-0000-0000-000000000000",
  numbers: ["+18880000000", "+18880000001", "+18880000002"]
)

puts(messaging_numbers_bulk_update)

POST /messaging_numbers/bulk_updates

— 必填参数：

messaging_profile_id

numbers

可选参数：

assign_only

（布尔值）

ruby

messaging_numbers_bulk_update = client.messaging_numbers_bulk_updates.create(
  messaging_profile_id: "00000000-0000-0000-0000-000000000000",
  numbers: ["+18880000000", "+18880000001", "+18880000002"]
)

puts(messaging_numbers_bulk_update)

Retrieve bulk update status

检索批量更新状态

GET /messaging_numbers/bulk_updates/{order_id}

ruby

messaging_numbers_bulk_update = client.messaging_numbers_bulk_updates.retrieve("order_id")

puts(messaging_numbers_bulk_update)

GET /messaging_numbers/bulk_updates/{order_id}

ruby

messaging_numbers_bulk_update = client.messaging_numbers_bulk_updates.retrieve("order_id")

puts(messaging_numbers_bulk_update)

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
`deliveryUpdate`	Delivery Update
`inboundMessage`	Inbound Message
`replacedLinkClick`	Replaced Link Click

以下Webhook事件将发送到您配置的Webhook URL。所有Webhook均包含

telnyx-timestamp

和

telnyx-signature-ed25519

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

事件	描述
`deliveryUpdate`	投递更新
`inboundMessage`	入站消息
`replacedLinkClick`	替换链接点击

Webhook payload fields

Webhook 负载字段

deliveryUpdate

Field	Type	Description
`data.record_type`	enum	Identifies the type of the resource.
`data.id`	uuid	Identifies the type of resource.
`data.event_type`	enum	The type of event being delivered.
`data.occurred_at`	date-time	ISO 8601 formatted date indicating when the resource was created.
`data.payload.record_type`	enum	Identifies the type of the resource.
`data.payload.direction`	enum	The direction of the message.
`data.payload.id`	uuid	Identifies the type of resource.
`data.payload.type`	enum	The type of message.
`data.payload.messaging_profile_id`	string	Unique identifier for a messaging profile.
`data.payload.organization_id`	uuid	The id of the organization the messaging profile belongs to.
`data.payload.to`	array[object]
`data.payload.cc`	array[object]
`data.payload.text`	string	Message body (i.e., content) as a non-empty string.
`data.payload.subject`	['string', 'null']	Subject of multimedia message
`data.payload.media`	array[object]
`data.payload.webhook_url`	url	The URL where webhooks related to this message will be sent.
`data.payload.webhook_failover_url`	url	The failover URL where webhooks related to this message will be sent if sending to the primary URL fails.
`data.payload.encoding`	string	Encoding scheme used for the message body.
`data.payload.parts`	integer	Number of parts into which the message's body must be split.
`data.payload.tags`	array[string]	Tags associated with the resource.
`data.payload.cost`	['object', 'null']
`data.payload.cost_breakdown`	['object', 'null']	Detailed breakdown of the message cost components.
`data.payload.tcr_campaign_id`	['string', 'null']	The Campaign Registry (TCR) campaign ID associated with the message.
`data.payload.tcr_campaign_billable`	boolean	Indicates whether the TCR campaign is billable.
`data.payload.tcr_campaign_registered`	['string', 'null']	The registration status of the TCR campaign.
`data.payload.received_at`	date-time	ISO 8601 formatted date indicating when the message request was received.
`data.payload.sent_at`	date-time	ISO 8601 formatted date indicating when the message was sent.
`data.payload.completed_at`	date-time	ISO 8601 formatted date indicating when the message was finalized.
`data.payload.valid_until`	date-time	Message must be out of the queue by this time or else it will be discarded and marked as 'sending_failed'.
`data.payload.errors`	array[object]	These errors may point at addressees when referring to unsuccessful/unconfirmed delivery statuses.
`data.payload.smart_encoding_applied`	boolean	Indicates whether smart encoding was applied to this message.
`meta.attempt`	integer	Number of attempts to deliver the webhook event.
`meta.delivered_to`	url	The webhook URL the event was delivered to.

inboundMessage

Field	Type	Description
`data.record_type`	enum	Identifies the type of the resource.
`data.id`	uuid	Identifies the type of resource.
`data.event_type`	enum	The type of event being delivered.
`data.occurred_at`	date-time	ISO 8601 formatted date indicating when the resource was created.
`data.payload.record_type`	enum	Identifies the type of the resource.
`data.payload.direction`	enum	The direction of the message.
`data.payload.id`	uuid	Identifies the type of resource.
`data.payload.type`	enum	The type of message.
`data.payload.messaging_profile_id`	string	Unique identifier for a messaging profile.
`data.payload.organization_id`	string	Unique identifier for a messaging profile.
`data.payload.to`	array[object]
`data.payload.cc`	array[object]
`data.payload.text`	string	Message body (i.e., content) as a non-empty string.
`data.payload.subject`	['string', 'null']	Message subject.
`data.payload.media`	array[object]
`data.payload.webhook_url`	url	The URL where webhooks related to this message will be sent.
`data.payload.webhook_failover_url`	url	The failover URL where webhooks related to this message will be sent if sending to the primary URL fails.
`data.payload.encoding`	string	Encoding scheme used for the message body.
`data.payload.parts`	integer	Number of parts into which the message's body must be split.
`data.payload.tags`	array[string]	Tags associated with the resource.
`data.payload.cost`	['object', 'null']
`data.payload.cost_breakdown`	['object', 'null']	Detailed breakdown of the message cost components.
`data.payload.tcr_campaign_id`	['string', 'null']	The Campaign Registry (TCR) campaign ID associated with the message.
`data.payload.tcr_campaign_billable`	boolean	Indicates whether the TCR campaign is billable.
`data.payload.tcr_campaign_registered`	['string', 'null']	The registration status of the TCR campaign.
`data.payload.received_at`	date-time	ISO 8601 formatted date indicating when the message request was received.
`data.payload.sent_at`	date-time	Not used for inbound messages.
`data.payload.completed_at`	date-time	Not used for inbound messages.
`data.payload.valid_until`	date-time	Not used for inbound messages.
`data.payload.errors`	array[object]	These errors may point at addressees when referring to unsuccessful/unconfirmed delivery statuses.

replacedLinkClick

Field	Type	Description
`data.record_type`	string	Identifies the type of the resource.
`data.url`	string	The original link that was sent in the message.
`data.to`	string	Sending address (+E.164 formatted phone number, alphanumeric sender ID, or short code).
`data.message_id`	uuid	The message ID associated with the clicked link.
`data.time_clicked`	date-time	ISO 8601 formatted date indicating when the message request was received.

deliveryUpdate

字段	类型	描述
`data.record_type`	枚举	标识资源类型。
`data.id`	UUID	标识资源类型。
`data.event_type`	枚举	投递的事件类型。
`data.occurred_at`	日期时间	ISO 8601格式的日期，指示资源创建时间。
`data.payload.record_type`	枚举	标识资源类型。
`data.payload.direction`	枚举	消息的方向。
`data.payload.id`	UUID	标识资源类型。
`data.payload.type`	枚举	消息类型。
`data.payload.messaging_profile_id`	字符串	消息配置文件的唯一标识符。
`data.payload.organization_id`	UUID	消息配置文件所属组织的ID。
`data.payload.to`	对象数组
`data.payload.cc`	对象数组
`data.payload.text`	字符串	消息正文（即内容），非空字符串。
`data.payload.subject`	['字符串', '空值']	多媒体消息的主题
`data.payload.media`	对象数组
`data.payload.webhook_url`	URL	与该消息相关的Webhook将发送到的URL。
`data.payload.webhook_failover_url`	URL	如果主URL投递失败，与该消息相关的Webhook将发送到的故障转移URL。
`data.payload.encoding`	字符串	消息正文使用的编码方案。
`data.payload.parts`	整数	消息正文必须拆分的部分数量。
`data.payload.tags`	字符串数组	与资源关联的标签。
`data.payload.cost`	['对象', '空值']
`data.payload.cost_breakdown`	['对象', '空值']	消息成本构成的详细细分。
`data.payload.tcr_campaign_id`	['字符串', '空值']	与消息关联的Campaign Registry (TCR) 活动ID。
`data.payload.tcr_campaign_billable`	布尔值	指示TCR活动是否可计费。
`data.payload.tcr_campaign_registered`	['字符串', '空值']	TCR活动的注册状态。
`data.payload.received_at`	日期时间	ISO 8601格式的日期，指示消息请求的接收时间。
`data.payload.sent_at`	日期时间	ISO 8601格式的日期，指示消息的发送时间。
`data.payload.completed_at`	日期时间	ISO 8601格式的日期，指示消息的完成时间。
`data.payload.valid_until`	日期时间	消息必须在此时间前离开队列，否则将被丢弃并标记为'sending_failed'。
`data.payload.errors`	对象数组	当涉及未成功/未确认的投递状态时，这些错误可能指向收件人。
`data.payload.smart_encoding_applied`	布尔值	指示是否对该消息应用了智能编码。
`meta.attempt`	整数	投递Webhook事件的尝试次数。
`meta.delivered_to`	URL	事件投递到的Webhook URL。

inboundMessage

字段	类型	描述
`data.record_type`	枚举	标识资源类型。
`data.id`	UUID	标识资源类型。
`data.event_type`	枚举	投递的事件类型。
`data.occurred_at`	日期时间	ISO 8601格式的日期，指示资源创建时间。
`data.payload.record_type`	枚举	标识资源类型。
`data.payload.direction`	枚举	消息的方向。
`data.payload.id`	UUID	标识资源类型。
`data.payload.type`	枚举	消息类型。
`data.payload.messaging_profile_id`	字符串	消息配置文件的唯一标识符。
`data.payload.organization_id`	字符串	消息配置文件的唯一标识符。
`data.payload.to`	对象数组
`data.payload.cc`	对象数组
`data.payload.text`	字符串	消息正文（即内容），非空字符串。
`data.payload.subject`	['字符串', '空值']	消息主题。
`data.payload.media`	对象数组
`data.payload.webhook_url`	URL	与该消息相关的Webhook将发送到的URL。
`data.payload.webhook_failover_url`	URL	如果主URL投递失败，与该消息相关的Webhook将发送到的故障转移URL。
`data.payload.encoding`	字符串	消息正文使用的编码方案。
`data.payload.parts`	整数	消息正文必须拆分的部分数量。
`data.payload.tags`	字符串数组	与资源关联的标签。
`data.payload.cost`	['对象', '空值']
`data.payload.cost_breakdown`	['对象', '空值']	消息成本构成的详细细分。
`data.payload.tcr_campaign_id`	['字符串', '空值']	与消息关联的Campaign Registry (TCR) 活动ID。
`data.payload.tcr_campaign_billable`	布尔值	指示TCR活动是否可计费。
`data.payload.tcr_campaign_registered`	['字符串', '空值']	TCR活动的注册状态。
`data.payload.received_at`	日期时间	ISO 8601格式的日期，指示消息请求的接收时间。
`data.payload.sent_at`	日期时间	入站消息不使用此字段。
`data.payload.completed_at`	日期时间	入站消息不使用此字段。
`data.payload.valid_until`	日期时间	入站消息不使用此字段。
`data.payload.errors`	对象数组	当涉及未成功/未确认的投递状态时，这些错误可能指向收件人。

replacedLinkClick

字段	类型	描述
`data.record_type`	字符串	标识资源类型。
`data.url`	字符串	消息中发送的原始链接。
`data.to`	字符串	发送地址（+E.164格式电话号码、字母数字发送方ID或短码）。
`data.message_id`	UUID	与点击链接关联的消息ID。
`data.time_clicked`	日期时间	ISO 8601格式的日期，指示消息请求的接收时间。