Canal de notification Laravel pour WhatsApp (TextMeFlow)
Le système de notifications de Laravel gère déjà le mail, Slack et le SMS via un schéma propre via() / toMail(). Il n'existe pas de pilote WhatsApp officiel, mais comme l'API de TextMeFlow se résume à une seule requête POST authentifiée, brancher un canal personnalisé demande une vingtaine de lignes de code — et vous obtenez gratuitement la mise en file d'attente, les nouvelles tentatives et la gestion des échecs du pipeline de notifications existant de Laravel.
Ce guide construit un WhatsAppChannel que vous pouvez associer à n'importe quelle classe de notification, ainsi qu'un point d'entrée webhook pour recevoir le statut de livraison et les réponses.
Pourquoi un canal personnalisé plutôt qu'un appel direct à l'API
Vous pourriez appeler directement le point d'entrée de TextMeFlow depuis un contrôleur avec Http::post(...), et pour un script ponctuel c'est très bien. Mais passer par un canal de notification signifie que :
- Chaque modèle notifiable (
User,Order,Booking, …) peut envoyer des messages WhatsApp via$model->notify(new OrderShipped($order)), exactement comme il envoie déjà du mail. - Les notifications sont mises en file d'attente automatiquement si la classe de notification implémente
ShouldQueue— pas de classe de job supplémentaire à écrire. - Les envois en échec passent par la gestion
failed()habituelle de Laravel et sa configuration de retry/backoff, au lieu de blocs try/catch personnalisés éparpillés dans le code.
1. La classe du canal
<?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() transforme une réponse non 2xx en exception, ce qui permet à la logique de nouvelle tentative de la file Laravel et au callback failed() d'intervenir en cas d'échec transitoire (un 429 parce que vous avez atteint la limite de débit de votre forfait, par exemple).
2. Enregistrer le canal
Ajoutez votre clé API dans config/services.php :
'textmeflow' => [
'key' => env('TEXTMEFLOW_API_KEY'),
],
Puis, sur le modèle notifiable (ou dans un trait partagé entre eux), indiquez à Laravel à quel numéro envoyer :
public function routeNotificationForWhatsApp(): string
{
return $this->phone_e164; // must be E.164, e.g. +32472932208
}
TextMeFlow rejette avec une erreur 422 tout ce qui n'est pas au format E.164 ; validez ou normalisez donc les numéros de téléphone à la saisie plutôt qu'au moment de l'envoi.
3. La classe de notification
<?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' => "Votre commande #{$this->orderNumber} a été expédiée.",
];
}
}
Déclenchez-la exactement comme n'importe quelle autre notification :
$order->customer->notify(new OrderShipped($order->number));
Puisque ShouldQueue est implémenté, l'envoi est confié à votre worker de file notifications au lieu de bloquer la requête — à faire pour tout ce qui est déclenché depuis une requête web plutôt que depuis une commande console.
4. Recevoir le statut de livraison et les réponses
L'envoi n'est que la moitié de l'intégration. TextMeFlow envoie par POST les messages entrants et les mises à jour de statut de livraison vers une URL de webhook que vous configurez dans le portail, signée en HMAC pour que vous puissiez vérifier que la payload provient bien de TextMeFlow et non d'une requête usurpée :
// 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();
}
Les noms d'en-têtes complets et la forme des payloads d'événements sont documentés sur /fr/docs/webhooks — à lire avant d'écrire la vérification de signature, car se tromper entre corps brut et corps analysé est le bug le plus fréquent ici (calculez toujours le HMAC sur le corps brut de la requête, pas sur json_encode($request->all()), qui peut se resérialiser différemment).
Tester sans consommer votre quota
Le forfait gratuit de TextMeFlow vous offre 50 messages par mois pendant toute la durée de vie du compte, de quoi construire et tester tout cela de bout en bout sans passer à un forfait supérieur. Pointez TEXTMEFLOW_API_KEY vers un compte sandbox dans votre .env.testing, ou simulez le client HTTP dans vos tests de notification avec Http::fake() pour que votre suite CI ne consomme pas de vrai quota à chaque exécution.
Pour conclure
Une fine classe de canal suffit pour faire de WhatsApp un citoyen à part entière aux côtés du mail et de Slack dans une application Laravel — même appel notify(), même infrastructure de files d'attente, même logique de nouvelle tentative. Pour la référence complète des points d'entrée (pièces jointes, consultation du statut des messages, limites de débit), voir /fr/docs/api. Créez un compte TextMeFlow gratuit pour obtenir une clé API et commencer à envoyer.
Envie d'envoyer des messages WhatsApp via API ?
Gratuit pour toujours jusqu'à 50 messages/mois. Scannez un QR et envoyez votre premier message en 5 minutes.
Gratuit pour toujours