API WhatsApp
Votre application peut envoyer des messages WhatsApp aux acheteurs d'une boutique grâce à quatre endpoints. Les messages utilisent les modèles de commande que DZBuild a fait approuver par Meta, et chacun est payé par le solde WhatsApp de la boutique, exactement comme les messages que l'addon WhatsApp Sender envoie de lui-même. Vous ne pouvez pas envoyer de texte libre ni vos propres modèles.
La référence complète des requêtes et réponses se trouve dans la description OpenAPI, accessible depuis la page Référence de l'API. Cette page explique comment les éléments s'articulent.
Scopes
| Scope | Autorise |
|---|---|
whatsapp:read | GET /v1/whatsapp/templates, GET /v1/whatsapp/balance, GET /v1/whatsapp/messages |
whatsapp:send | POST /v1/orders/{id}/whatsapp |
Ne demandez dans l'URL d'autorisation que les scopes dont vous avez besoin. Un appel sans le scope répond 403 avec le code forbidden et le message Missing scope: whatsapp:send (ou whatsapp:read). Voir Scopes.
Modèles
GET /v1/whatsapp/templates liste les six modèles. Il lit le statut d'approbation que DZBuild conserve et n'appelle jamais Meta.
| Clé | Envoyé pour |
|---|---|
received | La commande a été reçue. |
confirmed | La commande a été confirmée. |
shipped_home | Le colis est en route vers l'adresse de l'acheteur. |
shipped_desk | Le colis est en route vers un bureau du transporteur. |
delivery_failed | La tentative de livraison a échoué. |
desk_ready | Le colis est prêt à être retiré. |
Chaque élément contient key, name (le nom du modèle chez Meta, par exemple dz_order_confirmed), toggle (l'interrupteur correspondant du marchand dans l'addon) et languages. languages.ar et languages.fr contiennent chacun le body avec ses variables, un example et le status. Un modèle ne peut être envoyé que dans une langue dont le statut est APPROVED. UNKNOWN signifie que DZBuild n'a encore aucun statut enregistré.
Solde
GET /v1/whatsapp/balance renvoie :
| Champ | Signification |
|---|---|
balance | Messages restants dans le solde de la boutique. Un message coûte un crédit. |
low_balance | true quand il reste moins de 50 messages. |
addon_active | Indique si le marchand a activé l'addon WhatsApp Sender. |
stats | Nombre de messages des 30 derniers jours par statut (sent, delivered, read, failed) et used_month, les crédits utilisés depuis le premier jour du mois. |
Le marchand recharge son solde dans le tableau de bord DZBuild. Votre application ne peut pas ajouter de crédit.
Envoyer un message
POST /v1/orders/{id}/whatsapp met en file un modèle pour une commande de la boutique. C'est une écriture, elle exige donc un en-tête Idempotency-Key (voir Limites de requêtes).
POST /v1/orders/98765/whatsapp HTTP/1.1
Host: api.dzbuild.app
Authorization: Bearer dzpk_live_xxxxxxxx
Idempotency-Key: wa-98765-confirmed
Content-Type: application/json
{"template": "confirmed", "language": "fr"}
| Champ du corps | Obligatoire | Signification |
|---|---|---|
template | Oui | L'une des six clés, ou shipped. shipped choisit le bon modèle selon le type de livraison de la commande : shipped_home pour la livraison à domicile, shipped_desk pour un bureau, desk_ready pour le retrait. |
language | Non | ar ou fr. Sans ce champ, la langue réglée dans l'addon WhatsApp Sender de la boutique est utilisée, ou la langue de la boutique si l'addon n'en a pas. Si cette langue de repli n'est ni ar ni fr, le message part en arabe. |
Un envoi manuel ignore les interrupteurs d'envoi automatique du marchand dans l'addon. L'addon doit cependant être actif sur la boutique.
L'appel répond 202 quand le message est en file et le crédit débité :
{
"data": { "message_id": 4411, "status": "queued", "template": "confirmed", "language": "fr" },
"meta": { "request_id": "8f2c1a9d4b7e6035", "api_version": "v1" }
}
DZBuild envoie les messages en file en arrière-plan. Suivez le résultat avec GET /v1/whatsapp/messages.
Réponses et codes d'erreur
| Statut | Code | Signification |
|---|---|---|
202 | En file, un crédit débité. | |
400 | bad_request | L'identifiant de commande n'est pas numérique, ou le corps n'est pas un JSON valide. |
402 | no_credit | Le solde WhatsApp de la boutique est vide. Rien n'a été mis en file ni débité. |
403 | addon_not_active | Le marchand n'a pas activé l'addon WhatsApp Sender. |
403 | forbidden | Le jeton n'a pas whatsapp:send. |
404 | not_found | Aucune commande avec cet identifiant sur cette boutique. |
409 | already_sent | Ce modèle a déjà été envoyé pour cette commande. L'objet d'erreur porte l'id et le status du message existant. |
422 | unknown_template | template ne fait pas partie des clés acceptées. |
422 | invalid_language | language n'est ni ar ni fr. |
422 | invalid_number | Le téléphone de l'acheteur n'est pas un numéro mobile algérien valide. |
422 | suppressed | Le numéro de l'acheteur est bloqué pour les messages WhatsApp sur la plateforme. |
422 | template_not_approved | Le modèle n'est pas approuvé dans cette langue. |
422 | empty_param | Une valeur exigée par le modèle est vide sur la commande. |
500 | send_failed | Le message n'a pas pu être mis en file. Réessayez plus tard. |
Chaque modèle peut être envoyé une fois par commande via l'API. Un appel ultérieur pour le même modèle et la même commande répond 409, même si le premier message a échoué. Les réponses 422 de invalid_number à empty_param sont différentes : rien n'a été débité, et l'appel suivant pour ce modèle et cette commande réessaie. Corrigez la cause (par exemple le numéro de téléphone de la commande), puis rappelez avec un nouvel Idempotency-Key.
Journal des messages
GET /v1/whatsapp/messages liste les messages de la boutique, du plus récent au plus ancien. Paramètres de requête : order_id pour filtrer une commande, limit (50 par défaut, 200 au maximum) et cursor (le next_cursor de la page précédente). Le numéro de téléphone de l'acheteur n'est jamais renvoyé.
| Champ | Signification |
|---|---|
id | L'identifiant du message, le même que message_id dans la réponse d'envoi. |
order_id | La commande. |
event | La clé du modèle pour les messages envoyés via l'API, ou l'événement de l'addon (received, confirmed, shipped, delivery_failed, desk_ready) pour les messages automatiques. |
source | api pour les messages envoyés via l'API, auto pour les messages automatiques de l'addon. |
status | queued, sending, sent, delivered, read, failed ou skipped. |
language | ar ou fr. |
template_name | Le nom du modèle chez Meta. |
error_title | La raison de l'échec ou du saut du message, ou null. |
refunded | true quand le crédit a été rendu. |
billing | charged une fois le message facturé par WhatsApp, free une fois le crédit rendu, null tant que WhatsApp n'a pas signalé le résultat. |
created_at | La date de mise en file du message. |
Un message qui échoue, qui n'est pas délivré après 30 jours, ou qui est délivré sans facturation par WhatsApp récupère son crédit une fois : refunded passe à true et billing devient free. Un message facturé par WhatsApp est fixé à charged.