Envoi de messages à l’aide de la REST API

Vous pouvez envoyer des messages depuis votre backend en temps réel à l’aide de deux endpoints Braze différents. Chacun a une forme de requête différente : l’un nécessite le contenu complet du message dans la requête ; l’autre nécessite un ID de Campaign et envoie le contenu défini dans le tableau de bord.

Cette approche est compatible avec tous les canaux de communication pris en charge par l’API (WhatsApp, e-mail, SMS, notifications push, Content Cards, webhooks, etc.).

Deux méthodes d’envoi

Pour obtenir tous les détails relatifs aux requêtes et aux réponses, consultez les références des endpoints Envoyer des messages immédiatement (API uniquement) et Envoyer des Campaigns à l’aide d’une réception/distribution déclenchée par l’API.

Option 1 : Envoyer avec le contenu du message dans la requête (/messages/send)

Utilisez cet endpoint lorsque vous souhaitez spécifier le contenu complet du message dans la requête API. Vous devez inclure un objet messages (par exemple, messages.whats_app, messages.email ou messages.sms). Vous pouvez omettre campaign_id pour envoyer sans suivi de Campaign, ou inclure un ID de Campaign API et message_variation_id dans chaque message afin de suivre les envois dans le tableau de bord (consultez la référence de l’endpoint pour plus de détails).

Requis : clé API avec la permission messages.send.

Important

Chaque destinataire dans external_user_ids doit déjà exister dans Braze. Pour créer des utilisateurs dans le cadre d’un envoi, utilisez d’abord /users/track, ou utilisez l’option 2 (Campaign déclenchée par l’API) à la place.

Exemple : modèle de message WhatsApp

1
2
3
POST YOUR_REST_ENDPOINT/messages/send
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "external_user_ids": ["user123"],
  "messages": {
    "whats_app": {
      "app_id": "YOUR_APP_ID",
      "subscription_group_id": "YOUR_WHATSAPP_SUBSCRIPTION_GROUP_ID",
      "message_type": "template_message",
      "message": {
        "template_name": "new_message_received",
        "template_language_code": "en_US"
      }
    }
  }
}

Pour obtenir la spécification complète de l’objet WhatsApp, consultez Objet WhatsApp.

Remarque

L’endpoint /messages/send ne prend en charge que les modèles WhatsApp avec des en-têtes TEXT ou IMAGE. Pour les types d’en-tête DOCUMENT, VIDEO ou autres types de médias, utilisez l’endpoint de Campaign déclenchée par l’API ou le tableau de bord de Braze.

Exemple : e-mail

1
2
3
4
5
6
7
8
9
10
11
{
  "external_user_ids": ["user123"],
  "messages": {
    "email": {
      "app_id": "YOUR_APP_ID",
      "subject": "Your order has shipped",
      "from": "[email protected]",
      "body": "<p>Your order #12345 is on its way.</p>"
    }
  }
}

Pour les autres canaux, consultez Objets d’envoi de messages.

Option 2 : Déclencher une Campaign avec du contenu dans le tableau de bord (/campaigns/trigger/send)

Utilisez cet endpoint lorsque le contenu du message est créé dans le tableau de bord de Braze (Campaign déclenchée par API). Vous envoyez un campaign_id requis et les destinataires ; vous n’envoyez pas d’objet messages.

Requis : clé API avec la permission campaigns.trigger.send.

Étape 1 : Créer une Campaign déclenchée par API

1. Dans le tableau de bord de Braze, accédez à Messaging > Campaigns.
2. Sélectionnez Create Campaign, puis API-Triggered Campaign (et non « API Campaign »).
3. Ajoutez votre canal de communication (WhatsApp, e-mail, SMS, etc.) et créez le contenu du message dans le tableau de bord.
4. Notez l’ID de Campaign (et l’ID d’envoi si vous utilisez plusieurs variantes de message). Vous les utiliserez dans la requête API.

Pour en savoir plus sur la création de Campaigns déclenchées par API, consultez Réception/distribution déclenchée par API.

Étape 2 : Déclencher la Campaign via l’API

Envoyez une requête POST à /campaigns/trigger/send avec campaign_id et recipients (ou broadcast/audience). N’incluez pas d’objet messages — le contenu provient de la Campaign.

1
2
3
POST YOUR_REST_ENDPOINT/campaigns/trigger/send
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5
6
7
8
{
  "campaign_id": "YOUR_CAMPAIGN_ID",
  "recipients": [
    {
      "external_user_id": "user123"
    }
  ]
}

Pour obtenir le corps complet de la requête (y compris trigger_properties, send_to_existing_only, attributes, etc.), consultez la référence de l’endpoint Envoyer des Campaigns à l’aide d’une réception/distribution déclenchée par l’API.

Vérifier votre intégration

1. Envoyez une requête en utilisant l’une des options ci-dessus, en indiquant votre propre ID utilisateur comme destinataire.
2. Confirmez que le message a bien été distribué.
3. Si vous utilisez l’option 2, vérifiez la Campaign dans le tableau de bord de Braze pour confirmer que l’envoi a bien été enregistré.

Considérations

• Utilisez les fonctionnalités de personnalisation de Braze pour adapter le contenu lorsque cela est possible.
• Assurez-vous que vos envois de messages sont conformes aux réglementations applicables et qu’ils incluent les options de désabonnement et les avis de confidentialité requis.
• Pour d’autres endpoints (planification, déclencheurs Canvas, etc.), consultez Endpoints d’envoi de messages.