Skip to content
CostReveal
Menu

Connecting Twilio to CostReveal, setup guide

The CostReveal team, , 6 minute read

Messaging and voice spend scales with every verification code, notification and support call your product makes, and Twilio's invoice states it by category, not by the team or product behind it. This guide covers how CostReveal reads Twilio's usage records for your parent account and its subaccounts, how categories are kept so nothing is counted twice, which API key to create, how subaccounts become owners, and when a month is final.

What the Twilio connection reads

CostReveal reads Twilio's usage records for your parent account and its subaccounts: what each day's usage was priced at, category by category.

  • Each day's total, Twilio's totalprice, so nothing billed is left out, even costs that fall in no category.
  • The most specific categories, such as calls-inbound-local or sms-outbound-longcode, each as its own line. Twilio's categories roll up into broader ones, such as calls, so only the most specific are kept, and nothing is counted twice.
  • Other usage: what the specific categories leave of the day's total, as one line, so every day adds up to exactly what Twilio priced.
  • Subaccounts, each as an account of its own, when the key may list them.

The usage records describe categories and accounts. They do not name individual phone numbers or senders, so spend is explained by subaccount and category.

Why the key type matters

Twilio offers two kinds of API key, and the choice decides how much detail CostReveal can see:

  • A Main key can list your subaccounts, so each subaccount's usage arrives as its own account. This is the key to create.
  • A Standard key works too, but reads every subaccount's usage together, as the parent's, so the split by subaccount is lost.

What you need

  • Access to the parent account in the Twilio Console, to create a Main API key.
  • An owner or admin role in CostReveal.

Step by step setup

1. Start the connection

In CostReveal, go to Connections and choose Connect next to Twilio.

2. Create a Main API key

In the Twilio Console of the parent account, under Account, API keys, create a Main key for CostReveal.

3. Enter the details and verify

Enter the account SID, the key's SID and its secret, and choose Verify and connect. Only the format is checked as you type. When you verify, CostReveal reads today's usage with the key before saving anything.

The secret is stored encrypted and never shown again. Deleting the key in Twilio ends access at once.

Freshness and history

Twilio prices usage as it happens, so today's figures grow through the day. CostReveal reads every six hours. A month is invoiced once it has ended; the month in progress is not yet invoiced. The first read brings in the current month and the twelve before it, as far as Twilio holds them. Where Twilio holds no older months, Connections says how far back it reached, and each read asks again. After that, each read covers the current and previous month.

Connection states

Under Connections, the connection is always in one of four states:

  • Setup not finished: the key has not been verified yet.
  • Waiting for first data: the key was verified, and the first read is due.
  • Connected: usage was read and the latest read succeeded.
  • Needs attention: the latest read failed, for example because the key was deleted. Everything already read is kept.

How Twilio spend is explained

  • Direct: the service, the usage category, which Twilio states itself.
  • Inferred: the team, feature or customer, when an allocation rule names the owner of a subaccount. Usage records carry no tags, so rules on accounts are how Twilio spend is explained.
  • Allocated: a share of a cost an allocation rule divides, by fixed percentages, evenly, or in proportion to what each owner already explains.
  • Unknown: spend no rule explains. It is shown as unknown, never spread across teams.

Subaccounts as owners

Many teams already give each product or customer its own Twilio subaccount. With a Main key, each subaccount arrives as an account, and one rule on the account, such as "when the account is the notifications subaccount, the feature is notifications", explains all of it. Names never explain spend on their own; the rule does, and is shown with the figure.

Usage on the parent account itself, or shared usage, can be split with a rule, by fixed percentages or evenly.

How figures are checked

Every amount is recorded as Twilio prices it. Each day's specific categories, plus the other usage line, add up exactly to Twilio's totalprice for that day. A change to a day already read is recorded as a correction that keeps what was said before, and attribution runs again. Attribution on every dimension must then add up exactly to the ledger.

Twilio states usage records in this one source, so there is no second total to compare against. Home says the figures tie out with no second source named.

Getting more of Twilio spend explained

  1. Use a Main key, so each subaccount arrives as its own account.
  2. Give each product its own subaccount where you can, so one rule explains it.
  3. Write a rule per subaccount naming its team or feature.
  4. Watch categories in Explore, to see whether SMS, voice or verification moved.

Troubleshooting

  • All usage arrives under the parent. The key is a Standard key. Create a Main key, and enter it in the connection.
  • Verify cannot read usage. Check the account SID is the parent account's, and that the key's SID and secret belong to it.
  • The current month keeps changing. Twilio prices usage as it happens; a month is invoiced once it has ended.
  • A subaccount's spend is unknown. Add a rule on its account naming its owner.

Using Twilio figures in CostReveal

Once Twilio spend is read, it appears everywhere the rest of your spend does:

  • Explore groups it by provider, service, account, region, team, feature, customer or any custom dimension you define, and can filter to any of them. Every row shows how much of it is direct, inferred, allocated or unknown.
  • Budgets can be set on Twilio as a provider, or on any one of its services, with alerts when spend nears or passes the limit, or when the month is forecast past it.
  • Insights forecasts the month once it has three complete days, with a range and a confidence, and flags a day when a service spent outside its normal range: the median of the same weekday over the four weeks before.
  • Reports export the figures as CSV or a PDF, once or on a weekly or monthly schedule.
  • A worked example. Suppose each product sends from its own subaccount, and a rule names each subaccount's feature. A day when verification messages spike shows in Insights against that category's expected figure, and Explore by feature shows which product sent them.

Security and access

  • What CostReveal holds. The API key's secret. It is encrypted with AES-256-GCM before it is stored, under keys that can be rotated, and it is never shown again after you enter it.
  • What it is used for. Reading only. CostReveal never changes anything in your account.
  • Who can change the connection. Only owners and admins in CostReveal can connect, change or remove a connection, and each of those actions is recorded in the organization's audit log, with who did it and when.
  • Isolation. Every figure is stored in CostReveal's database with your organization isolated by PostgreSQL row level security, enforced in the database itself, below the application.
  • Ending access. Delete the key in Twilio. CostReveal keeps every figure already read and says that new data has stopped.

Removing the connection

Removing the connection under Connections deletes every figure it brought in from the project. Delete the key in Twilio too. To stop reading without removing anything, delete the key: CostReveal keeps every figure already read and tells you new data has stopped.

Frequently asked questions

Which API key should I create? A Main key in the parent account. A Standard key works, but reads every subaccount's usage together, as the parent's.

How are categories kept from counting twice? Only the most specific categories are kept, since broader ones roll them up. What they leave of each day's total is one line of other usage.

Can I see spend per phone number? No. Twilio's usage records are by category and account, so spend is explained by subaccount and category.

How do I assign a subaccount to a team? Write an allocation rule on the account naming its owner.

When is a month final? A month is invoiced once it has ended. The month in progress grows as Twilio prices usage.

Is Twilio spend checked against another total? Each day's lines add up exactly to Twilio's own daily total. There is no separate second source, and Home says so.

Keep reading

More setup guides