Centre d'aide Compatibilité de l'API Messages

Compatibilité de l'API Messages

SMSBAT prend en charge une couche de compatibilité avec l’API Messagio. Cela vous permet de migrer vos intégrations Viber existantes conçues pour Messagio directement vers SMSBAT sans avoir à réécrire votre structure de charge utile ou à modifier la logique d’intégration.

Paramètres de connexion

Pour acheminer les requêtes via SMSBAT, mettez à jour l’URL de base et les informations d’authentification dans votre intégration :

URL de base : https://restapi.smsbat.com
Point de terminaison : POST /api/SendMessage
Format de la demande : application/x-www-form-urlencoded (Données du formulaire)

Authentification et informations d’identification

Les demandes sont authentifiées à l’aide de paramètres envoyés directement dans les données du formulaire du corps de la demande :

Paramètre	Tapez	Obligatoire	Descriptif
`utilisateur`	chaîne	Oui	Votre identifiant de compte SMSBAT ou votre identifiant utilisateur.
`signe`	chaîne	Oui	Secret API ou signature enregistrée pour le nom de l’expéditeur.
`de`	chaîne	Oui	Nom alphabétique de l’expéditeur enregistré.
`méthode_d'envoi`	chaîne	Oui	Type de canal. Utilisez « viber » pour les messages Viber Business réguliers ou « viber_otp » pour les modèles Viber OTP.
`téléphone`	chaîne	Oui	Numéro de téléphone du destinataire au format international (par exemple, « 380501234567 »).

Types de messages Viber

Choisissez un onglet ci-dessous pour afficher les paramètres spécifiques et demander des charges utiles pour différentes structures de messages Viber :

Envoie un simple message texte.

Paramètres supplémentaires :

Paramètre	Tapez	Obligatoire	Descriptif
`txt`	chaîne	Oui	Texte du message.

Exemple de charge utile de demande :

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hello+from+SMSBAT%21

Envoie un message texte avec un bouton d’appel à l’action interactif.

Paramètres supplémentaires :

Paramètre	Tapez	Obligatoire	Descriptif
`txt`	chaîne	Oui	Texte du message.
`bouton_text`	chaîne	Oui	Texte affiché sur le bouton.
`bouton_lien`	chaîne	Oui	URL de destination lorsque le bouton est cliqué.

Exemple de charge utile de demande :

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Check+our+latest+offers%21&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Envoie un fichier image public.

Paramètres supplémentaires :

Paramètre	Tapez	Obligatoire	Descriptif
`image_lien`	chaîne	Oui	URL HTTPS publique de l’image.
`txt`	chaîne	Non	Texte de légende facultatif à afficher sous l’image.

Exemple de charge utile de demande :

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png

Envoie une carte enrichie contenant du texte, une image et un bouton.

Paramètres supplémentaires :

Paramètre	Tapez	Obligatoire	Descriptif
`txt`	chaîne	Oui	Texte de légende.
`image_lien`	chaîne	Oui	URL HTTPS publique de l’image.
`bouton_text`	chaîne	Oui	Texte affiché sur le bouton.
`bouton_lien`	chaîne	Oui	URL de destination lorsque le bouton est cliqué.

Exemple de charge utile de demande :

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hot+deals+inside%21&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Envoie un fichier vidéo avec une légende de texte et des boutons d’action facultatifs.

Paramètres supplémentaires :

Paramètre	Tapez	Obligatoire	Descriptif
`vidéo.url`	chaîne	Oui	URL HTTPS publique du fichier vidéo.
`vidéo.thumbnail`	chaîne	Oui	URL HTTPS publique de l’image d’aperçu vidéo.
`vidéo.size_mb`	entier	Oui	Taille approximative du fichier vidéo en mégaoctets.
`vidéo.duration_sec`	entier	Oui	Durée de la vidéo en secondes.
`txt`	chaîne	Non	Texte de description facultatif.
`bouton_text`	chaîne	Non	Texte du bouton facultatif (peut servir de légende ou de lien).
`bouton_lien`	chaîne	Non	URL du lien du bouton facultatif.

Exemple de charge utile de demande :

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Watch+this+tutorial%21&video.url=https%3A%2F%2Fwww.example.com%2Fvideo.mp4&video.thumbnail=https%3A%2F%2Fwww.example.com%2Fvideo-thumbnail.png&video.size_mb=1&video.duration_sec=3&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Paramètres supplémentaires :

| Paramètre | Tapez | Obligatoire | Descriptif |
| :--- | :--- | :--- | :--- |
| `template.id` | chaîne | **Oui** | ID de modèle Viber OTP pré-approuvé. |
| `template.lang` | chaîne | **Oui** | Code de langue du modèle (par exemple, « en », « uk ). |
| `template.params.pin` | chaîne | **Oui** | La valeur de la broche OTP à injecter dans le modèle. |
| `template.params.business_platform_name` | chaîne | **Oui** | Espace réservé au nom de l’entreprise dans le modèle. |
| `template.params.code_validity_time` | chaîne | **Oui** | Période de validité du code PIN en minutes. |

