Centre d'aide Compatibilité des API GMS

Compatibilité des API GMS

SMSBAT prend en charge une couche de compatibilité avec l’API GMS. Cela vous permet de migrer vos intégrations existantes conçues pour GMS directement vers SMSBAT sans avoir à modifier vos schémas de routage de messages, vos structures de charge utile ou vos écouteurs de rappel.

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/GMSMessage/send_message
Format de la demande : application/json
Authentification : Authentification HTTP de base (utilise vos informations d’identification API SMSBAT)

Paramètres de la requête

L’API de compatibilité GMS accepte un objet JSON avec les paramètres de niveau supérieur suivants :

Paramètre	Tapez	Obligatoire	Descriptif
`numéro_téléphone`	chaîne	Oui	Numéro de téléphone du destinataire au format international (par exemple, « 380501234567 »).
`balise`	chaîne	Oui	Nom de l’expéditeur enregistré / nom alpha.
`canaux`	tableau	Oui	Liste des chaînes à essayer, par ordre de priorité. Valeurs prises en charge : `viber`, `sms`, `push`. Par exemple, `["viber", "sms"]`.
`channel_options`	objet	Oui	Carte contenant les options pour chaque canal actif (voir ci-dessous).
`id_extra`	chaîne	Non	Votre identifiant de message interne côté client.
`callback_url`	chaîne	Non	URL du point de terminaison sur votre système pour recevoir des rappels d’état de livraison.
`code_division`	chaîne	Non	Identificateur de code de division facultatif (par défaut : « principal »).

Paramètres des options de chaîne

L’objet channel_options contient des configurations spécifiques au canal.

Utilisé lorsque « viber » est répertorié dans le tableau « canaux ».

Paramètre	Tapez	Obligatoire	Descriptif
`texte`	chaîne	Oui	Texte du corps du message.
`ttl`	entier	Oui	Durée de vie en secondes.
`img`	chaîne	Non	URL HTTPS publique de l’image à afficher.
`légende`	chaîne	Non	Étiquette de texte du bouton.
‘action’	chaîne	Non	URL de destination lorsque le bouton est cliqué.
`survey_options`	tableau	Non	Tableau de chaînes (2 à 5 éléments) à afficher comme options d’enquête.
`carrousel_items`	tableau	Non	Tableau d’objets slide à afficher sous forme de carrousel Viber (voir structure dans l’onglet).

Exemple de demande Viber :

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Hello from SMSBAT!",
      "ttl": 60,
      "img": "https://www.example.com/image.png",
      "caption": "Open",
      "action": "https://www.example.com"
    }
  }
}

Active la messagerie Viber avec un repli automatique des SMS si la livraison Viber échoue dans la durée de vie.

Exemple de demande de secours :

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber", "sms"],
  "channel_options": {
    "viber": {
      "text": "Your order is ready!",
      "ttl": 60,
      "caption": "Details",
      "action": "https://www.example.com/order"
    },
    "sms": {
      "text": "Your order is ready: https://www.example.com/order",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

Utilisé lorsque « sms » est répertorié dans le tableau « canaux ».

Paramètre	Tapez	Obligatoire	Descriptif
`texte`	chaîne	Oui	Texte du corps du message.
`nom_alpha`	chaîne	Oui	Nom alphabétique de l’expéditeur.
`ttl`	entier	Oui	Durée de vie en secondes.
`ctr`	booléen	Non	Activez le suivi des clics CTR sur les liens dans le texte (`true`/`false`).

Exemple de demande SMS :

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["sms"],
  "channel_options": {
    "sms": {
      "text": "Your verification code is 1234",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

Utilisé pour créer des sondages et des enquêtes Viber.

Warning

La configuration de l’enquête Viber doit avoir entre 2 et 5 options dans survey_options.

Exemple de demande d’enquête :

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Please rate our service:",
      "ttl": 60,
      "survey_options": [
        "Excellent",
        "Good",
        "Bad"
      ]
    }
  }
}

Utilisé pour envoyer des cartes de diapositives d’images glissantes. Chaque diapositive prend en charge l’image, le titre et les boutons.

Exemple de demande de carrousel :

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Choose an offer",
      "ttl": 60,
      "carousel_items": [
        {
          "title": "Offer 1",
          "image_url": "https://www.example.com/offer-1.png",
          "primary_label": "Open",
          "primary_url": "https://www.example.com/offer-1",
          "secondary_label": "More",
          "secondary_url": "https://www.example.com/offers"
        },
        {
          "title": "Offer 2",
          "image_url": "https://www.example.com/offer-2.png",
          "primary_label": "Open",
          "primary_url": "https://www.example.com/offer-2"
        }
      ]
    }
  }
}

