ISVs: Set up for Success

ISVs: Set up for Success

Twilio partners with a wide variety of software solutions to provide the communications infrastructure they need to scale. At Twilio, we refer to these software solutions as Independent Software Vendors (ISV).

This post provides some best practices that ISVs should follow when building on the Twilio platform.

That said, this post is beneficial for any customer looking to set up their application for success.

Below are the main items we will work through:

• Pricing and Packaging Strategies.
• Technical Considerations.

Technical Requirements

This blog is mainly informational, however there are some example code snippets. So in order to perform the operations you will need the following:

• A free Twilio Account - Sign up for one here through this link to get an extra $10 in credit when you upgrade.
• Familiarity with sending REST API requests. Here are helpful tips on running a cURL from bash or zsh or you can use a tool like Postman.

What is an ISV?

ISVs, or independent software vendors, are customers that embed Twilio APIs into their software solutions to power digital communications. ISV partners resell this software to businesses around the globe. If you answer "yes" to the following statements, Twilio would most likely consider you an ISV.

• You provide full featured solutions to other businesses and want to offer omni-channel solutions via Twilio.
• You are generally a B2B and your customers are B2C.

For the remainder of the article, we will use a fictional customer - Owl Inc. - to help illustrate some of these concepts.

Owl Inc. offers a contact management system. They want to embed Twilio’s API into their application to offer a wide range of capabilities for their customers.  

Below is a high level overview of their structure:

Pricing and Packaging Strategy

One important decision for ISVs is how to create a sustainable business model with Twilio's APIs.

Twilio charges ISV partners based on usage. Usage based pricing is great as it's transparent, flexible and allows customers, such as Owl Inc., to create packages for their customers to buy.

For example, let's say that Owl Inc. wants to first launch with the ability to offer their customers the ability to send and receive SMS messages.

Below are a few different ways Owl Inc. can package the Twilio Usage based pricing into their model.

These common strategies have trade-offs. To talk more about these trade-offs and learn which strategy is right for your business, reach out to the Twilio Account team to schedule a meeting.

Twilio Account Structure

It's critical that ISVs set up their Twilio account structure properly, as not doing so creates challenges around account management, supportability and isolation of resources. Although there are different strategies when setting up your account with Twilio, the diagram below represents the most common practice we recommend to our ISVs:

The high level benefits to using subaccounts include:

• Logical containers for customers.
• Segmentation of usage.

To get started with subaccounts checkout this blog post and our documentation on subaccount APIs.

For the remainder of this post we will assume that an ISV is going to use subaccounts and make recommendations based on that assumption.

We’ve grouped quite a few topics into logical buckets that we hope makes for easier categorization. The following buckets include:

• Operational.
• Performance.
• Cost.
• Security.

Operational Considerations

Users and RBAC

Twilio provides Role Based Access Control (RBAC) features to limit each user’s access and capabilities within Twilio’s console. Customers can use this feature to secure their Twilio investments by limiting Console access for their projects.

Each Twilio project has only one owner, defaulting to the email account originally used to set up the account. The owner has full permissions for your project, but additional users may be added to the project with varying levels of permissions. Each new user needs to be assigned one of the following roles:

• Administrator: Full access to invite and revoke access for new users, see billing history and make changes, and change project settings.
• Developer: Access to only the required project details for developing with Twilio - API credentials, phone numbers, development tools, logs, and usage.
• Billing Manager: Access to only the required project details for handling billing requests - logs, usage, and billing history and settings.
• Support: Access to only logs and usage.

Below is a full list of the permissions by role type:

API Keys

Rather than using your Twilio Account SID and authentication token combination to make an authenticated request, ISVs can programmatically generate, manage and use API keys.

Here is a great blog on API key rotation. 

Key Takeaways for ISVs:

• Once users are created and added to a project, they have access to the parent account and all subaccounts within the Twilio console. Although the specific functionality they can access is governed by the assigned role but still across accounts and subaccounts.
• It is not recommended to create user accounts for your customers on the Twilio console because doing so will allow one of your customers' to access data / usage across your entire Twilio account, thus exposing one customer's data to others.
• ISVs typically provide usage data to their customers by creating dashboards in their existing systems (e.g. CRM / POS) by extracting or consuming the relevant data for their customers' usage via Twilio API.

Service Level Agreements

If we think about our customer Owl Inc. they need to work with their customers to agree on SLAs (Service Level Agreements) and internally define SLOs (Service Level Objectives) and SLIs (Service Level Indicators) for their services. Twilio understands how important SLAs can be. Thus, we have components to help support this business critical agreement.

