Twilio
Send SMS and WhatsApp messages and place calls through your Twilio account.
Connect it with: User name and password. Twilio's own documentation: https://www.twilio.com/docs/usage/requests-to-twilio.
What agents can do
Connect Twilio so the agents working your tasks can reach it. With it connected, they can:
- Send an SMS, for example an on-call alert or a one-time notice to a customer.
- Send a WhatsApp message from a Twilio-approved sender.
- Look up message delivery status and recent message logs.
- List the phone numbers on the account.
Before you start
- A Twilio account. A trial account can send only to the phone numbers you verified under Phone Numbers > Manage > Verified Caller IDs.
- A Twilio phone number or messaging service to send from (Phone Numbers > Manage > Buy a number).
- A Jaah account. Anyone can add a personal secret; an organization secret needs an Org Owner or Admin.
Connect with Twilio
Jaah connects to Twilio with a user name and password, not with a sign-in button.
Connect with an API key
Find each value first:
- Account SID: Twilio Console (console.twilio.com) home page > Account Info panel > Account SID. It starts with AC.
- Auth token: Twilio Console home page > Account Info panel > Auth Token: select Show or the copy icon. A new token is issued under Account > API keys & tokens > Auth tokens.
Then add it to Jaah:
- In Jaah, open Secrets, select New, and pick the Twilio card.
- Name the secret and choose who can use it.
- Fill in Account SID, Auth token.
- Select Save. Jaah tests the secret straight away (see Test the connection).
Jaah encrypts what you type and never shows it again — not to you, and not to an admin.
Use your own OAuth app
Not used: Jaah connects to Twilio with a user name and password, not through an OAuth app.
Test the connection
Select Test on the secret. Jaah calls Twilio's API once (GET https://api.twilio.com/2010-04-01/Accounts.json) with the stored values, and shows whether Twilio accepted it, or which value Twilio refused and the status it answered. Jaah also tests automatically when you save or reconnect.
The last result and its time stay on the secret's page, so you can see whether it still works without testing again.
Who can use it
Every secret has an owner, and the owner decides who can use it:
- Personal — only your own tasks can use it. This is the default.
- Organization — every task in the organization can use it. Only Org Owners and Admins can choose this.
- Attached to a project — every task on that project can use it, whoever started the task. See Attach a secret to a project.
More on owners and access: How secrets work.
Use it in an agent session
An agent asks for the secret with its credential_get tool, by the secret's path, when it needs it, and gets the values for that one call. The path is the owner's prefix and the secret's name:
org/<name>for an organization secret,projects/<project>/<name>for one attached to a project,me/<name>for your personal one.
A key connection hands the agent its fields: account_sid, auth_token.
Tell the agent in your task description which secret to use, for example “use the Twilio secret org/twilio”.
Manage, rotate or disconnect
Everything is on the secret's page under Secrets:
- Rotate a key: create a new key at the vendor first, then select Replace on the secret and paste it. Revoke the old key at Twilio once the test passes. Steps: Replace or delete a secret.
- Disconnect: select Delete. The stored values are destroyed and agents lose access on their next call. To end access at Twilio's side too, change the password at Twilio or remove the user.
Limitations
- Jaah stores the account's Auth Token, which has full access to the account. Rotate it if a task description or log ever leaks it.
- Messages cost money per segment at Twilio's rates; Jaah does not cap what agents send.
- Sending to some countries needs a registered sender (for example A2P 10DLC in the US) before Twilio delivers the message.
- Agents can do only what the connected Twilio account allows.
Troubleshooting
Test says Twilio rejected the auth token (401)
Check that the Account SID and Auth Token come from the same account, and that the token was not rotated. Copy both again from the Account Info panel and select Replace on the secret.
Sending fails with error 21608 on a trial account
Trial accounts send only to verified numbers. Verify the recipient under Phone Numbers > Manage > Verified Caller IDs, or upgrade the account.
Messages are accepted but never arrive in the US
Register the sending number for A2P 10DLC under Messaging > Regulatory Compliance, as Twilio requires for application-to-person SMS.
Still stuck? Select Test and read the result: it names the value Twilio refused and the status it answered.
FAQ
Can I use an API key instead of the Auth Token?
Yes, for sending: put the API key's SID in Account SID and its secret in Auth token. A Standard key cannot read the account itself, so Test may report it rejected; a Main key passes.
Does a subaccount work?
Yes. Use the subaccount's own Account SID and Auth Token, so agents can reach only that subaccount.
Can Jaah or an admin see the key or token?
No. Jaah stores it encrypted and never shows it again. Only the tasks allowed to use the secret receive it, at the moment they ask for it.
Can I connect more than one Twilio account?
Yes. Add one secret per account, each with its own name, and tell the agent which one to use.