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, schedule messages through a Messaging Service, place, redirect and end calls, start Twilio Studio flows, look up phone-number details, run Verify one-time-passcode flows, post messages into Twilio Conversations, download call recordings and message media, read transcripts, and clean up message, call and recording history. Triggers start a workflow when a message or call arrives, when a delivery status or call status changes, when a recording or transcript is ready, when Twilio raises a debugger alert, and when a number is added to the account.

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

Every trigger is in beta and requires a connection. Webhook triggers verify Twilio's request signature before they activate; one inbound POST starts one workflow activation.

Point Twilio at TaskJuice

The webhook triggers share one TaskJuice webhook URL for your workspace's Twilio connection, shown in the trigger's panel. Paste it wherever Twilio asks for a callback URL; TaskJuice works out which trigger a request belongs to from the fields Twilio sends, so the same URL can sit in every slot:

The Configure Phone Number Webhooks action sets a number's messaging, voice and status URLs for you.

Twilio signs each request with an HMAC-SHA1 over the request URL plus the alphabetically sorted POST parameters and sends 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.

Incoming Call and Phone Call are not two ways of doing one thing. Incoming Call tells you a call happened and lets the workflow react afterwards — it acknowledges Twilio immediately and runs in the background. Phone Call answers the caller: it holds the connection open while the workflow runs and a Voice Agent node speaks to the person on the line.

Phone Call

The Phone Call trigger is the front door for a voice agent. Pick the Twilio number the workflow should answer, add a Voice Agent node downstream, and publish.

1. Add the trigger

   In the workflow editor, add the Twilio Phone Call trigger and choose your Twilio connection.

2. Pick the number

   Choose a number from the Phone number dropdown. The list is read live from your Twilio account. Expressions are not available here: publishing changes this number's settings, so it has to be a concrete number rather than one computed at run time.

3. Answer the call

   Add a Voice Agent node downstream of the trigger and give it a realtime model, a system prompt and, optionally, tools. The Voice Agent is what answers; without one the workflow has nothing to say and the publish bar refuses it.

What publishing does to the number

Publishing a workflow with a Phone Call trigger points the number's voice URL at TaskJuice. TaskJuice does this for you through Twilio's API — you never paste a URL into the Twilio Console.

Before it changes anything, TaskJuice takes a snapshot of the number's four voice fields as they are: VoiceUrl, VoiceMethod, VoiceFallbackUrl and StatusCallback. It then sets VoiceUrl to the workflow's ingress URL and VoiceMethod to POST.

Unpublishing (or deleting the workflow) restores that snapshot, field for field, so the number goes back to whatever it was pointing at before — an IVR, another platform, or nothing. A number can only be pointed at one workflow at a time: publish or activate a second workflow on the same number and TaskJuice refuses it rather than overwriting the first workflow's claim. The error names the workflow that holds the number. Unpublish or deactivate that workflow first.

Transfers

A Voice Agent can transfer the caller to a person on one of the numbers you list. A transfer is a second, outgoing call placed on the same connected Twilio account, and Twilio bills the two calls separately, each per minute and rounded up to the next minute: the inbound call the agent answered, and the outgoing call to the person.

The spend TaskJuice shows on the run for a transfer is an estimate at Twilio's list price, counted by the second. Because Twilio rounds each call up to the whole minute, the estimate can be up to a minute's charge low for each of the two calls. It also leaves out anything Twilio charges for the spoken note the person hears and for the no-answer message. Your Twilio invoice is the exact figure.

What number the person sees is set on the transfer tool: see Caller ID.

Phone Call payload

The trigger's output is Twilio's inbound voice webhook, so it carries the same fields as Incoming Call: CallSid, AccountSid, From, To, CallStatus, Direction, and the optional CallerName / geo fields. The call's transcript, recording and summary are the Voice Agent's output, not the trigger's — they only exist once the call has ended.

Response mode

Phone Call always answers synchronously through the Voice Agent node; there is no Response mode to choose. TaskJuice has 10 seconds to answer Twilio, so a slow step between the trigger and the Voice Agent (an HTTP call, an AI step) is a real risk — the publish bar warns you when it sees one. See the webhook response-modes reference.

Incoming SMS payload

Incoming Call payload

Actions

The integration ships 37 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, Messaging Service and Studio flow dropdowns work the same way. Each picker loads 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.

More actions

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.
• Webhook triggers are set up by hand: Twilio has no API for registering an account-wide webhook, so you paste the TaskJuice URL into each Twilio slot listed above. Only the Phone Call trigger configures the number for you.
• TaskJuice acknowledges Twilio's messaging webhook without a TwiML reply, so Twilio may log warning 12300 for each incoming message. That warning reaches New Debugger Alert if you route alerts here; filter on Level or the error code if it is noise.
• Intelligence Transcript Available polls: Twilio signs the Conversational Intelligence webhook over a hash of its JSON body, which TaskJuice's Twilio signature check does not cover yet. It reads your newest 100 completed transcripts per check.
• New Phone Number polls because Twilio sends no event when a number is added. It reads up to 1,000 numbers per check; numbers beyond the first 1,000 are not watched.
• Inbound verification relies on the Twilio request signature. Every webhook trigger verifies 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 actions 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 the inbound triggers (FromCity, FromState, FromCountry, and their To equivalents) appear only when Twilio has location data for the number. Treat them as optional.
• The Phone Call trigger answers INBOUND calls only. Placing a call and having the agent speak first is not available yet.
• One number, one published workflow. TaskJuice refuses to publish or activate a workflow on a number another active workflow already answers, rather than silently taking it over. Unpublish or deactivate the other workflow first.
• Rotating the Auth Token also breaks the Phone Call trigger's signature verification, and TaskJuice needs a valid connection to restore the number's previous voice URL when you unpublish. Update the connection before you unpublish.

Related

• Connect an account
• Control flow nodes
• Voice Agent node
• All integrations