directus-twilio

A Directus extension bundle to send SMS and WhatsApp messages through Twilio.

This package includes:

• an API endpoint (twilio-messages)
• a Flow operation (twilio-send-message)
• a custom interface for E.164 phone numbers (phone-e164)

Features

• Send messages via sms or whatsapp
• Built-in E.164 normalization and validation for destination numbers
• Optional Twilio Messaging Service SID support (per channel)
• Optional status callback URL support
• Directus Flow operation with a user-friendly UI
• Custom Directus input interface with live phone validation

Requirements

• Directus ^10.10.0
• Node.js (recommended LTS)
• A Twilio account with valid credentials

Installation

1. Add the extension to your Directus extensions folder

If this repository is standalone, place it in your Directus extensions path.

2. Install dependencies

npm install

3. Build the bundle

npm run build

4. Restart Directus

After build, restart your Directus instance so it loads the extension.

Configuration

Set the following environment variables in your Directus environment.

| Variable | Required | Description | |---|---|---| | TWILIO_SID | Yes | Twilio Account SID | | TWILIO_TOKEN | Yes | Twilio Auth Token | | TWILIO_SMS_FROM | Conditionally | Sender for SMS in E.164 format (required if TWILIO_MESSAGING_SERVICE_SID_SMS is not set) | | TWILIO_WHATSAPP_FROM | Conditionally | Sender number for WhatsApp in E.164 format (required if TWILIO_MESSAGING_SERVICE_SID_WHATSAPP is not set) | | TWILIO_MESSAGING_SERVICE_SID_SMS | Optional | Twilio Messaging Service SID used for SMS (overrides TWILIO_SMS_FROM) | | TWILIO_MESSAGING_SERVICE_SID_WHATSAPP | Optional | Twilio Messaging Service SID used for WhatsApp (overrides TWILIO_WHATSAPP_FROM) | | TWILIO_STATUS_CALLBACK_URL | Optional | Twilio status callback URL | | TWILIO_TIMEOUT_MS | Optional | Timeout value in milliseconds (currently reserved) |

Bundle Entries

1. Endpoint: twilio-messages

Creates a POST endpoint that sends a message through Twilio.

Route (based on endpoint name):

/twilio-messages

If your Directus instance is hosted under a base path, prepend that base path accordingly.

Request body:

{
  "channel": "sms",
  "to": "+14155552671",
  "body": "Hello from Directus"
}

• channel: sms or whatsapp
• to: destination phone in E.164 format
• body: non-empty message text

Success response example:

{
  "sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "channel": "sms",
  "to": "+14155552671",
  "status": "queued"
}

Error response example:

{
  "error": "Message send failed",
  "details": {
    "message": "...",
    "code": 21608,
    "status": 400,
    "moreInfo": "..."
  }
}

2. Operation: twilio-send-message

Flow operation named Twilio: Send Message.

Options:

• channel: sms or whatsapp
• to: phone number (uses phone-e164 interface)
• body: message content

Use it in Directus Flows to send notifications or transactional messages.

3. Interface: phone-e164

Custom Directus interface for string fields.

• Validates E.164 format live (example: +14155552671)
• Shows inline error for invalid values
• Supports mustache template values (for Flow dynamic data), e.g. {{ $trigger.payload.phone }}

Development

npm run dev        # watch mode build
npm run build      # production build
npm run validate   # directus extension validation
npm run link       # link extension locally

Project Structure

src/
  twilio-messages/
  twilio-messaging-operation/
  phone-e164/
  lib/
    twilio/
    adapters/directus/

Notes

• Destination numbers must be valid E.164 values.
• For WhatsApp, Twilio expects WhatsApp-enabled sender/destination configuration.
• The extension wraps Twilio SDK errors and returns structured details when possible.

License

MIT License