Twilio integration

What it does

The Twilio integration lets your agency run a client's messaging and voice program from inside a workflow. Connect a client's Twilio account once and your workflows can send SMS, MMS, and WhatsApp messages, place outbound calls, look up phone-number details, run Verify one-time-passcode flows, post messages into Twilio Conversations, and read message and call history. Two triggers start a workflow the moment an SMS or a voice call arrives on a Twilio phone number.

Twilio connects with an Account SID and Auth Token, not an OAuth sign-in. Every trigger and action is currently in beta.

Connect a Twilio account

Twilio uses API-key credentials, so you paste two values rather than authorizing through a redirect.

1. Open Connections

   Open your workspace in TaskJuice and go to Connections.
2. Start the Twilio connection

   Choose Twilio and click Connect.
3. Sign in to the Twilio Console

   In a new tab, sign in to the Twilio Console at console.twilio.com as the client, or as your agency if the client has delegated credentials to you.

4. Copy your Account SID and Auth Token

   Under Account Info, copy the Account SID (it starts with AC) and the Auth Token.

5. Save the connection

   Paste both values into TaskJuice and save the connection. The Auth Token is stored encrypted and is never shown again in the browser.

The connection form has exactly two fields.

The Auth Token is the master credential for the entire Twilio account. Treat it like a password: store it only in TaskJuice and rotate it from the Twilio Console if it is ever exposed.

Triggers

Both triggers are webhook-based and single-event: one inbound POST from Twilio starts one workflow activation. Both require a connection and verify the request signature before activating. Both are in beta.

Incoming SMS payload

Incoming Call payload

Point your Twilio number at TaskJuice

Each trigger publishes a TaskJuice webhook URL. Set your Twilio phone number's Messaging or Voice webhook to that URL, either manually in the Twilio Console under the number's Messaging or Voice configuration, or programmatically with the Configure Phone Number Webhooks action.

Twilio signs each request by computing an HMAC-SHA1 over the request URL plus the alphabetically sorted POST parameters and sending the base64 digest in the X-Twilio-Signature header. TaskJuice verifies that signature with your Auth Token before activating the workflow. No extra shared-secret header is required.

Actions

The integration ships 14 actions, all in beta, all requiring a connection. Where a field reads "From Phone Number (dropdown)," TaskJuice loads your account's incoming Twilio numbers into a picker so you select instead of pasting an SID. Verify Service dropdowns work the same way for your Twilio Verify services. Both pickers load up to 200 entries.

Messaging

twilio/send-sms sends an SMS to a phone number.

Output: sid, status, to, from, body, date_created, price, error_code (string or null).

twilio/send-mms sends a multimedia message with an image or media attachment.

Output: sid, status, to, from, num_media, date_created.

twilio/send-whatsapp sends a WhatsApp message via Twilio. The From here is free text, not a dropdown.

Output: sid, status, to, from, body.

twilio/get-message retrieves details of a specific SMS or MMS message.

Output: sid, status, to, from, body, date_created, date_sent, price, error_code (string or null), error_message (string or null).

twilio/list-messages lists SMS and MMS messages with optional filters.

Output: messages[] (each with sid, status, to, from, body, date_sent) plus next_page_uri (string or null).

twilio/send-conversation-message sends a message in a Twilio Conversation.

Output: sid, conversation_sid, body, author, date_created.

Voice

twilio/make-call initiates an outbound phone call. Supply either inline TwiML or a TwiML URL, not both.

Output: sid, status, to, from, direction, date_created.

twilio/get-call retrieves details of a specific phone call.

Output: sid, status, to, from, direction, duration, start_time, end_time, price.

twilio/list-recordings lists call recordings with optional filters.

Output: recordings[] (each with sid, call_sid, duration, date_created, status) plus next_page_uri (string or null).

Phone numbers

twilio/list-phone-numbers lists incoming phone numbers on the account.

Output: incoming_phone_numbers[] (each with sid, phone_number, friendly_name, sms_url, voice_url, capabilities).

twilio/lookup-phone-number looks up information about a phone number using the Twilio Lookup v2 API.

Output: phone_number, country_code, national_format, valid (boolean), calling_country_code, caller_name (object or null), line_type_intelligence (object or null).

twilio/configure-phone-number-webhooks updates webhook URLs for an incoming phone number.

Output: sid, phone_number, friendly_name, sms_url, voice_url, status_callback.

Verify

twilio/start-verification sends a verification code through Twilio Verify.

Output: sid, status, to, channel, valid (boolean), date_created.

twilio/check-verification checks a verification code submitted by the user.

Output: sid, status, to, channel, valid (boolean), date_created.

Errors

When a Twilio call fails, TaskJuice maps the provider's HTTP status to a stable error code so your workflow can branch on it. Any response that does not map to a specific code surfaces as the generic UPSTREAM_REQUEST_FAILED.

Known limitations

• Twilio connects with API-key credentials, not OAuth. There is no Connect-and-authorize redirect; you paste your Account SID and Auth Token. Every REST call authenticates with HTTP Basic, using the Account SID as the username and the Auth Token as the password.
• Inbound verification relies on the Twilio request signature. Incoming SMS and Incoming Call triggers verify the X-Twilio-Signature header before activating, using your Auth Token. Because the Auth Token is also the signing key, rotating it in the Twilio Console means you must update the TaskJuice connection promptly, or inbound webhooks will fail verification.
• Every Twilio trigger and action is in beta.
• Send SMS accepts up to 1600 characters in Body. Split longer content across multiple sends.
• Phone numbers for SMS, MMS, and voice must be in E.164 format, for example +15551234567. WhatsApp uses the whatsapp:+... prefixed form for both To and From.
• Send WhatsApp Message does not use the phone-number dropdown. You type the whatsapp:+... sender yourself, and it must be a WhatsApp-enabled Twilio sender.
• List Messages and List Recordings return one page per call. Each pages at up to 1000 results (default 50) and returns a next_page_uri for the following page.
• There is no bulk-send action. To message many recipients, drive Send SMS from a Loop node over your recipient list.
• The geo fields on both triggers (FromCity, FromState, FromCountry, and their To equivalents) appear only when Twilio has location data for the number. Treat them as optional.

Related

• Connect an account
• Control flow nodes
• All integrations