Utilisé lorsque « push » est répertorié dans le tableau « channels ».

Paramètre	Tapez	Obligatoire	Descriptif
`titre`	chaîne	Oui	Texte du titre de la notification push.
`texte`	chaîne	Oui	Texte du corps du message.
`ttl`	entier	Oui	Durée de vie en secondes.
`img`	chaîne	Non	URL HTTPS publique de l’image à afficher.
`légende`	chaîne	Non	Étiquette de texte du bouton.
‘action’	chaîne	Non	URL de destination lorsque le bouton est cliqué.
`ctr`	booléen	Non	Activez le suivi des clics.

Exemple de demande push :

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["push"],
  "channel_options": {
    "push": {
      "title": "Order update",
      "text": "Your order is ready for pickup!",
      "ttl": 60,
      "img": "https://www.example.com/push.png",
      "caption": "Open",
      "action": "https://www.example.com/order",
      "ctr": false
    }
  }
}

Format de réponse

Le point de terminaison renvoie des réponses au format JSON avec un code d’état « HTTP 200 OK ».

Réponse réussie

{
  "MessageId": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "ErrorCode": null,
  "ErrorText": null
}

Réponses aux erreurs

Si la validation ou le traitement échoue, une réponse d’erreur avec un « ErrorCode » non nul et un « ErrorText » détaillé sera renvoyée.

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "This type of Message is not supported by the system"
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "There can be from 2 to 5 survey options."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 400,
  "ErrorText": "Cannot send to international number: alpha name 'ALPHA' is not registered."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 500,
  "ErrorText": "Internal server error."
}

Format de livraison du rappel

Si « callback_url » a été spécifié dans la demande, SMSBAT envoie des mises à jour de l’état de livraison sous forme de charge utile JSON POST à votre point de terminaison.

Exemple de demande de rappel

POST /your-callback-endpoint HTTP/1.1
Host: yoursystem.com
Content-Type: application/json

{
  "number": "380501234567",
  "time": 1719237600000,
  "status": 2,
  "substatus": 23,
  "hyber_status": 23033,
  "message_id": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "extra_id": "ORDER-12345",
  "sent_via": "viber",
  "matching_template_id": 0
}

Champs de rappel Description

Champ	Tapez	Descriptif
`numéro`	chaîne	Numéro de téléphone du destinataire.
`temps`	numéro	Horodatage de l’événement en millisecondes Unix.
`statut`	numéro	Identifiant de statut simplifié (voir tableau des codes de statut).
`sous-statut`	numéro	Identifiant de statut détaillé (voir tableau des codes de sous-statut).
`hyber_statut`	numéro	Code d’état interne SMSBAT détaillé (voir tableau Hyber Status).
`message_id`	chaîne	ID de message SMSBAT (GUID) généré lors de l’envoi.
`id_extra`	chaîne	ID côté client fourni dans la demande d’origine.
`envoyé_via`	chaîne	Canal qui a traité le message : `viber`, `sms` ou `rcs`.
`matching_template_id`	numéro	Statut de correspondance du modèle Viber (le cas échéant).

Mappages de statut

1. Statut simplifié (« statut »)

Codes	Signification
’1’	Message accepté ou en cours de livraison.
‘2’	Message délivré.
‘3’	Erreur de traitement ou de livraison.

