Laravel-Notification-Channel für WhatsApp mit TextMeFlow bauen
Laravels Notification-System verschickt Mail, Slack und SMS bereits über ein sauberes via() / toMail()-Muster. Einen offiziellen WhatsApp-Treiber gibt es nicht, aber da die TextMeFlow-API ein einziger authentifizierter POST-Request ist, ist ein eigener Channel in etwa zwanzig Zeilen Code verdrahtet – und Queueing, Retries und Fehlerbehandlung bekommst du kostenlos von Laravels bestehender Notification-Pipeline.
Diese Anleitung baut einen WhatsAppChannel, den du an jede Notification-Klasse hängen kannst, plus einen Webhook-Endpunkt, der Zustellstatus und Antworten empfängt.
Warum ein eigener Channel statt den API-Aufruf inline zu machen
Du könntest den Endpunkt von TextMeFlow direkt aus einem Controller mit Http::post(...) aufrufen, und für ein einmaliges Skript ist das in Ordnung. Aber der Weg über einen Notification-Channel bedeutet:
- Jedes Notifiable-Model (
User,Order,Booking, …) kann WhatsApp-Nachrichten per$model->notify(new OrderShipped($order))senden, so wie es bereits Mails sendet. - Notifications werden automatisch in die Queue gestellt, wenn die Notification-Klasse
ShouldQueueimplementiert – keine zusätzliche Job-Klasse nötig. - Fehlgeschlagene Sendungen laufen durch Laravels normale
failed()-Behandlung und die Retry-/Backoff-Konfiguration, statt über den Code verstreute eigene try/catch-Blöcke.
1. Die Channel-Klasse
<?php
namespace App\Notifications\Channels;
use Illuminate\Notifications\Notification;
use Illuminate\Support\Facades\Http;
class WhatsAppChannel
{
public function send(object $notifiable, Notification $notification): void
{
if (! method_exists($notification, 'toWhatsApp')) {
return;
}
$message = $notification->toWhatsApp($notifiable);
$response = Http::withToken(config('services.textmeflow.key'))
->post('https://api.textmeflow.eu/v1/messages', [
'to' => $notifiable->routeNotificationFor('whatsapp'),
'text' => $message['text'],
'media_url' => $message['media_url'] ?? null,
]);
$response->throw();
}
}
->throw() verwandelt eine Nicht-2xx-Antwort in eine Exception, wodurch Laravels Queue-Retry-Logik und der failed()-Callback bei vorübergehenden Fehlern greifen können (zum Beispiel ein 429, weil du das Rate Limit deines Tarifs erreicht hast).
2. Den Channel registrieren
Trage deinen API-Key in config/services.php ein:
'textmeflow' => [
'key' => env('TEXTMEFLOW_API_KEY'),
],
Sag Laravel dann am Notifiable-Model (oder in einem Trait, den mehrere Models teilen), an welche Nummer gesendet werden soll:
public function routeNotificationForWhatsApp(): string
{
return $this->phone_e164; // must be E.164, e.g. +32472932208
}
TextMeFlow lehnt alles, was nicht im E.164-Format vorliegt, mit einem 422 ab. Validiere oder normalisiere Telefonnummern daher bei der Eingabe statt erst beim Senden.
3. Die Notification-Klasse
<?php
namespace App\Notifications;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Notification;
use App\Notifications\Channels\WhatsAppChannel;
class OrderShipped extends Notification implements ShouldQueue
{
use Queueable;
public function __construct(private readonly string $orderNumber) {}
public function via(object $notifiable): array
{
return [WhatsAppChannel::class];
}
public function toWhatsApp(object $notifiable): array
{
return [
'text' => "Deine Bestellung #{$this->orderNumber} wurde versendet.",
];
}
}
Löse sie genau wie jede andere Notification aus:
$order->customer->notify(new OrderShipped($order->number));
Da ShouldQueue implementiert ist, wird die Sendung an deinen notifications-Queue-Worker übergeben, statt den Request zu blockieren – sinnvoll für alles, was aus einem Web-Request statt aus einem Konsolenbefehl ausgelöst wird.
4. Zustellstatus und Antworten empfangen
Das Senden ist nur die halbe Integration. TextMeFlow schickt eingehende Nachrichten und Zustellstatus-Updates per POST an eine Webhook-URL, die du im Portal konfigurierst, per HMAC signiert, damit du prüfen kannst, dass die Payload von TextMeFlow stammt und nicht von einem gefälschten Request:
// routes/web.php
Route::post('/webhooks/textmeflow', WhatsAppWebhookController::class);
public function __invoke(Request $request)
{
$signature = $request->header('X-TextMeFlow-Signature');
$expected = hash_hmac('sha256', $request->getContent(), config('services.textmeflow.webhook_secret'));
abort_unless(hash_equals($expected, $signature), 401);
$payload = $request->json()->all();
match ($payload['event']) {
'message.delivered' => $this->markDelivered($payload),
'message.received' => $this->handleReply($payload),
default => null,
};
return response()->noContent();
}
Die vollständigen Header-Namen und Event-Payload-Formate sind unter /de/docs/webhooks dokumentiert – lies das, bevor du die Signaturprüfung schreibst, denn die falsche Reihenfolge von Raw-Body und geparstem Body ist hier der häufigste Fehler (bilde den HMAC immer über den rohen Request-Body, nicht über json_encode($request->all()), das anders serialisieren kann).
Testen, ohne dein Kontingent zu verbrauchen
TextMeFlows kostenloser Tarif gibt dir 50 Nachrichten pro Monat für die gesamte Lebensdauer des Accounts, genug, um all das von Anfang bis Ende zu bauen und zu testen, ohne ein Upgrade. Richte TEXTMEFLOW_API_KEY in deiner .env.testing auf einen Sandbox-Account, oder fake den HTTP-Client in deinen Notification-Tests mit Http::fake(), damit deine CI-Suite nicht bei jedem Lauf echtes Kontingent verbrennt.
Fazit
Eine schlanke Channel-Klasse genügt, um WhatsApp in einer Laravel-App neben Mail und Slack zum gleichwertigen Kanal zu machen – derselbe notify()-Aufruf, dieselbe Queue-Infrastruktur, dieselbe Retry-Semantik. Die vollständige Endpunkt-Referenz (Medienanhänge, Statusabfrage, Rate Limits) findest du unter /de/docs/api. Erstelle einen kostenlosen TextMeFlow-Account, um einen API-Key zu erhalten und loszulegen.
Selbst WhatsApp-Nachrichten per API senden?
Für immer gratis bis 50 Nachrichten/Monat. QR scannen und in 5 Minuten die erste Nachricht senden.
Für immer gratis