Actions

The ballerinax/twilio package exposes the following clients:

Client	Purpose
Client	Full Twilio REST API access: messaging, voice calls, phone numbers, recordings, conferences, and account management.

Client

Full Twilio REST API access: messaging, voice calls, phone numbers, recordings, conferences, and account management.

Configuration

Field	Type	Default	Description
auth	AuthTokenConfig|ApiKeyConfig	Required	Authentication configuration: either Auth Token or API Key based.
httpVersion	HttpVersion	HTTP_2_0	HTTP protocol version.
http1Settings	ClientHttp1Settings	()	Configurations for HTTP/1.x protocol.
http2Settings	ClientHttp2Settings	()	Configurations for HTTP/2 protocol.
timeout	decimal	60	Request timeout in seconds.
forwarded	string	"disable"	The choice of setting forwarded/x-forwarded header.
retryConfig	RetryConfig	()	Retry configuration for failed requests.
responseLimits	ResponseLimitConfigs	()	Configurations associated with inbound response size limits.
secureSocket	ClientSecureSocket	()	SSL/TLS configuration.
proxy	ProxyConfig	()	Proxy server configuration.
compression	Compression	COMPRESSION_AUTO	HTTP compression configuration.
circuitBreaker	CircuitBreakerConfig	()	Circuit breaker configuration for fault tolerance.
poolConfig	PoolConfiguration	()	HTTP connection pool configuration.
cache	CacheConfig	()	HTTP response cache configuration.
validation	boolean	true	Enable/disable payload validation.

Initializing the client

Using Auth Token authentication:

import ballerinax/twilio;

configurable string accountSid = ?;
configurable string authToken = ?;

twilio:Client twilioClient = check new ({
    auth: {
        accountSid: accountSid,
        authToken: authToken
    }
});

Using API Key authentication:

import ballerinax/twilio;

configurable string accountSid = ?;
configurable string apiKey = ?;
configurable string apiSecret = ?;

twilio:Client twilioClient = check new ({
    auth: {
        accountSid: accountSid,
        apiKey: apiKey,
        apiSecret: apiSecret
    }
});

Operations

Messaging

createMessage

Sends an SMS, MMS, or WhatsApp message.

Parameters:

Name	Type	Required	Description
payload	CreateMessageRequest	Yes	Message details including To, From, Body, and optional MediaUrl.
accountSid	string	No	Account SID override. Defaults to the authenticated account.

Returns: Message|error

Sample code:

twilio:CreateMessageRequest messageRequest = {
    To: "+1234567890",
    From: "+0987654321",
    Body: "Hello from Ballerina"
};

twilio:Message response = check twilioClient->createMessage(messageRequest);

Sample response:

