Telstra Messaging API Ruby SDK

⚠️ Important Notice

• Ruby 3.3+ Required - This gem requires Ruby version 3.3 or higher
• Unofficial Gem - This is an unofficial gem, forked originally from the now unsupported official gem (it seems) that was at Telstra/MessagingAPI-SDK-Ruby but removed somewtime around July 2025.
  • The functionailiy here is unchanged, though I've removed support for Ruby 3.2 and below, and added a docs/ folder, including sequence diagrams and examples, and just improved documentation for usage overall.

An unofficial Ruby gem for integrating with the Telstra Messaging API. Send and receive SMS and MMS messages globally using Telstra's enterprise-grade messaging platform.

Features

Feature	Description
Send SMS/MMS	Send text and multimedia messages to mobile devices globally
Receive Messages	Handle inbound SMS/MMS via webhooks to your application
Delivery Tracking	Get real-time delivery status and read receipts
Two-Way Messaging	Enable reply conversations with automatic message tracking
Broadcast Messages	Send to multiple recipients in a single API call
Rich Content	Support for images, videos, audio, and documents in MMS
Unicode Support	Full UTF-8 character set including emojis
Enterprise Features	Dedicated numbers, alphanumeric sender IDs, and priority messaging

Quick Start

Add to your Gemfile:

gem 'Telstra_Messaging', '~> 1.0.6'

Basic usage:

require 'Telstra_Messaging'

# Configure authentication
Telstra_Messaging.configure do |config|
  config.access_token = 'YOUR_ACCESS_TOKEN'
end

# Send an SMS
messaging_api = Telstra_Messaging::MessagingApi.new
sms_request = Telstra_Messaging::SendSMSRequest.new(
  to: "+61412345678",
  body: "Hello from Telstra!"
)

result = messaging_api.send_sms(sms_request)
puts "Message sent! ID: #{result.message_id}"

📖 Documentation

• Developer Guide - Comprehensive integration guide with webhook payloads, examples, and testing
• Message Flows - Visual sequence diagrams showing API interaction patterns
• API Reference - Detailed API documentation for all classes and methods

Requirements

• Ruby 3.3+ - This gem requires Ruby version 3.3 or higher

Installation

From RubyGems

gem install Telstra_Messaging

With Bundler

Add to your Gemfile:

gem 'Telstra_Messaging', '~> 1.0.6'

Then run:

bundle install

From Git

gem 'Telstra_Messaging', git: 'https://github.com/Telstra/MessagingAPI-SDK-Ruby.git'

Build from Source

git clone https://github.com/Telstra/MessagingAPI-SDK-Ruby.git
cd MessagingAPI-SDK-Ruby
gem build Telstra_Messaging.gemspec
gem install ./Telstra_Messaging-1.0.6.gem

Getting Started

1. Get API Access

1. Register at dev.telstra.com
2. Create an application and select API Free Trial product
3. Note your Client Key and Client Secret for authentication
4. Get 1000 free messages to start (additional messages available for purchase)

2. Authentication

# Get OAuth2 token
auth_api = Telstra_Messaging::AuthenticationApi.new
result = auth_api.auth_token(
  'your_client_id',
  'your_client_secret', 
  'client_credentials'
)
access_token = result.access_token

3. Provision a Number

# Get a dedicated number for sending/receiving
provisioning_api = Telstra_Messaging::ProvisioningApi.new
provision_request = Telstra_Messaging::ProvisionNumberRequest.new(
  active_days: 30,
  notify_url: "https://yourapp.com/webhooks/inbound"
)
result = provisioning_api.create_subscription(provision_request)
puts "Your number: #{result.destination_address}"

4. Send Your First Message

sms_request = Telstra_Messaging::SendSMSRequest.new(
  to: "+61412345678",
  body: "Hello from Telstra API!"
)
result = messaging_api.send_sms(sms_request)
puts "Message sent! ID: #{result.message_id}"

Key Use Cases

Send SMS

sms_request = Telstra_Messaging::SendSMSRequest.new(
  to: "+61412345678",
  body: "Your verification code is: 123456",
  notify_url: "https://yourapp.com/delivery-status"
)
result = messaging_api.send_sms(sms_request)

Send MMS with Image

# Encode image as base64
image_data = Base64.encode64(File.read("image.jpg"))

