Module twilio.trigger
ballerinax/twilio.trigger Ballerina library
Overview
The Twilio Trigger module allows you to listen to Twilio status callbacks:
- Call status changes:
initiated,queued,ringing,in-progress,completed,busy,failed,no-answerandcanceled - Message status changes:
accepted,scheduled,queued,sending,sent,delivered,undelivered,failed,read,canceled,receiving,receivedandpartially_delivered
This module receives Twilio's status callbacks directly - it does not call Twilio's REST API on
your behalf. Use the ballerinax/twilio
connector for that, for example to send a message.
Key features
- Receives Twilio call status (9 statuses) and message status (13 statuses) callbacks
- Verifies every callback with the account's Auth Token (
X-Twilio-Signature, signed over the full URL and parameters) - Serves call and message callbacks on their own paths,
/callStatusand/smsStatus - Acknowledges each delivery before running your handler, so a slow or failing handler doesn't cause retries
- Services can be attached on their own path, so several triggers and HTTP services can share one port
- Trigger services are listed by
bal build --export-endpoints(Ballerina 2201.13.6 or later)
Setup guide
Before using this trigger in your Ballerina application, you need a Twilio account with a phone number, and a Ballerina service that Twilio can reach over the internet to deliver status callbacks to. The two sections below cover both a quick local test setup and a production deployment.
The listener serves call status callbacks at /callStatus and message status callbacks at
/smsStatus, so the URLs you give Twilio are your public base URL followed by one of those paths.
Try it out locally
Use this flow to test your callback handling logic on your own machine before deploying anywhere, using ngrok to expose your local listener to the internet.
-
In the Twilio Console, find Account Info on the home page and copy the Auth Token. Twilio signs every callback with it, and the listener uses it to reject requests that did not come from Twilio (how Twilio signs requests).
-
Expose port
8090with ngrok:ngrok http 8090Copy the
ForwardingURL ngrok prints out (for examplehttps://abc123.ngrok-free.app) - this is your temporary public base URL. -
Write your service (see Quickstart below) with the Auth Token as
webhookSecretand the ngrok URL aswebhookBaseUrl, and run it withbal run.webhookBaseUrlmust be exactly the scheme and host Twilio calls, without a trailing slash, because Twilio signs the full URL. The listener adds the path and any query string it receives, so a callback URL with query parameters works too. -
To receive call status callbacks, create a call with
StatusCallbackset to<ngrok URL>/callStatus. Twilio callsToand plays the TwiML atUrl; on a trial account,Tomust be a number you have verified.curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Calls.json" \ --data-urlencode "From=<your Twilio number>" \ --data-urlencode "To=<your phone number>" \ --data-urlencode "Url=http://demo.twilio.com/docs/voice.xml" \ --data-urlencode "StatusCallback=<ngrok URL>/callStatus" \ --data-urlencode "StatusCallbackEvent=initiated ringing answered completed" \ -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN"For calls to your Twilio number, set Call status changes under Voice Configuration on the number's Configure tab (Phone Numbers > Manage > Active numbers) to
<ngrok URL>/callStatusinstead. See Voice webhooks and the Call resource for both options. -
To receive message status callbacks, send a message with
StatusCallbackset to<ngrok URL>/smsStatus. On a trial account,Tomust be a number you have verified.curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Messages.json" \ --data-urlencode "From=<your Twilio number>" \ --data-urlencode "To=<your phone number>" \ --data-urlencode "Body=Hello from Ballerina" \ --data-urlencode "StatusCallback=<ngrok URL>/smsStatus" \ -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" -
Twilio posts each status the call or message goes through (
initiated,ringing,completed,queued,sent,delivered, ...). Each callback shows up in the ngrok console asPOST /callStatusorPOST /smsStatuswith200 OK, and your handler runs. To see a callback's parameters, open ngrok's request inspector athttp://127.0.0.1:4040. A401means the signature check failed: check the Auth Token and thatwebhookBaseUrlmatches the ngrok URL.
Without StatusCallbackEvent, Twilio sends only the final call status (completed, busy,
failed, no-answer or canceled), and the Call status changes setting on a number works the
same way. answered arrives as in-progress. For all messages sent through a Messaging Service,
set the service's Delivery Status Callback under Integration instead of passing
StatusCallback each time.
Production / business integration
For production use, deploy your Ballerina service somewhere with a stable, internet-reachable HTTPS URL. Ballerina doesn't require any specific hosting platform - containers, a VM, a managed PaaS, or anything else that gives you a stable HTTPS endpoint all work equally well.
Rather than hardcoding the values shown in the Quickstart, inject them via Config.toml (or your
platform's equivalent configuration/secret mechanism), since they are configurable:
[<your_org>.<your_module_name>.userInput] webhookSecret = "<your Auth Token>" webhookBaseUrl = "https://<your production host>"
Then use your production URL in place of the ngrok URL in the callback URLs above, and set
webhookBaseUrl to it. If you rotate the Auth Token in the Twilio Console, update
webhookSecret too, or every callback is rejected.
Compatibility
| Version | |
|---|---|
| Ballerina Language | Ballerina Swan Lake 2201.13.0 |
Quickstart
To use the Twilio Trigger in your Ballerina application, update the .bal file as follows:
Step 1: Import the Twilio Trigger Ballerina library
import ballerinax/twilio.trigger as twilio;
Step 2: Initialize the Twilio Listener
Initialize the trigger by providing the listener config and a port number/http:Listener object.
configurable twilio:ListenerConfig userInput = { webhookSecret: "xxxxxx", webhookBaseUrl: "https://xxxx.ngrok-free.app" }; listener twilio:Listener twilioListener = new (userInput, 8090);
webhookSecret should always be set to your account's Auth Token - this is what the trigger uses
to verify incoming callbacks actually came from Twilio. Without it, the listener rejects every request with 401 Unauthorized. webhookBaseUrl is the public base URL Twilio calls,
which is part of what Twilio signs.
If you don't provide a port it will use the default port, which is 8090.
listener twilio:Listener twilioListener = new (userInput);
Step 3: Use the correct service type to implement the service
Use CallStatusService for call status callbacks and SmsStatusService for message status
callbacks. Every remote function declared on a service type must be implemented - Ballerina
requires a complete implementation, not just the ones you care about.
service twilio:CallStatusService on twilioListener { remote function onInitiated(twilio:CallStatusEventWrapper payload) returns error? { } remote function onQueued(twilio:CallStatusEventWrapper payload) returns error? { } remote function onRinging(twilio:CallStatusEventWrapper payload) returns error? { } remote function onInProgress(twilio:CallStatusEventWrapper payload) returns error? { } remote function onCompleted(twilio:CallStatusEventWrapper payload) returns error? { } remote function onBusy(twilio:CallStatusEventWrapper payload) returns error? { } remote function onFailed(twilio:CallStatusEventWrapper payload) returns error? { } remote function onNoAnswer(twilio:CallStatusEventWrapper payload) returns error? { } remote function onCanceled(twilio:CallStatusEventWrapper payload) returns error? { } }
Step 4: Provide remote functions corresponding to the events you're interested in
Each status has its own remote function on the matching service type - for example,
onCompleted on twilio:CallStatusService when a call ends normally.
import ballerina/log; service twilio:CallStatusService on twilioListener { remote function onCompleted(twilio:CallStatusEventWrapper payload) returns error? { log:printInfo("Call completed", callSid = payload.CallSid, 'from = payload.From, to = payload.To, durationSeconds = payload.CallDuration); } // ... the other remote functions of CallStatusService }
Step 5: Run the service
Use the bal run command to compile and run the Ballerina program.
Step 6: Point Twilio at your service
See Setup guide above for the full walkthrough of exposing your service and setting the callback URLs, for both local testing and production use.
Examples
The twilio.trigger module provides practical examples illustrating usage in various scenarios.
Explore these examples,
covering common status callback handling use cases.
Report issues
To report bugs, request new features, start new discussions, etc., go to the Ballerina Library repository.
Useful links
- For more information go to the
twilio.triggerpackage. - If you're moving from the older
trigger.twiliopackage, see the migration notes. - For example demonstrations of the usage, go to Ballerina By Examples.
- Chat live with us via our Discord server.
- Post all technical questions on Stack Overflow with the #ballerina tag.
Import
import ballerinax/twilio.trigger;Other versions
0.9.0