**Exemple de charge utile de demande :**
```http
POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber_otp&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&template.id=otp_template_123&template.lang=en&template.params.pin=123456&template.params.business_platform_name=SMSBAT&template.params.code_validity_time=7
```

Envoie une carte de message interactive contenant plusieurs diapositives (cartes) que l’utilisateur peut parcourir.

Paramètres supplémentaires :

Paramètre	Tapez	Obligatoire	Descriptif
`txt`	chaîne	Oui	Texte du titre du carrousel.
`carrousel[N].title`	chaîne	Oui	Titre de la carte `N` (commençant à 0).
`carrousel[N].image_url`	chaîne	Oui	URL de l’image HTTPS publique de la carte « N ».
`carrousel[N].primary_label`	chaîne	Oui	Légende du bouton principal de la carte « N ».
`carrousel[N].primary_url`	chaîne	Oui	URL du lien du bouton principal de la carte « N ».
`carrousel[N].secondary_label`	chaîne	Non	Légende du bouton secondaire de la carte « N ».
`carrousel[N].secondary_url`	chaîne	Non	URL du lien du bouton secondaire de la carte « N ».

Exemple de charge utile de demande :

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Top+picks+for+you&carousel%5B0%5D.title=First+Offer&carousel%5B0%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-1.png&carousel%5B0%5D.primary_label=Open&carousel%5B0%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-1&carousel%5B0%5D.secondary_label=Details&carousel%5B0%5D.secondary_url=https%3A%2F%2Fwww.example.com%2Fitem-1%2Fdetails&carousel%5B1%5D.title=Second+Offer&carousel%5B1%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-2.png&carousel%5B1%5D.primary_label=Open&carousel%5B1%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-2

Envoie un message contenant un sondage interactif ou une question d’enquête.

Paramètres supplémentaires :

Paramètre	Tapez	Obligatoire	Descriptif
`txt`	chaîne	Oui	Texte de la question de l’enquête.
`survey_options[N]`	chaîne	Oui	Texte de l’option d’enquête pour l’élément « N » (index commençant à 0). Au moins 2 options sont requises.
`option_type`	entier	Oui	Type de sélecteur : `1` (RadioButtons) ou `2` (boutons normaux).

Exemple de charge utile de demande :

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Please+rate+our+service&survey_options%5B0%5D=Excellent&survey_options%5B1%5D=Good&survey_options%5B2%5D=Average&option_type=1

Format de réponse

Le point de terminaison de compatibilité de l’API Messagio renvoie les réponses au format XML avec un code d’état « HTTP 200 OK ».

Réponse acceptée (succès)

<response>
  <code>0</code>
  <tech_message>OK</tech_message>
  <msg_id phone="380501234567">MESSAGE_GUID</msg_id>
</response>

Réponses aux erreurs

Si la validation des paramètres de requête échoue ou si l’authentification échoue, la réponse renverra un code différent de zéro.

<response>
  <code>-1</code>
  <tech_message>PARAM ERROR (sign)</tech_message>
</response>

<response>
  <code>-2</code>
  <tech_message>ERROR(unauthorized)</tech_message>
</response>

Rappels

Les URL de rappel doivent être implémentées et hébergées sur votre plateforme. SMSBAT envoie des rappels HTTP pour mettre à jour votre système concernant les événements de livraison, les réponses à l’enquête et les réponses des utilisateurs.

1. Rappel de l’état de livraison

Envoyé lorsqu’un message change d’état (livré, lu, échoué).

Type de contenu : application/x-www-form-urlencoded
Méthode : POST

Formats de charge utile de demande :

Livré :
```
msg_id=MESSAGE_GUID&status=delivered
```

Vu/lu :

msg_id=MESSAGE_GUID&status=delivered&type=seen

Non livré/Échec :

msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Description des champs :

msg_id : ID de message unique (GUID) SMSBAT renvoyé dans la réponse SendMessage.
statut : résultat de la livraison (livré, non livré ou statut inconnu).
type : défini sur “vu” lorsque le message a été consulté par le destinataire.
status_extended : raison technique spécifique du statut non livré (par exemple VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE).

2. Rappel des réponses à l’enquête

Déclenché lorsqu’un utilisateur sélectionne une option de réponse dans un message Viber Survey.

Type de contenu : application/x-www-form-urlencoded
Méthode : POST

Format de charge utile de la demande :

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Rappel des messages utilisateur entrants

Déclenché lorsqu’un utilisateur renvoie une réponse SMS ou multimédia à votre service Viber Business.

Type de contenu : application/json
Méthode : POST

Format de charge utile de la demande :

{
  "msg_id": "INBOUND_MESSAGE_GUID",
  "text": "Hello, I have a question",
  "media": "https://example.com/user-attachment.png",
  "phone": "380501234567",
  "sender_bm_id": "12345"
}

Description des champs :

msg_id : L’ID de message unique généré pour la réponse entrante.
text : contenu texte envoyé par l’utilisateur (peut être null s’il a envoyé uniquement du média).
media : URL directe pour télécharger toutes les pièces jointes multimédia envoyées par l’utilisateur (peut être null s’il s’agit uniquement de texte).
« téléphone » : numéro de téléphone de l’expéditeur au format international.
sender_bm_id : l’identifiant de l’expéditeur Viber Business.