mms_content = Telstra_Messaging::MMSContent.new(
  type: "image/jpeg",
  filename: "image.jpg",
  payload: image_data
)

mms_request = Telstra_Messaging::SendMmsRequest.new(
  to: "+61412345678",
  subject: "Check this out!",
  mms_content: [mms_content]
)
result = messaging_api.send_mms(mms_request)

Handle Inbound Messages

# In your webhook endpoint
def webhook_handler
  payload = JSON.parse(request.body.read)
  
  case request.headers['X-Webhook-Event']
  when 'inbound-sms'
    handle_inbound_sms(payload)
  when 'inbound-mms' 
    handle_inbound_mms(payload)
  when 'delivery-status'
    handle_delivery_status(payload)
  end
  
  render json: { status: 'received' }
end

Two-Way Conversations

# Enable reply tracking
sms_request = Telstra_Messaging::SendSMSRequest.new(
  to: "+61412345678", 
  body: "Reply with A, B, or C for your choice",
  reply_request: true,
  notify_url: "https://yourapp.com/webhooks/replies"
)
result = messaging_api.send_sms(sms_request)

# Replies will be sent to your webhook with the same messageId

Frequently Asked Questions

Q: Do I need a provisioned number to send messages? A: Yes, you must provision a dedicated number before sending SMS/MMS messages.

Q: How long does my number stay active? A: Numbers are active for 30 days by default. Use the activeDays parameter when provisioning to extend this.

Q: Can I send to international numbers? A: Yes, except to sanctioned countries: Burma, Côte d'Ivoire, Cuba, Iran, North Korea, Syria.

Q: What's the difference between Small and Large MMS? A: Small MMS are under 600kB, Large MMS are over 600kB. They're charged differently.

Q: How do I handle message delivery failures? A: Implement webhook handlers for delivery status updates, or poll the status API for messages without webhooks.

Q: Can I use alphanumeric sender IDs? A: Yes, but only on Telstra Account paid plans (not credit card plans).

Q: What's the maximum message length? A: SMS: 1900 characters (single recipient) or 500 characters (multiple recipients). Messages over 160 chars are automatically split.

For more detailed information, see the Developer Guide.

Resources

• 📖 Developer Guide - Comprehensive integration guide
• 🔄 Message Flows - Visual sequence diagrams
• 💻 Code Examples - Practical webhook and messaging examples
• 🧪 API Testing with Postman

API Reference

All URIs are relative to https://tapi.telstra.com/v2

Class	Method	HTTP request	Description
Telstra_Messaging::AuthenticationApi	auth_token	POST /oauth/token	Generate OAuth2 token
Telstra_Messaging::MessagingApi	send_sms	POST /messages/sms	Send SMS
Telstra_Messaging::MessagingApi	send_mms	POST /messages/mms	Send MMS
Telstra_Messaging::MessagingApi	get_sms_status	GET /messages/sms/{messageId}/status	Get SMS Status
Telstra_Messaging::MessagingApi	get_mms_status	GET /messages/mms/{messageid}/status	Get MMS Status
Telstra_Messaging::MessagingApi	retrieve_sms_responses	GET /messages/sms	Retrieve SMS Responses
Telstra_Messaging::MessagingApi	retrieve_mms_responses	GET /messages/mms	Retrieve MMS Responses
Telstra_Messaging::ProvisioningApi	create_subscription	POST /messages/provisioning/subscriptions	Create Subscription
Telstra_Messaging::ProvisioningApi	get_subscription	GET /messages/provisioning/subscriptions	Get Subscription
Telstra_Messaging::ProvisioningApi	delete_subscription	DELETE /messages/provisioning/subscriptions	Delete Subscription

Models

• Telstra_Messaging::SendSMSRequest
• Telstra_Messaging::SendMmsRequest
• Telstra_Messaging::MMSContent
• Telstra_Messaging::MessageSentResponse
• Telstra_Messaging::InboundPollResponse
• Telstra_Messaging::OutboundPollResponse
• Telstra_Messaging::ProvisionNumberRequest
• Telstra_Messaging::ProvisionNumberResponse
• Complete Model List

Authentication

This SDK uses OAuth2 with client credentials flow:

• Type: OAuth
• Flow: application
• Scopes: NSMS