Twilio Connect Ruby Quickstart

Overview

Twilio Connect allows developers to obtain authorization to make calls, send text messages, purchase phone numbers, read access logs and perform other API functions on behalf of another Twilio account holder.

As an example, imagine you want to access the Twilio account of a user of your web application to provide in-depth analytics of their Twilio account activity. This quickstart solves this problem by creating your first Twilio Connect App and placing the "Connect" button on your website so users can authorize your app to access their Twilio account data and make API requests against their account.

Create your first Twilio Connect app

To create your first Connect App, log in to the Twilio Console and go to Settings > Connect applications. Click Create a new connect app and fill in the top section with the name of your application and your company information.

Next, assign an Authorize URL to your Connect application. The Authorize URL is the URL that Twilio will redirect the user's browser to after they have authorized your application to access their Twilio account. Later on in the quickstart we'll demonstrate how the Authorize URL is used.

Lastly, select the access rights your Connect app requires on the user's account. For this example we will access call logs for analytics, so we'll choose "Read all account data".

Here's what our sample Connect application looks like:

Rossum app settings with endpoints and permissions, including a possum .

Click Save and you're done!

Place the Connect button on your website

The Connect button is where your customers will start the process of authorizing your Connect App to access their Twilio account.

To get the Connect button code, click Generate connect button HTML on your Connect App details page. Copy the generated code and paste it into the HTML of your website where you would like the button to appear.

Test the Authorization workflow

With the Twilio Connect button now on your website, browse to the page where you placed the HTML and click the Connect button. Verify that the information displayed on the authorization screen is correct.

After completing the app authorization process, you are redirected to the Authorize URL you specified when creating your Connect App. Appended to that URL is an Account Sid URL parameter with a value that looks like this:

1http://www.example.com/twilio/authorize?AccountSid=AC12345
2   Your Connect App's Authorize URL       Customer's SID
3

Your application should extract the AccountSid value from the URL and associate it with the user's account within your application. After extracting the AccountSid, we recommend that you redirect the user to another page within your app so the AccountSid isn't hanging around. The following Ruby example extracts the AccountSid and redirects the user.

(warning)

Warning

This tutorial assumes you have a Ruby development environment with Sinatra and the twilio-ruby SDK. If you don't have these yet, please see our post on setting up your Ruby environment.

Extract the AccountSid in a Sinatra route

1require 'rubygems'
2require 'sinatra'
3require 'twilio-ruby'
4
5get '/connect' do
6  sid = params['AccountSid']
7  # Store this account sid in your database, so you can retrieve it
8  # later. You will need to write this section of the code.
9
10  # Finally, redirect the user to your app after you've gathered their Sid
11  redirect 'http://example.com/myapp'
12
13end

Make an authorized request

With the user's Account Sid in hand you can now request data from their account via the Twilio REST API. A request to retrieve data from a user's account is nearly identical to a request made against your own account, with one key difference. Instead of authenticating with your own AccountSid, you authenticate with the Account Sid retrieved during the authorization process and your account's Auth Token.

Here is a request to retrieve call logs from an account using the Ruby SDK. Pay special attention to line 4 where the customer's Account Sid is specified instead of your own:

Retrieve call logs using the customer's Account SID

1require 'rubygems' # not necessary with ruby 1.9 but included for completeness
2require 'twilio-ruby'
3
4# Use your customer's account sid.
5account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
6
7# Use your own auth token.
8auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
9
10# set up a client to talk to the Twilio REST API
11client = Twilio::REST::Client.new(account_sid, auth_token)
12
13calls = client.calls.list
14
15begin
16  calls.each do |call|
17    puts call.sid + "\t" + call.from + "\t" + call.to
18  end
19  calls = calls.next_page
20end while not calls.empty?

Next steps

Retrieving call logs on behalf of your customers is just the start of what you can accomplish with Twilio Connect. Visit the complete Connect documentation and best practices to learn more about how to integrate Connect's additional capabilities into your applications.