Skip to main content


How to make phone calls and send SMS with Ruby

Samantha Capps Samantha Capps
Samantha Capps

Bandwidth has a full suite of messaging API solutions to power your business’ needs. Whether you want to send messages from toll-free numbers, local numbers, or short codes, Bandwidth’s APIs make it easy to enable in your software or platform, while Bandwidth’s relationships with the carriers give you reliable message delivery and insights. 


In this article, you will see a quick overview of what sending your first message and creating your first call looks like when using Bandwidth’s Voice and Messaging APIs along with Bandwidth’s Ruby SDK. First you will see some code examples and then at the end of this article is an explanation of the variables you would need to insert into the code to make the SDK work with your Bandwidth account.

Additional resources:

Packages and Client Initialization

First you need to install the gems needed for this example like this.

gem install bandwidth-sdk
gem install sinatra

You then need to initialize the configuration for the SDK client.

require 'bandwidth'

include Bandwidth

bandwidth_client =
    messaging_basic_auth_user_name: '{username}',
    messaging_basic_auth_password: '{password}',
    voice_basic_auth_user_name: '{username}',
    voice_basic_auth_password: '{password}'

$voice_client = bandwidth_client.voice_client.client
$messaging_client = bandwidth_client.messaging_client.client

How to send a text message with Ruby

Sending a SMS with Ruby from a Bandwidth number looks like this. This must be in the same file as your initiated client or the client must be imported here.

require 'bandwidth'

include Bandwidth::Messaging

messageBody =
messageBody.application_id = '{app_id}' = ['{to}']
messageBody.from = '{from}'
messageBody.text = 'Hello, I am sending a message! How fun!'

$messaging_client.create_message('{account_id}', body: messageBody)

You will need to set up a server that can receive a callback/webhooks with a JSON body that will tell you if the message was successfully delivered or not. Some simple Ruby server code using sinatra that can process Bandwidth messaging callbacks could look like this.

require 'sinatra'

post '/messaging' do
    data = JSON.parse(
    if (data[0]['type'] == 'message-delivered')
        //successful delivery action
        halt 200
    if (data[0]['type'] == 'message-failed')
        failureReason = data["description"]
        //failed delivery action
        halt 200
    halt 200

How to make a phone call with Ruby

Making a phone call with Ruby from a Bandwidth number looks like this. This must be in the same file as your initiated client or the client must be imported here.

require 'bandwidth'

include Bandwidth::Voice

voiceBody =
voiceBody.from = '{from}' = '{to}'
voiceBody.answer_url = '{url}'
voiceBody.application_id = '{app_id}'

$voice_client.create_call('{account_id}', :body => voiceBody)

When the call is answered by whoever you sent the call to, Bandwidth will send a callback/webhook with a JSON body to the URL you specified when you created the call. You can send BXML verbs back to Bandwidth in response to the callback/webhook in order to create new actions on the call. Some simple server code that would make the call play some text-to-speech audio and then hang up could look like this:

require 'bandwidth'
require 'sinatra'

include Bandwidth::Voice

post '/voice' do
    data = JSON.parse(
    if (data['eventType'] == 'answer')
        response =
        speak_sentence ={
            :sentence => 'I am saying something and now will hang up.',
            :voice => 'julie'

        response =
        hangup =

    halt 200

And that’s it! That’s how simple it is to create your first message and call with a Bandwidth phone number, Bandwidth’s API, and Bandwidth’s Ruby SDK.

Variable Reference

Here is an explanation of the variables used in the above code that will be unique to your account and use case.

Variable NameExplanation
usernameyour username for the Bandwidth Dashboard
passwordyour password for the Bandwidth Dashboard
app_idthe ID of your messaging or voice application; applications are set within the Bandwidth Dashboard and are used associate your Bandwidth phone numbers with URLs for callback/webhooks
from_numberwhen creating outgoing messages or calls, the number you are sending to; this can be your cell phone number for testing or the number of one of your customers
to_numberwhen creating outgoing messages or calls, this is a number you have been assigned by Bandwidth that lives on your Bandwidth Dashboard account
account_idyour Bandwidth Dashboard account ID
urla URL you own that to which Bandwidth will send callbacks/webhooks related to call and messaging events; note that for messaging, this URL is not set at the time of message creation and is instead defined by the Bandwidth Dashboard application used to send the message

Developing with Bandwidth – Ruby

Looking for additional information on developing with Ruby? The webinar below goes into greater detail on the topics presented in this post.

Learn more

Want to learn more about creating your first call or message using Bandwidth's APIs and PHP? Sign up for a trial account or check out our developer resources.

Bandwidth Developer Resources