Get Started

Twilio Connect

Overview

Twilio Connect lets your users authorize access to their Twilio accounts so your application can buy phone numbers, make phone calls, send SMS, and access log data. Because your customers are using their own Twilio account, you don't need to worry about charging for usage. Twilio will charge your customer directly for their Twilio usage.

Additionally, users can grant your Connect App access to their Twilio call and SMS log data. With this information, your application can implement analytics and other read-only use-cases.

Want to get started right away? Jump right in with our Twilio Connect Quickstart!

Manage Your Connect Apps

Create Connect Apps through the Apps page in the account portal. You may update your Connect Apps through the Apps page, or by using the new Connect REST API.

Helper Libraries

You can use the existing Twilio helper libraries to easily make authorized requests to your users' Twilio accounts. Just drop in the AccountSid provided by authorization.

Best Practices

Twilio Connect is a new way of thinking about your applications. We suggest some Best Practices that you should follow to make sure your Connect App is both secure and error-free.

How It Works

When creating your Connect Apps, there are two different permissions you can request from users:

"Read all account data" allows your application to access call, SMS and other logs for analytics and other read-only use-cases.

"Charge account for usage" allows your application to buy phone numbers, make phone calls, send text messages and perform other tasks that result in Twilio billing the user directly.

After you create your Connect App, you will be given a snippet of HTML to drop into your page. This HTML will display a "Connect Button" that enables users to authorize your Connect App to use their Twilio account. If your user doesn't yet have a Twilio account, Twilio will prompt them to sign up.

These permissions are not mutually exclusive. You can request both "Charge account for usage" and "Read all account data." If you change your Connect App permissions you will not be able to use any new permission until the user reauthorizes your Connect App.

After the user authorizes your Connect App, Twilio will redirect the user's browser to your AuthorizeRedirectUrl with an AccountSid as a GET query string parameter. That AccountSid provides you access to the user's account. Now, you can authenticate with that AccountSid and your AuthToken. If you add a query string parameter called "state" to the target url of the connect button Twilio will pass that parameter back to your AuthorizedRedirectUrl. This is useful for passing metadata, like a customer username or unique identifier, to your authorize url.

If you have "Charge account for usage" permission ("post-all" in the API), you can POST to that account's subresource URLs to buy numbers, make phone calls, and send SMS messages. If you have "Read all account data" access ("get-all" in the API), you can GET the /Accounts resource to see all the user's accounts, and you can GET from any subresource owned by any of those accounts.

Best Practices

Do
  1. Do place your Connect button behind some form of authentication

    Twilio Connect allows end users to authorize your application to make requests on their behalf, it does not serve as an authentication mechanism for your end users. As such, your application should provide its own mechanism for authentication. For more information please read the authentication section.

    When presenting users with your Connect button, you should inform them that Twilio will bill them directly for your Connect App's voice and SMS usage.

  2. Do redirect to another page after your Authorize URL

    The AuthorizeURL should only be used by your Connect App. We will pass your user's AccountSid to the AuthorizeURL. After you store the AccountSid associated with your user, you should redirect to another page.

  3. Do have a Deauthorize URL

    When a user revokes permission to your Connect App, Twilio will make an HTTP request to the DeauthorizeCallbackURL. You should update your user database to reflect this.

Do Not
  1. Do not make a user's AccountSid readily available to others

    Although all requests made to the Twilio API must be authenticated with your AuthToken, you should treat the AccountSid as you would other user data.

  2. Do not change your Connect App permissions haphazardly

    As described above, if you change the permissions that your Connect App requires, you will not be able to use them until your user reauthorizes. Changing your Connect App permissions frequently may lead to situations where you're not sure what permissions you have for a particular account. We recommend you change permissions only when a new feature requires it.

Permissions

There are two permissions available for Twilio Connect Apps:

Read all account data

This allows your Connect App to see all the user's data, including calls, SMSs, recordings and transcriptions. Your Connect App will also have access to Twilio data generated by other Connect Apps, any subaccount, and the parent account. A Connect App with this permission alone will only have access to perform HTTP GETs on the user's accounts.

Charge account for usage

This allows your Connect App to perform actions that charge your user's Twilio account such as make and receive phone calls, send and receive SMS messages, and buy phone numbers. Your Connect App will not have access to resources in the user's parent account, like phone numbers. Instead, your Connect App must buy phone numbers on behalf of the user, using the AccountSid passed to your AuthorizeURL.

The AccountSid that Twilio returns to your Authorize URL is a subaccount just for your application within the user's account. This allows your Connect App to buy numbers and make calls without other Connect Apps modifying your data.

Connect App Configuration Options

Connect Apps have a variety of configuration options that Twilio uses in different parts of the authorization flow and the account portal.

Option Description
Friendly Name Name of your Connect App. Displayed on the authorization screen and the user's list of authorized apps. Required.
Application Logo Logo or picture associated with your Connect App. Displayed on the authorization screen, and in the user's list of authorized apps.
Company Name Name of the Connect App developer's company. Displayed on the authorization screen and the user's list of authorized apps. Required
Description Brief description of what your Connect App does. Displayed on the authorization screen.
Homepage URL The homepage of your Connect App, displayed in the user's list of authorized apps.
Terms of Service URL The URL where users can read your Connect App's Terms of Service. Displayed in the user's list of authorized apps.
Authorize URL The URL where the user will be redirected after they go through the authorization flow. If the user approves access for your Connect App they will be redirected to this URL with their AccountSid as an HTTP GET query string parameter named AccountSid.

If a user chooses to decline authorization they will be redirected to this URL with a single parameter: error=unauthorized_client
Deauthorize URL The URL that Twilio makes a request to when a user revokes access to your Connect App. This is a server to server request; your users will never be directed to this location.

Two parameters will be sent as part of this request:

  • AccountSid is the AccountSid of the user that has deauthorized your Connect App.

  • ConnectAppSid is the ConnectAppSid of the Connect App that has been deauthorized.
  • Deauthorize URL HTTP Method The HTTP method used when making a request to your Deauthorize URL. You can select either GET or POST.
    Access Required This defines the types of API access your Connect App will require. Read the permissions section for more details.