Download the PHP package palpalani/laravel-bandwidth-api without Composer

Bandwidth API for Laravel

A simple, elegant Laravel wrapper for the Bandwidth API. Send SMS/MMS messages, make voice calls, implement two-factor authentication, and integrate WebRTC communications into your Laravel applications with ease.

Features

• 📱 SMS/MMS Messaging - Send text and multimedia messages with media attachments
• 📞 Voice API - Manage inbound and outbound voice calls
• 🔐 Two-Factor Authentication - Implement 2FA with voice or SMS
• 🌐 WebRTC - Browser-based real-time communications
• 🔍 Phone Number Lookup - Validate and lookup phone number information
• 🎛️ Dashboard API - Manage your Bandwidth account programmatically
• ✨ Structured Responses - Consistent error handling and response format
• 🎯 Message Tagging - Organize and track messages with custom tags
• 🏗️ Laravel Integration - Service provider, facade, and dependency injection support

Requirements

• PHP 8.3 or higher
• Laravel 11.x, or 12.x
• A Bandwidth account with API credentials

Installation

Install the package via Composer:

Publish the configuration file:

This will create a config/bandwidth.php configuration file.

Configuration

Add your Bandwidth API credentials to your .env file:

Published Configuration File

The config/bandwidth.php file contains the following structure:

Note: You don't need credentials for all APIs. Configure only the services you plan to use.

Getting Your Credentials

1. Sign up for a Bandwidth account
2. Navigate to your Bandwidth Dashboard
3. Create API credentials for the services you need
4. For messaging, create an Application to get your application_id
5. Your account_id can be found in your account settings

Usage

Basic SMS Messaging

Using the Facade:

Using Dependency Injection:

Message Tagging

Organize and track messages with custom tags (available since v0.6.0):

Response Structure

All sendMessage() calls return a structured array (since v0.5.0):

Success Response:

Error Response:

Error Handling

Dashboard API Access

Access your Bandwidth account information:

Advanced: Direct SDK Access

For advanced use cases, access the underlying Bandwidth SDK clients directly:

API Reference

Bandwidth Class

sendMessage()

Send an SMS or MMS message.

Parameters:

• $from - The phone number to send from (E.164 format)
• $to - Array of recipient phone numbers (E.164 format)
• $text - The message text content
• $tag - Optional tag for organizing messages (since v0.6.0)

Returns: Array with keys:

• success (bool) - Whether the operation succeeded
• message (string) - Human-readable status message
• id (string|null) - Bandwidth message ID on success
• data (object) - Full API response on success
• error (string) - Error message on failure

getAccount()

Get the Bandwidth account object for dashboard operations.

Returns: Iris\Account object for account management

Environment Variables

Testing

Run the test suite:

Run static analysis:

Fix code style issues:

Testing Your Integration

When testing, you can use Bandwidth's test credentials or mock the Bandwidth class:

Troubleshooting

Common Issues

Problem: "Application ID not configured"

• Solution: Ensure BANDWIDTH_MESSAGING_APPLICATION_ID is set in your .env file. This is required since v0.4.0.

Problem: "Invalid phone number format"

• Solution: Use E.164 format for phone numbers (e.g., +1234567890). Include the country code with + prefix.

Problem: "The to parameter must be an array"

• Solution: Always pass recipient numbers as an array: to: ['+1234567890'] not to: '+1234567890'

Problem: "Unexpected response type"

• Solution: This usually indicates an API version mismatch. Ensure you're using compatible versions of bandwidth/sdk and bandwidth/iris.

Enable Debug Logging

Add logging to debug issues:

Check API Status

Visit Bandwidth Status Page to check for service outages.

Upgrade Guide

Upgrading to v0.6.0 from v0.5.0

New Feature: Optional tag parameter added to sendMessage().

No breaking changes - fully backward compatible.

Upgrading to v0.5.0 from v0.4.0

Breaking Change: sendMessage() response structure changed.

Before (v0.4.0):

After (v0.5.0):

Migration Steps:

1. Update all sendMessage() calls to handle the new array response
2. Replace exception handling with $result['success'] checks
3. Update tests to expect the new response structure

Upgrading to v0.4.0 from v0.3.0

Breaking Change: Removed $applicationId parameter from sendMessage().

Before (v0.3.0):

After (v0.4.0):

Migration Steps:

1. Add BANDWIDTH_MESSAGING_APPLICATION_ID to your .env file
2. Remove the $applicationId parameter from all sendMessage() calls
3. Republish the config if you published it before v0.4.0

FAQ

Q: Do I need to configure all API credentials? A: No, only configure the services you plan to use. For example, if you only need SMS, just set the messaging credentials.

Q: What's the difference between account_id and application_id? A: The account_id is your Bandwidth account identifier. The application_id is specific to your messaging application created in the Bandwidth dashboard. You need both for messaging.

Q: Can I send messages to multiple recipients? A: Yes, pass an array of phone numbers to the to parameter. Bandwidth will send individual messages to each recipient.

Q: How do I send MMS with images? A: Currently, the package's sendMessage() helper focuses on text messages. For MMS with media, use the direct SDK access to set the media property on the MessageRequest object.

Q: Is there a rate limit? A: Yes, Bandwidth enforces rate limits. Check your account's rate limits in the Bandwidth dashboard and implement appropriate throttling in your application.

Q: How can I track message delivery status? A: Configure webhooks in your Bandwidth dashboard to receive delivery receipts. The package returns a message ID that you can use to correlate webhook callbacks.

Q: Does this support Laravel Vapor/serverless? A: Yes, the package is stateless and works with serverless deployments like Laravel Vapor.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

We welcome contributions! Whether it's:

• Bug reports and fixes
• Feature requests and implementations
• Documentation improvements
• Code quality enhancements

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Never commit your Bandwidth API credentials to version control. Always use environment variables and keep your .env file secure.

Credits

• palPalani
• All Contributors

This package is a Laravel wrapper for the official Bandwidth SDK. Special thanks to Bandwidth for providing excellent communications APIs.

License

The MIT License (MIT). Please see License File for more information.

Resources

• Bandwidth Developer Documentation
• Bandwidth API Reference
• Bandwidth PHP SDK
• Bandwidth IRIS SDK
• Package Documentation

Note: This is an unofficial Laravel package. Bandwidth® is a registered trademark of Bandwidth Inc.