First is our Twilio status page. Twilio will post incidents to this page and ISVs should use the Twilio Status API to subscribe and get notifications.

Second is supportability. Twilio has an excellent team of Technical Support folks to help with troubleshooting and resolving issues. For ISVs who are running mission critical workloads and applications, we recommend leveraging a support plan that has a guaranteed response time and 24/7 access to our team.

Alert Triggers

As Owl Inc. begins to develop its product(s), warnings and errors will occur, as this is part of the development process. When Owl Inc. pushes their services that depend on Twilio to production they need a way to monitor errors at scale. We recommend using the Debugger API for situations like this.

Below is a webhook for all errors and warnings to be sent. This endpoint might be an JSON storage service or a monitoring service:

Performance Considerations

API Throughput

Twilio is a multi-tenant platform that allows hundreds and thousands of companies to provide digital engagement experiences. In order to provide equitable resources across all of its customers, Twilio enforces rate limits on the number of API requests per seconds a specific customer can send on its platform. This API request throughput is configurable based on your specific needs and use cases.

As a best practice, all of Twilio customers including ISVs should implement retries with exponential backoff if your application receives a 429 response code when you exceed the specific API rate limits configured for your Twilio account. Check out this support page for more details on how to handle 429 errors.

ISVs have to consider that the API rate limits are usually specified at a Twilio account level - i.e., account / subaccount. As a best practice, ISVs need to implement logic to monitor their API throughput (to Twilio) to graciously handle any retries if they receive a 429 response code (Too Many Requests) from Twilio (not common).

Cost Considerations

In this section we will talk about strategies to control costs and cover how best to measure costs.

Usage API

Owl Inc. will need a method to aggregate its usage in order to understand the costs incurred on Twilio to ensure they can correctly bill the customers. This will also help ensure that they are running a sustainable business.

Assume the Owl Inc. wants to bill its customers on the start of the month. So if a customer signs up March 15th, their first bill will be issued April 1st for March 1st-March 30th.

In order to use the Twilio usage API, Owl Inc. can specify these dates and retrieve all the usage for their customers.

Below is the request to retrieve data from March 1st - March 31st.

Here are a few things to note in the response from Twilio:

This response will contain all usage across every product, so we’re just showing a few of the objects rather than the entire payload.

Each category (i.e. calleridlookups, calls, etc..) will contain their subresource_uris, in the event that you want to drill down specifically into that category.

Most data is based on UTC timezone.

If you are comparing call logs vs. the usage you might see some potential discrepancies. We’ve outlined how to reason through the differences between call logs and usage discrepancies in this article.

Usage Triggers

Now that we have a way to measure an accounts' usage, we want to control the usage of an account. Some customers allot a certain amount of credits or usage for their customers. A way to programmatically control this is via Usage Triggers.

For example; lets say that Owl Inc. offers its customers the ability to send 1,000 SMS messages in a given month. We can create a usage trigger that will send our application a webhook when this limit is reached.

Security Considerations

Data Controls

Often ISV would like to take control of their data and want to make sure this data is only stored for necessary duration.

Twilio stores call and messaging logs on Twilio until they are deleted by an ISV. These logs are available for viewing in console for 13 months.

Twilio offers a number of ways to manage these log data.

1. HTTP Delete for messaging Logs and Call logs.
2. Data retention Controls for messaging logs.

Conclusion: Setup for ISVs is critical

We discussed a lot of concepts at a high level in this post. If you have additional questions or want to talk through trade-offs, we recommend reaching out to our teams that work with ISVs. We’ll be able to offer guidance on which strategies and considerations are most important for your team. Also, check out our other posts, where we lay out messaging and voice archiectural best practices.

We hope to produce more ISV specific blogs, so if you have any ideas for us don’t hesitate to reach out!

Josh Siverson is a Principal Solutions Engineer at Twilio, focusing on helping our Independent Software Vendor (ISV) Partners build scalable architectures and business on Twilio. You can reach him at jsiverson [at] twilio.com.

Sunil Kalva is a Partner Solutions Architect at Twilio and helps Vertical ISV partners integrate Twilio technology stack to provide compelling digital engagement solutions across industries. Reach him at skalva [at] twilio.com.

Pathik Soni is a Principal Solutions Engineer who helps Enterprise ISV partners reimagine customer experience using Twilio.