2. Statut détaillé (« sous-statut »)

Codes	Signification
’12’	Accepté pour traitement.
‘23’	Livré.
‘24’	Vu/lu.
‘35’	Non livré dans le délai TTL (expiré).
‘36’	Erreur de livraison.

3. Type de canal (`sent_via`)

Chaîne	Descriptif
`vibreur`	Statut produit par la chaîne Viber.
`sms`	Statut produit par canal SMS.
`rcs`	Statut produit par la chaîne RCS.

4. Statut détaillé de SMSBAT (`hyber_status`)

Codes	Chaîne	Statut	Sous-statut	Signification
23033	`vibreur`	’2'	'23’	Message Viber envoyé.
24013	`vibreur`	’2'	'24’	Message Viber lu par le destinataire (Vu).
36013	`vibreur`	’3'	'36’	Erreur interne Viber.
36023	`vibreur`	’3'	'36’	ID de service Viber invalide ou indisponible.
36033	`vibreur`	’3'	'36’	Données de charge utile Viber invalides.
36037	`vibreur`	’3'	'36’	URL de l’image Viber trop longue.
36038	`vibreur`	’3'	'36’	URL de l’image Viber invalide.
36039	`vibreur`	’3'	'36’	Texte Viber trop long.
36044	`vibreur`	’3'	'36’	Texte Viber vide.
36053	`vibreur`	’3'	'36’	Type de message Viber non pris en charge.
36063	`vibreur`	’3'	'36’	Paramètres Viber invalides.
36073	`vibreur`	’3'	'36’	Expiration du délai du fournisseur Viber.
36083	`vibreur`	’3'	'36’	Expéditeur Viber bloqué par le destinataire.
36093	`vibreur`	’3'	'36’	Le destinataire n’est pas enregistré en tant qu’utilisateur Viber.
36103	`vibreur`	’3'	'36’	Aucun appareil Android/iOS prenant en charge Viber trouvé.
36113	`vibreur`	’3'	'36’	Adresse IP non autorisée pour l’envoi Viber.
36123	`vibreur`	’3'	'36’	Message Viber en double détecté.
36143	`vibreur`	’3'	'36’	Erreur de facturation Viber.
36153	`vibreur`	’3'	'36’	Message bloqué par la liste noire de la plateforme.
36163	`vibreur`	’3'	'36’	Erreur de traitement interne de la plateforme Viber.
36173	`vibreur`	’3'	'36’	Étiquette Viber erronée ou manquante.
36183	`vibreur`	’3'	'36’	Valeur TTL Viber invalide.
12011	`sms` / `rcs`	’1'	'12’	SMS/RCS acceptés.
36011	`sms` / `rcs`	’1'	'12’	SMS/RCS en route.
23011	`sms` / `rcs`	’2'	'23’	SMS/RCS délivrés.
35015	`sms` / `rcs`	’3'	'35’	SMS/RCS expiré (non livré dans le délai TTL).
36021	`sms` / `rcs`	’3'	'36’	Message SMS/RCS supprimé.
36031	`sms` / `rcs`	’3'	'36’	Les SMS/RCS ne peuvent pas être délivrés.
36041	`sms` / `rcs`	’3'	'36’	Statut de livraison SMS/RCS inconnu.
36051	`sms` / `rcs`	’3'	'36’	Message SMS/RCS rejeté.

Résultats de recherche

Compatibilité des API GMS

Paramètres de connexion

Paramètres de la requête

Paramètres des options de chaîne

Format de réponse

Réponse réussie

Réponses aux erreurs

Format de livraison du rappel

Exemple de demande de rappel

Champs de rappel Description

Mappages de statut

1. Statut simplifié (« statut »)

2. Statut détaillé (« sous-statut »)

3. Type de canal (sent_via)

4. Statut détaillé de SMSBAT (hyber_status)

3. Type de canal (`sent_via`)

4. Statut détaillé de SMSBAT (`hyber_status`)