Download the PHP package omerfayyaz/laravel-sms-gateway without Composer

Laravel SMS Gateway client

Send and receive SMS from a Laravel app through an SMS gateway that you host yourself, with Android phones as the modems. The package sends messages, looks them up, sends Laravel notifications as SMS, and turns the gateway's signed webhooks into Laravel events.

• Every send carries an idempotency key, so a retry never sends a second SMS.
• Queued notifications keep their key across retries.
• SmsGateway::fake() records messages in tests instead of sending them.

Requirements

• PHP 8.2 or newer, and Laravel 12.18 or newer, or 13.
• The gateway, and an app created on its dashboard under Apps, which gives the API key.

Install

Add to .env:

Then send yourself a message to check the setup:

To change the timeouts, the retries or the webhook path, publish the config file:

Sending

SmsMessage sets everything else:

The gateway accepts the message and queues it; a phone sends it shortly after. Its outcome arrives later, by webhook.

Idempotency

A request that cannot reach the gateway, or that fails on its side, is tried again, twice by default. Each retry carries the same idempotency key, so the gateway returns the message it already queued instead of sending another. When send() is called again with a key the gateway has seen, it returns that first message with replayed set.

Without a key of your own, each call to send() makes one. That covers the retries within the call, but not a job that runs twice. For those, give the message a key made from what it is for, as in the example above. Queued notifications do this for you.

The gateway remembers a key for good, so a key should name one send, not a recipient: a second reminder under reminder-{$guest->id} would never go out. The same key with another number or text is refused with a 409. Keys are at most 64 characters.

Notifications

Add 'sms-gateway' to the notification's channels, and say what to send:

The number comes from the notifiable:

or is given on demand:

A notifiable without a number is skipped. Each notification is sent with the notification's id as its idempotency key. A queued notification (ShouldQueue) keeps that id when its job is retried, so a retry cannot send the SMS twice. A notification sent straight away gets a new id each time: if the code that sends it can run twice, queue the notification or give the message a key of your own.

Looking messages up

The list holds the app's own messages, and the SMS that arrived for it (to filters by recipient; for an arrived SMS that is the number it arrived on).

Webhooks

The package registers POST /sms-gateway/webhook. The route sits outside the web middleware, so no session or CSRF token is involved; the signature authenticates each event. To set it up:

1. On the gateway's dashboard, open Apps, then your app, then Webhook.
2. Enter https://your-app.example/sms-gateway/webhook and pick the events to receive.
3. Put the signing secret it shows into SMS_GATEWAY_WEBHOOK_SECRET.

Each event becomes a Laravel event:

Each of these carries $event->message (a GatewayMessage), $event->eventId and $event->occurredAt. Every event, including ones this version doesn't know, also arrives raw as WebhookReceived.

Events arrive at least once, and not always in order:

• The gateway retries an event for about a day until it gets a 2xx answer. A repeat of an event already handled is answered but not dispatched again, for two days, using the app's cache. While one request is handling an event, a second copy is told to come back later.
• If any listener throws, the event is not remembered. The gateway's retry dispatches it again, to every listener, including the ones that succeeded the first time.
• After an outage, retries arrive in their own time, so message.sent can come after message.delivered. Don't let a status move backwards.

So make listeners safe to run twice, and use $event->eventId to tell repeats apart. A listener that replies should key its SMS by the event, so a second run sends nothing new:

Queue listeners that do slow work, so the gateway gets its answer quickly.

To register the route yourself, set SMS_GATEWAY_WEBHOOK_PATH=null, then add it where no CSRF check runs, such as routes/api.php. In routes/web.php the CSRF check would refuse every event:

Errors

Everything thrown extends OmerFayyaz\SmsGateway\Exceptions\SmsGatewayException.

• RequestFailed: the gateway answered with an error. It carries status, errors and retryAfter.
  • A 422 means the gateway refused the message, for example because the app has no active number to send from. The message says which; check isValidationError().
  • A 401 means the key is wrong.
  • A 403 means the key lacks the ability, such as sending.
• ConnectionFailed: the gateway could not be reached, or did not answer in time, even after the retries.

After a ConnectionFailed, or a RequestFailed with a 5xx status, the SMS may still have been queued. Both carry the idempotencyKey that was used; sending again with it is safe, because the gateway answers with the message it already has.

Testing

To test your webhook listeners, post an event signed the way the gateway signs it:

License

MIT. See LICENSE.md.