Aller au contenu

Guide de l'API RESTful SMSBAT

Guide complet de l'API SMSBAT RESTful – tout ce que vous devez savoir.

Dernière mise à jour : 29 août 2025

L'API SMSBAT RESTful vous permet d'envoyer différents types de messages : Viber-carrousel, Viber-survey, Viber-promo (images, vidéo), discussions professionnelles Viber, messages OTP (Viber OTP, Flash Call) et leurs variantes de secours.

Remarque : Il s'agit de l'API HTTP unifiée pour la messagerie sortante. Si vous avez besoin d'intégrations avec des robots entrants (Viber Bot / Telegram Bot), veuillez vous référer à l'API Cascade.

1. Protocole

  • Protocole : HTTPS
  • Request Body : objet JSON contenant un tableau de « messages ».
  • Méthodes :
  • GET pour récupérer des données (état du message, solde, etc.)
  • POST pour créer des objets (par exemple, lancer une diffusion/envoi)
  • PATCH pour modifier les objets

2. Autorisation

Nous proposons plusieurs méthodes d'autorisation pour votre commodité : - Authentification HTTP Basic (identifiant et mot de passe depuis votre tableau de bord). - En-tête HTTP personnalisé X-Authorization-Key contenant un jeton API. - Champ de mot de passe d'authentification de base HTTP contenant le jeton API (passez @ comme identifiant).

Le Jeton API peut être généré dans le tableau de bord sous Profil utilisateur.

Exemples de requêtes

Avec authentification de base : 

curl -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist \
  --user user:password

Avec X-Authorization-Key : 

curl -H "X-Authorization-Key: <token>" \
  -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist

3. Envoi de messages

Dans la plateforme SMSBAT, tout envoi de message (même un seul message) est considéré comme un « Broadcast » (liste de messages).

Point de terminaison - Méthode : POST - URL : https://api.smsbat.com/bat/messagelist - En-têtes : Content-Type : application/json

Structure de base de la charge utile : 

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "text": "Check out our new products!",
      "type": "viber_carousel",
      "ttl": 300,
      "messageData": { ... }
    }
  ]
}

Champs obligatoires pour chaque objet de message :

  • from : nom alpha de l'expéditeur vérifié.
  • à : Numéro de téléphone du destinataire (format E.164).
  • type : énumération du type de message.
  • text : Texte principal du message (facultatif si le type ne nécessite pas de texte).

Valeurs type prises en charge : - sms - viber_service (ou viber_trans) - viber_promo - viber_carrousel - viber_survey - viber_otp - viber_session - flashcall_callback - appel flash

Champs communs facultatifs :

  • customerMessageId : ID de chaîne dans votre propre système (utilisé pour le suivi des rappels). Doit être unique par message.
  • dtSend : Date/heure ISO8601 de l'expédition future programmée.
  • dtExpire : Date/Heure ISO8601 du délai de livraison.
  • ttl : Durée de vie en secondes. (Si dtExpire n'est pas fourni, l'API calcule le mappage des valeurs par défaut à partir du type).

TTL par défaut (secondes) :

  • sms - 86400 (24h)
  • viber_trans / viber_service - 345600
  • viber_promo - 604800
  • viber_session - 604800

4. Routage de secours (en cascade)

Vous pouvez spécifier une file d'attente de secours pour garantir la remise des messages en cas d'échec ou d'expiration du canal principal.

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380500505051",
      "text": "test message",
      "type": "viber_service",
      "ttl": 60,
      "fallbacks": [
        {
          "from": "ALPHANAME",
          "to": "380936670003",
          "text": "test sms fallback message2",
          "type": "sms"
        }
      ]
    }
  ]
}
Les replis se déclenchent lorsque le fournisseur rejette le message principal ou lorsque la durée de vie expire.

5. Présentation des types de messages et des données de message

Les types de messages complexes nécessitent des configurations supplémentaires injectées dans la propriété messageData.

5.1 Promotion Viber (viber_promo)

Image uniquement 

"messageData":{
  "img":"https://domain.com/image.png"
}

Texte + Bouton 

"messageData":{
  "buttonText":"Save Now",
  "buttonAction":"https://help.smsbat.com"
}

Image + Texte + Bouton Combine img, buttonText et buttonAction.

Charge utile vidéo : 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}
(Vous pouvez également combiner les propriétés vidéo avec buttonText et buttonAction).

5.2 Viber Transactionnel/Service (viber_trans, viber_service)

Si vous disposez d'un modèle approuvé contenant un fichier joint : 

"messageData": {
  "fileUrl": "https://domain.com/receipt.pdf",
  "fileName": "Receipt.pdf",
  "fileType": "pdf"
}

Nécessite un tableau carousel.items dans messageData.

Limites : - Longueur des articles : entre 2 et 5 articles - Titre : 2 à 38 caractères - imageUrl : taille recommandée JPEG/PNG 215x185

"messageData": {
  "carousel": {
    "items": [
      {
        "title": "50% Off Shoes!",
        "imageUrl": "https://domain.com/image1.png",
        "primaryButton": { "label": "Shop", "actionUrl": "..." },
        "secondaryButton": { "label": "Details", "actionUrl": "..." }
      }
    ]
  }
}

5.4 Enquête/Liste Viber (viber_survey)

Crée un sondage interactif dans la vue de discussion. 

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}
La propriété « text » du message fait office de titre de l'enquête (85 caractères maximum). Vous pouvez transmettre entre 2 et 5 options, chacune contenant au maximum 50 caractères.

5.5 Viber OTP (viber_otp)

Utilise des modèles Viber localisés préenregistrés à l’échelle mondiale. 

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}
Les paramètres du modèle (pin, business_platform_name) sont strictement sensibles à la casse. L'API prend en charge diverses variantes de langage de code ISO (EN, ES, RU, TR, UK, etc.).

5.6 Appel Flash (« flashcall »)

Les derniers chiffres du numéro à composer (le code généré) doivent être transmis via le paramètre text. Si « texte » est omis, le code est randomisé et vous devez l'extraire du corps de réponse synchrone 200 OK de l'API (« messages/texte »).

{
  "from": "FLASHCALL",
  "to": "380500000000",
  "type": "flashcall",
  "text": "340"
}