Setup guide
Twilio Bulk SMS Setup Guide
🏷️ Version 1.0.0
Requires WordPress 6.0+ and PHP 8.1+
1
Overview
Twilio Bulk SMS lets WordPress administrators send single and bulk SMS messages through the Twilio API, directly from the WordPress admin dashboard. It includes contact management, CSV import, a background processed sending queue, delivery tracking, and reporting.
1.1 What you will need
- A WordPress site running WordPress 6.0 or later and PHP 8.1 or later.
- Administrator (manage_options) access to the WordPress dashboard.
- A Twilio account, trial or paid, with an Account SID, Auth Token, and either a Twilio phone number or a Messaging Service.
- Composer access on the server (or locally, to upload the vendor folder) to install the official Twilio PHP SDK.
Tip
If you don’t have a Twilio account yet, sign up at twilio.com. The trial tier is enough to complete this setup and send test messages to verified numbers.
2
Installation
2.1 Upload the plugin
- In your WordPress dashboard, go to Plugins → Add New → Upload Plugin.
- Choose the twilio-bulk-sms.zip file and click Install Now.
- Do not activate yet, the Twilio SDK must be installed first (next step). If you activate now, you will see a notice that credentials aren’t configured, which is expected.
2.2 Install the Twilio PHP SDK via Composer
The plugin uses the official Twilio PHP SDK to communicate with the Twilio API. This is not bundled in the ZIP and must be installed with Composer.
Connect to your server via SSH (or use your hosting control panel’s terminal), then run:
cd wp-content/plugins/twilio-bulk-sms
composer install --no-devThis creates a vendor/ folder inside the plugin directory containing the Twilio SDK.
Important
If your hosting provider does not offer SSH access, install Composer dependencies on your local machine inside a copy of the plugin folder, then upload the resulting vendor/ folder to the same location on the server via FTP/SFTP.
2.3 Activate the plugin
- Go to Plugins → Installed Plugins.
- Find Twilio Bulk SMS and click Activate.
- On activation, the plugin automatically creates three database tables (contacts, queue, and logs) and schedules a background task to process the sending queue.
A new “Twilio SMS” menu item will appear in the left hand admin sidebar.
3
Getting Your Twilio Credentials
Before configuring the plugin, gather the following from your Twilio Console (console.twilio.com):
3.1 Account SID and Auth Token
- Log in to the Twilio Console.
- On the main dashboard, locate the Account Info panel.
- Copy the Account SID, it always starts with AC followed by 32 characters.
- Click “View” next to Auth Token and copy it.
Important
Treat your Auth Token like a password. Never share it or commit it to a public code repository.
3.2 A sending number or a Messaging Service
You need one of the following two options, not both are required, but the plugin supports either:
Option A: A single Twilio phone number
- In the Console, go to Phone Numbers → Manage → Active Numbers.
- Copy your number in E.164 format, e.g. +14155552671.
- Use this as the From Number in the plugin settings.
Recommended for bulk
Option B: A Messaging Service
- In the Console, go to Messaging → Services.
- Create a new Messaging Service (or select an existing one) and add one or more phone numbers to its Sender Pool.
- Copy the Messaging Service SID from the service’s settings page.
Important
A Messaging Service SID always starts with the letters MG followed by 32 characters. Twilio has several other resource types whose SIDs look superficially similar, most notably a Conversation/Sync Service SID, which starts with IS. These are not interchangeable. Pasting an IS… SID into the Messaging Service SID field will cause every send to fail with an HTTP 400 error from Twilio, and because Twilio rejects the request before it is ever logged, the failure will not appear anywhere in Twilio’s Monitor → Logs, it will simply look like the message vanished. Always copy this value from Messaging → Services, never from Conversations or Sync.
Tip
Using a Messaging Service is recommended over a single From Number for bulk sending, because Twilio can automatically distribute messages across multiple numbers in the pool, improving throughput and deliverability.
4
Configuring the Plugin
4.1 Enter your credentials
- In the WordPress dashboard, go to Twilio SMS → Settings.
- Fill in the credential fields shown below.
| Field | Value |
|---|---|
| Account SID | Starts with AC, from Twilio Console dashboard |
| Auth Token | From Twilio Console dashboard (click “View”) |
| From Number | Your Twilio number in E.164 format, e.g. +14155552671 |
| Messaging Service SID | Optional. Starts with MG, overrides From Number when set |
- Click Save Settings.
- Click the Test Connection button. You should see a green “Connection successful!” message.
Important
If Test Connection reports that your Messaging Service SID is invalid, double check that the value starts with MG and was copied from Messaging → Services in the Twilio Console, not from Conversations, Sync, or any other product.
4.2 Configure queue behavior (optional)
Still on the Settings page, you can adjust how bulk sends are processed:
| Setting | Description |
|---|---|
| Batch Size | How many messages to send per processing pass. Default: 50. |
| Delay (seconds) | A short pause between each message in a batch, as a courtesy to Twilio’s API and to reduce carrier level rate limiting. Default: 2. |
| Delivery Callbacks | When enabled, Twilio will report delivery status updates back to your site automatically (see Section 6). |
5
Using the Plugin
5.1 Sending a single SMS
- Go to Twilio SMS → Send SMS.
- Enter a phone number. You may type it in E.164 format (+14155552671) or as a plain 10 digit US number, the plugin will format it automatically.
- Enter your message and click Send SMS.
On success, you’ll see the Twilio message SID and status. The message is also recorded in SMS History.
5.2 Sending bulk SMS
- Go to Twilio SMS → Bulk SMS.
- Choose a source for your recipients, either paste phone numbers directly (one per line) or switch to the Select Contacts tab to choose from your saved contacts.
- Enter your message and click Queue Bulk SMS.
Messages are added to the queue and begin sending immediately. A recurring background task also checks the queue every minute, so any messages beyond the configured batch size, or any that need retrying, will continue to be processed automatically.
Tip
You can pause, resume, cancel, or retry the queue at any time from the Dashboard page.
5.3 Managing contacts
- Add contacts manually, or import them in bulk via Twilio SMS → Import Contacts using a CSV file.
- Supported CSV columns: Phone Number (required), Name, Group, and Tags (all optional).
- Phone numbers are automatically validated and converted to E.164 format on import. Invalid numbers and duplicates are reported after import completes.
- Use Groups to organize contacts and filter them when selecting recipients for a bulk send.
5.4 Viewing history and reports
- Twilio SMS → SMS History shows every message sent, with status, Twilio SID, and timestamp. You can filter by phone number, status, or date range, and export the results to CSV.
- Twilio SMS → Reports shows aggregate statistics: daily, weekly, and monthly volume, delivery rate, and top contact groups.
- The main Dashboard page shows live counters and charts for messages sent, failed, and queued.
6
Delivery Status Callbacks
By default, a message’s status in SMS History reflects only what Twilio returned at the moment it was sent (typically “queued” or “accepted”). To see real time delivery confirmation (“delivered”, “undelivered”, “failed”), enable delivery callbacks.
- Go to Twilio SMS → Settings and check Enable Delivery Callbacks, then save.
- Copy the webhook URL shown beneath the checkbox.
https://yoursite.com/wp-json/twilio-sms/v1/delivery-status- In the Twilio Console, go to Messaging → Services, select your Messaging Service, and under Integration, paste this URL into the Status Callback URL field. If you are using a single From Number instead of a Messaging Service, set this URL under that number’s Messaging configuration instead.
From this point on, Twilio will notify your site automatically whenever a message’s delivery status changes, and SMS History will update to reflect it.
7
Troubleshooting
7.1 Plugin won’t activate / fatal error on activation
- Confirm your server is running PHP 8.1 or later.
- Make sure the plugin ZIP was uploaded and extracted completely, with no missing files.
- Check your hosting error log for the specific fatal error message, and contact support with that detail if it persists.
7.2 “Phone and message are required” when sending
- Make sure both fields are filled in before clicking Send SMS.
- If the fields are filled in but the error still appears, clear your browser cache or hard refresh the page, this can occur if an outdated cached copy of the plugin’s JavaScript file is being served.
7.3 Bulk messages stay “Queued” and never send
- Check Twilio SMS → Settings and confirm the connection test succeeds.
- Some hosting environments disable or heavily delay WP-Cron. The plugin processes the first batch immediately when you click Queue Bulk SMS, but if messages still don’t send, ask your host whether WP-Cron is enabled, or configure a real server level cron job to call wp-cron.php every minute.
7.4 Messages fail, but nothing appears in Twilio’s Monitor → Logs
- This specific combination, a failure in WordPress with no corresponding entry in Twilio’s own logs, means the request never reached Twilio’s message sending endpoint at all. The most common cause is an invalid Messaging Service SID.
- Open Twilio SMS → SMS History and look at the error_message recorded for the failed entry (visible in the database table wp_tbs_logs, or via Twilio SMS → SMS History in the dashboard).
- If the error mentions “Messaging Service Sid … is invalid”, confirm the SID in Settings starts with MG. A SID starting with IS is a different Twilio resource (Conversations/Sync) and will always be rejected, see Section 3.2.
- Re-copy the correct SID from Messaging → Services in the Twilio Console, paste it into Settings, save, and click Test Connection to confirm before retrying.
7.5 Sent messages don’t appear in SMS History
- Confirm the plugin’s database tables exist (deactivating and reactivating the plugin will recreate them if missing).
- Check your site’s PHP error log for any database related warnings at the time of sending.
7.6 Trial account limitations
- If you are using a Twilio trial account, messages can only be sent to phone numbers that have been verified in the Twilio Console under Phone Numbers → Verified Caller IDs.
- Trial messages will also include a Twilio trial banner in the message body. Upgrade to a paid account to remove these restrictions.
8
Uninstalling
Deactivating the plugin (Plugins → Installed Plugins → Deactivate) stops all scheduled processing but keeps your data and settings intact, in case you plan to reactivate later.
Deleting the plugin (Plugins → Installed Plugins → Delete, after deactivating) permanently removes all plugin database tables, contacts, queue, and SMS history, and all saved settings. This cannot be undone.
Important
Export your contacts and SMS history to CSV before deleting the plugin if you want to keep that data.
9
Quick Reference: Settings Checklist
| Item | Where to find it in Twilio |
|---|---|
| Account SID (AC…) | Console dashboard |
| Auth Token | Console dashboard → “View” |
| From Number | Phone Numbers → Manage → Active Numbers |
| Messaging Service SID (MG…) | Messaging → Services |
| Delivery webhook URL | Paste into Messaging Service → Integration → Status Callback URL |
End of document.