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

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)

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)

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)

Send a Whatsapp message

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)

Send a group MMS message

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)

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)

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)

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)

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)

List opt-outs

Retrieve a list of opt-out blocks.

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)

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)

List phone numbers with messaging settings

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)

List mobile phone numbers with messaging settings

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)

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)

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

Webhook payload fields

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.

telnyx-messaging-ruby

NPX Install

Tags

SKILL.md Content

Telnyx Messaging - Ruby

Installation

Setup

Send a message

Retrieve a message

Cancel a scheduled message

Send a Whatsapp message

Send a group MMS message

Send a long code message

Send a message using number pool

Schedule a message

Send a short code message

List opt-outs

Retrieve a phone number with messaging settings

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

List phone numbers with messaging settings

Retrieve a mobile phone number with messaging settings

List mobile phone numbers with messaging settings

Bulk update phone number profiles

Retrieve bulk update status

Webhooks

Webhook payload fields