{"sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "status": "queued", "to": "+1234567890", "from": "+0987654321", "body": "Hello from Ballerina", "num_segments": "1", "direction": "outbound-api"}

fetchMessage

Retrieves a message by its SID.

Parameters:

Name	Type	Required	Description
sid	string	Yes	The Message SID.
accountSid	string	No	Account SID override.

Returns: Message|error

Sample code:

twilio:Message message = check twilioClient->fetchMessage("SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");

Sample response:

{"sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "status": "delivered", "to": "+1234567890", "from": "+0987654321", "body": "Hello from Ballerina", "date_sent": "Mon, 10 Mar 2026 14:30:00 +0000"}

listMessage

Lists messages, optionally filtered by sender, recipient, or date.

Parameters:

Name	Type	Required	Description
to	string	No	Filter by recipient phone number.
from	string	No	Filter by sender phone number.
dateSent	string	No	Filter by date sent (YYYY-MM-DD).
pageSize	int	No	Number of records to return per page.
accountSid	string	No	Account SID override.

Returns: ListMessageResponse|error

Sample code:

twilio:ListMessageResponse messages = check twilioClient->listMessage(to = "+1234567890", pageSize = 10);

Sample response:

{"messages": [{"sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "status": "delivered", "to": "+1234567890", "body": "Hello"}], "page_size": 10, "page": 0}

deleteMessage

Deletes a message by its SID.

Parameters:

Name	Type	Required	Description
sid	string	Yes	The Message SID to delete.
accountSid	string	No	Account SID override.

Returns: http:Response|error

Sample code:

http:Response response = check twilioClient->deleteMessage("SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");

Voice calls

createCall

Initiates an outbound voice call.

Parameters:

Name	Type	Required	Description
payload	CreateCallRequest	Yes	Call details: see required and optional fields below.
accountSid	string	No	Account SID override.

CreateCallRequest required fields:

Name	Type	Description
To	string	The phone number to call, in E.164 format.
From	string	Your Twilio number to use as the caller ID, in E.164 format.

note

Provide exactly one of Url, Twiml, or ApplicationSid to specify the call instructions:

• Url: URL of a TwiML document or Twilio Application to fetch call instructions from.
• Twiml: Inline TwiML string for simple call flows that do not require a separate server.
• ApplicationSid: SID of a Twilio Application with configured voice URLs.

Optional fields include StatusCallback, StatusCallbackMethod, StatusCallbackEvent, Record, Timeout, and others: see the Twilio REST API reference for the full list.

Returns: Call|error

Sample code:

twilio:CreateCallRequest callRequest = {
    To: "+1234567890",
    From: "+0987654321",
    Url: "http://demo.twilio.com/docs/voice.xml",
    StatusCallback: "https://your-app.example.com/status",
    StatusCallbackMethod: "POST"
};

twilio:Call response = check twilioClient->createCall(callRequest);

Sample response:

{"sid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "status": "queued", "to": "+1234567890", "from": "+0987654321", "direction": "outbound-api"}

fetchCall

Retrieves details of a call by its SID.

Parameters:

Name	Type	Required	Description
sid	string	Yes	The Call SID.
accountSid	string	No	Account SID override.

Returns: Call|error

Sample code:

twilio:Call call = check twilioClient->fetchCall("CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");

Sample response:

{"sid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "status": "completed", "to": "+1234567890", "from": "+0987654321", "duration": "45", "price": "-0.0085", "price_unit": "USD"}

listCall

Lists calls, optionally filtered by status, phone number, or date.

Parameters:

Name	Type	Required	Description
to	string	No	Filter by recipient.
from	string	No	Filter by caller.
status	Call_enum_status	No	Filter by call status.
pageSize	int	No	Number of records per page.
accountSid	string	No	Account SID override.

Returns: ListCallResponse|error

Sample code:

twilio:ListCallResponse calls = check twilioClient->listCall(status = "completed", pageSize = 20);

Sample response:

{"calls": [{"sid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "status": "completed", "duration": "45"}], "page_size": 20, "page": 0}

deleteCall

Deletes a call record by its SID.

Parameters:

Name	Type	Required	Description
sid	string	Yes	The Call SID to delete.
accountSid	string	No	Account SID override.

Returns: http:Response|error

Sample code:

http:Response response = check twilioClient->deleteCall("CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");

Account management

createAccount

Creates a new Twilio sub-account.

Parameters:

Name	Type	Required	Description
payload	CreateAccountRequest	Yes	Account creation details including optional FriendlyName.

Returns: Account|error

Sample code:

twilio:CreateAccountRequest accountRequest = {
    FriendlyName: "My Sub Account"
};

twilio:Account subAccount = check twilioClient->createAccount(accountRequest);

Sample response:

{"sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "friendly_name": "My Sub Account", "status": "active", "type": "Full"}

fetchAccount

Retrieves account details by SID.

Parameters:

Name	Type	Required	Description
sid	string	Yes	The Account SID.

Returns: Account|error

Sample code:

twilio:Account account = check twilioClient->fetchAccount("ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");

Sample response:

{"sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "friendly_name": "My Account", "status": "active", "type": "Full"}

fetchBalance

Retrieves the account balance.

Parameters:

Name	Type	Required	Description
accountSid	string	No	Account SID. Defaults to the authenticated account.

Returns: Balance|error

Sample code:

twilio:Balance balance = check twilioClient->fetchBalance();

Sample response:

{"account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "balance": "25.50", "currency": "USD"}

listAccount

Lists accounts, optionally filtered by name or status.

Parameters:

Name	Type	Required	Description
friendlyName	string	No	Filter by friendly name.
status	Account_enum_status	No	Filter by account status.
pageSize	int	No	Number of records per page.

Returns: ListAccountResponse|error

Sample code:

twilio:ListAccountResponse accounts = check twilioClient->listAccount(status = "active");

Sample response:

{"accounts": [{"sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "friendly_name": "My Account", "status": "active"}], "page_size": 50, "page": 0}

updateAccount

Updates properties of an account.

Parameters:

Name	Type	Required	Description
sid	string	Yes	The Account SID of the account to update.
payload	UpdateAccountRequest	Yes	Update parameters.

UpdateAccountRequest fields:

Name	Type	Required	Description
FriendlyName	string	No	A human-readable name for the account.
Status	Account_enum_status	No	The new status for the account: active, suspended, or closed.

Returns: Account|error

Sample code:

twilio:Account updated = check twilioClient->updateAccount("ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", {
    FriendlyName: "Updated Account Name"
});

Phone number management

createIncomingPhoneNumber

Purchases a new phone number for your account.

Parameters:

Name	Type	Required	Description
payload	CreateIncomingPhoneNumberRequest	Yes	Phone number purchase details including the number or area code.
accountSid	string	No	Account SID override.

Returns: Incoming_phone_number|error

Sample code:

twilio:Incoming_phone_number number = check twilioClient->createIncomingPhoneNumber({
    PhoneNumber: "+1234567890"
});

Sample response:

{"sid": "PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "phone_number": "+1234567890", "friendly_name": "(123) 456-7890", "capabilities": {"voice": true, "sms": true, "mms": true}}

listIncomingPhoneNumber

Lists phone numbers owned by the account.

Parameters:

Name	Type	Required	Description
phoneNumber	string	No	Filter by phone number.
friendlyName	string	No	Filter by friendly name.
pageSize	int	No	Number of records per page.
accountSid	string	No	Account SID override.

Returns: ListIncomingPhoneNumberResponse|error

Sample code:

twilio:ListIncomingPhoneNumberResponse numbers = check twilioClient->listIncomingPhoneNumber(pageSize = 20);

Sample response:

{"incoming_phone_numbers": [{"sid": "PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "phone_number": "+1234567890", "friendly_name": "(123) 456-7890"}], "page_size": 20}

listAvailablePhoneNumberLocal

Searches for available local phone numbers to purchase.

Parameters:

Name	Type	Required	Description
countryCode	string	Yes	ISO 3166-1 alpha-2 country code (e.g., "US").
areaCode	int	No	Filter by area code.
smsEnabled	boolean	No	Filter for SMS-capable numbers.
voiceEnabled	boolean	No	Filter for voice-capable numbers.
accountSid	string	No	Account SID override.

Returns: ListAvailablePhoneNumberLocalResponse|error

Sample code:

twilio:ListAvailablePhoneNumberLocalResponse available = check twilioClient->listAvailablePhoneNumberLocal(
    "US", areaCode = 415, smsEnabled = true
);

Sample response:

{"available_phone_numbers": [{"phone_number": "+14155551234", "friendly_name": "(415) 555-1234", "capabilities": {"voice": true, "SMS": true, "MMS": true}}]}

Recordings

listRecording

Lists recordings for the account.

Parameters:

Name	Type	Required	Description
dateCreated	string	No	Filter by creation date (YYYY-MM-DD).
pageSize	int	No	Number of records per page.
accountSid	string	No	Account SID override.

Returns: ListRecordingResponse|error

Sample code:

twilio:ListRecordingResponse recordings = check twilioClient->listRecording(pageSize = 10);

Sample response:

{"recordings": [{"sid": "RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "duration": "30", "status": "completed", "call_sid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}], "page_size": 10}

fetchRecording

Retrieves a recording by its SID.

Parameters:

Name	Type	Required	Description
sid	string	Yes	The Recording SID.
accountSid	string	No	Account SID override.

Returns: Recording|error

Sample code:

twilio:Recording recording = check twilioClient->fetchRecording("RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx");

Sample response:

{"sid": "RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "duration": "30", "status": "completed", "call_sid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "price": "-0.0025", "price_unit": "USD"}

deleteRecording

Deletes a recording by its SID.

Parameters:

Name	Type	Required	Description
sid	string	Yes	The Recording SID to delete.
accountSid	string	No	Account SID override.

Returns: http:Response|error

Sample code:

http:Response response = check twilioClient->deleteRecording("RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx");

Conferences

listConference

Lists conferences for the account.

Parameters:

Name	Type	Required	Description
friendlyName	string	No	Filter by conference friendly name.
status	Conference_enum_status	No	Filter by conference status.
pageSize	int	No	Number of records per page.
accountSid	string	No	Account SID override.

Returns: ListConferenceResponse|error

Sample code:

twilio:ListConferenceResponse conferences = check twilioClient->listConference(status = "completed", pageSize = 10);

Sample response:

{"conferences": [{"sid": "CFxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "friendly_name": "MyConference", "status": "completed"}], "page_size": 10}

fetchConference

Retrieves a conference by its SID.

Parameters:

Name	Type	Required	Description
sid	string	Yes	The Conference SID.
accountSid	string	No	Account SID override.

Returns: Conference|error

Sample code:

twilio:Conference conference = check twilioClient->fetchConference("CFxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");

Sample response:

{"sid": "CFxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "friendly_name": "MyConference", "status": "completed", "region": "us1"}

Queue management

createQueue

Creates a new call queue.

Parameters:

Name	Type	Required	Description
payload	CreateQueueRequest	Yes	Queue creation details including FriendlyName.
accountSid	string	No	Account SID override.

Returns: Queue|error

Sample code:

twilio:Queue queue = check twilioClient->createQueue({
    FriendlyName: "Support Queue"
});

Sample response:

{"sid": "QUxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "friendly_name": "Support Queue", "current_size": 0, "max_size": 1000}

listQueue

Lists call queues for the account.

Parameters:

Name	Type	Required	Description
pageSize	int	No	Number of records per page.
accountSid	string	No	Account SID override.

Returns: ListQueueResponse|error

Sample code:

twilio:ListQueueResponse queues = check twilioClient->listQueue(pageSize = 10);

Sample response:

{"queues": [{"sid": "QUxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "friendly_name": "Support Queue", "current_size": 0}], "page_size": 10}

Usage

listUsageRecord

Lists usage records for the account.

Parameters:

Name	Type	Required	Description
category	Usage_record_enum_category	No	Filter by usage category (e.g., sms, calls).
startDate	string	No	Start date for the usage period (YYYY-MM-DD).
endDate	string	No	End date for the usage period (YYYY-MM-DD).
pageSize	int	No	Number of records per page.
accountSid	string	No	Account SID override.

Returns: ListUsageRecordResponse|error

Sample code:

twilio:ListUsageRecordResponse usage = check twilioClient->listUsageRecord(pageSize = 10);

Sample response:

{"usage_records": [{"category": "sms", "description": "SMS Messages", "count": "150", "price": "1.125", "price_unit": "USD"}], "page_size": 10}

What's next

• Trigger Reference: Event-driven webhook integration using the Twilio listener.
• Example: Complete example integrations for the Twilio connector and trigger.
• Setup Guide: Create a Twilio account and obtain credentials.