Aller au contenu

Envoyer un message

Envoyez des messages via l'API SMSBAT à l'aide du point de terminaison /bat/messagelist.

Point de terminaison

POST /bat/messagelist

Structure de la demande

Le corps de la requête est un tableau JSON d'objets de message :

{
  "messages": [
    {
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Your message text",
      "customerMessageId": "your-internal-id",
      "ttl": 3600
    }
  ]
}

Paramètres

Paramètres requis

Paramètre Tapez Descriptif
de chaîne ID d'expéditeur alphanumérique
à chaîne Numéro de téléphone du destinataire au format E.164 (par exemple +380XXXXXXXXX)
type chaîne Type de message : sms, viber_promo, viber_trans, viber_carousel, viber_survey, viber_otp, rcs, flashcall
texte chaîne Contenu du message (obligatoire pour la plupart des types, facultatif pour certains)

Paramètres facultatifs

Paramètre Tapez Descriptif
customerMessageId chaîne Votre identifiant interne pour le suivi
ttl entier Durée de vie en secondes
messageDonnées objet Configuration spécifique au type (varie selon le type de message)

Authentification

Choisissez l'une des trois méthodes d'authentification :

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -H "X-Authorization-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "@:your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

Réponse

Réponse réussie

{
  "messagelistId": 123456,
  "messages": [
    {
      "messageId": "abc123def456",
      "status": "accepted",
      "parts": 1,
      "customerMessageId": "your-internal-id",
      "to": "+380XXXXXXXXX"
    }
  ]
}

Champs de réponse

Champ Tapez Descriptif
messagelistId entier Identifiant unique de la liste de messages
messageId chaîne Identifiant unique pour chaque message
statut chaîne Statut du message : accepté, rejeté, échec
pièces entier Nombre de parties du message (pour SMS)
customerMessageId chaîne Votre identifiant interne (si fourni)
à chaîne Numéro de téléphone du destinataire

Types de messages

SMS

SMS simples :

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "sms",
  "text": "Your SMS message text"
}

Promo Viber

Messages promotionnels avec rich media :

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_promo",
  "text": "Check out our new product!",
  "messageData": {
    "image": "https://example.com/image.jpg",
    "button": {
      "text": "View Product",
      "url": "https://example.com/product"
    }
  }
}

Viber Transactionnel

Notifications de transactions :

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_trans",
  "text": "Your order #12345 has been confirmed"
}

Viber OTP

Notifications de mot de passe uniques :

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_otp",
  "messageData": {
    "code": "123456",
    "validity": 300
  }
}

Gestion des erreurs

Codes d'état HTTP

Codes Descriptif
200 Demande réussie
400 Requête incorrecte – paramètres invalides
401 Non autorisé - échec de l'authentification
429 Trop de requêtes – limite de débit dépassée
500 Erreur de serveur interne

Réponse d'erreur

{
  "error": {
    "code": "INVALID_RECIPIENT",
    "message": "Invalid phone number format"
  }
}

meilleures pratiques

Format du numéro de téléphone

Utilisez toujours le format E.164 pour les numéros de téléphone :

  • ✅ Correct : +380XXXXXXXXX
  • ❌ Incorrect : 380XXXXXXXXX, 0XXXXXXXXX

Texte du message

  • Gardez les SMS sous 160 caractères pour éviter plusieurs parties
  • Utilisez l'encodage UTF-8 pour les caractères internationaux
  • Testez les caractères spéciaux avant l'envoi groupé

TTL (durée de vie)

  • Définir le TTL approprié pour les messages urgents
  • Messages OTP : 300 à 600 secondes (5 à 10 minutes)
  • Messages promotionnels : 3 600 à 86 400 secondes (1 à 24 heures)

ID du message client

  • Utilisez des identifiants uniques pour chaque message
  • Aide au suivi et au débogage
  • Utile pour établir une corrélation avec les enregistrements de votre système

Limites de taux

Contactez votre gestionnaire de compte pour obtenir des informations sur :

  • Messages par seconde
  • Messages par jour
  • Connexions simultanées

Prochaines étapes