Skip to main content

Twilio

Twilio is the telephony provider that holds your phone numbers and carries calls to and from your agents. The Twilio page connects an environment to your Twilio account, so its Frontline agents can be given phone numbers from that account.

Agents work without Twilio. You can build, test and publish an agent, and use it from your own systems, with nothing connected here. Twilio is only needed when an agent needs a phone number, or when you set up human escalation.

Before You Start​

  • Role: the Organisation Admin role.
  • A Twilio account, with access to its Twilio Console.
  • The right environment selected. Each environment has its own Twilio connection. See Settings Are Per Environment.

You need two values from Twilio:

  • Account SID: the ID of your Twilio account. It starts with AC. See Twilio's account docs.
  • Auth token: the secret that goes with the account SID and proves requests really come from that account. See Twilio's auth token docs.

Both are on the home page of your Twilio Console.

Connecting Twilio​

  1. Open Settings. It opens on the Twilio page.
  2. In the Account section, enter the Account SID.
  3. Enter the Auth token.
  4. Select Save changes in the bar at the bottom of the page.

Each field name has a small link icon beside it that opens the matching page in the Twilio Console in a new tab, so you can copy the value from the right place.

Agentic checks both values with Twilio before saving. If Twilio accepts them, they are saved, the page header shows a Connected badge, and the Account section reads "Last verified with Twilio" with the time. If Twilio refuses them, nothing is saved and the bar explains which value was rejected.

Connecting From an Agent​

You do not have to visit Settings first. When you choose a phone number for an agent and Twilio is not connected yet, the picker says "Connect Twilio to see your numbers." Select Connect Twilio to open the same two fields in a dialog, then select Connect. See Phone Numbers and Deployment.

The Auth Token Is Write Only​

Once saved, the auth token is never shown again. Its row reads Saved, with a Replace button.

  1. Select Replace.
  2. Enter the new auth token.
  3. Select Save changes.

To keep the saved token instead, use the revert option on the row before saving.

Replace the token when you rotate it in Twilio

The auth token confirms that calls arriving from Twilio are genuinely yours. If you rotate the auth token in Twilio, replace it here straight away. Until you do, Twilio rejects the saved credentials and calls to your agents' numbers can fail.

Changing the Account​

You can correct the account SID at any time. If the new value belongs to a different Twilio account, the bar describes the change as Changing the account and warns that it clears the API key and resources on the Twilio Resources page, because they belong to the old account. Re-enter them for the new account afterwards. See Twilio Resources.

Connection Status​

The line under Account reports the last check with Twilio:

What you seeWhat it means
"Not verified with Twilio yet."Nothing has been saved.
"Last verified with Twilio at…"Twilio accepted the saved values at that time.
"Last checked with Twilio at…" or "Twilio could not verify this connection."Twilio refused the saved values the last time they were checked.
"Latest test: Twilio error" with a codeTwilio's own error code. Select the code to open Twilio's explanation of it.

When Twilio refuses saved values, the Twilio entry in the sidebar shows a marker, and the Getting started checklist in the sidebar shows Twilio Rejected Your Saved Credentials with a Fix Connection button. The usual cause is an auth token that was rotated in Twilio but not replaced here.

Save Errors​

MessageWhat to do
Can't be emptyFill in the account SID, and the auth token if none is saved.
Twilio rejected these credentialsCheck that the account SID and auth token belong to the same Twilio account, and copy them again from the Twilio Console.
Twilio could not check these credentialsTwilio did not answer. Wait a moment and select Retry.

Human Escalation Needs More​

The account SID and auth token are enough for phone numbers. Human escalation also needs a Twilio API key and some TaskRouter resources, which live on the Twilio Resources page.

When human escalation is on but no API key has been added, the Twilio page shows "Human escalation needs an API key. Add one in Twilio Resources so people can take calls." Select Open Twilio Resources to add one. See Twilio Resources.

What Happens Next​

  • Give a Frontline agent a phone number from the connected account. See Phone Numbers and Deployment.
  • If the account has no numbers yet, buy or port one in Twilio first. The phone number picker says "Every number in your Twilio account is already in use" when there is none free, with Buy a Number in Twilio and Check Again buttons.
  • To let people take over from agents, set up human escalation.