SMS transactionnels – spécification (Advanced API)

Attention

Il est strictement interdit d'utiliser les SMS transactionnels à des fins promotionnelles ou marketing. Ils doivent servir uniquement à des fins de notification, en tant que notification SMS.

Note

Si vous souhaitez utiliser une route transactionnelle pour envoyer une notification groupée, veuillez contacter notre support. Nous pouvons autoriser cette option pour un motif légitime.

URL de l'API

URL utilisée pour envoyer les requêtes HTTP :

https://portal.bulkgate.com/api/2.0/advanced/transactional

Note

Si la requête n'atteint pas sa destination, répétez-la sur le serveur de secours backup1.bulkgate.com.

Méthodes HTTP prises en charge

POST - application/json

POST /api/2.0/advanced/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json

Tableau des paramètres

NOM DU PARAMÈTRE	VALEUR	OBLIGATOIRE	VALEUR PAR DÉFAUT
application_id	Identifiant de l'application	Oui	-
application_token	Jeton d'authentification de l'application	Oui	-
number	Numéro du destinataire ou tableau de numéros de destinataires - Valeur number	Oui ou `admin`	-
admin	Numéro de l'administrateur BulkGate qui reçoit la notification. Plus d'informations	Oui ou `number`	-
text	Texte du message SMS (max. 612 caractères, ou 268 caractères si Unicode est utilisé), encodage UTF-8. Il est possible d'ajouter au modèle des variables provenant du tableau `variables` (autre paramètre) `Hello <first_name> <last_name> ....`	Oui	-
variables	Tableau associatif pour ajouter des variables au texte, par ex. : `{"first_name": "John", "last_name": "Doe"}`	Non	`[]`
channel	Canaux alternatifs. Les canaux sont essayés en cascade, dans l'ordre dans lequel vous les indiquez dans l'objet : si nous ne parvenons pas à délivrer votre message par le premier canal, le suivant de la liste est utilisé. Le SMS n'est pas ajouté automatiquement ; si vous le souhaitez comme dernier recours, incluez l'objet `sms` dans la cascade. Si aucun canal n'est indiqué, le message est envoyé par SMS.	Non	Objet SMS
country	Indiquez les numéros des destinataires au format international (avec préfixe, par ex. `420`) ou ajoutez le code pays au format ISO 3166-1 alpha-2 (`777777777` + `CZ` = `420777777777`). Voir l'exemple de requête avec le pays. Si la valeur est `null`, le fuseau horaire que vous avez défini est utilisé pour compléter l'information	Non	`null`
schedule	Planifiez la date et l'heure d'envoi au format timestamp Unix, ou ISO 8601.	Non	Maintenant
duplicates_check	Choisissez `on` pour éviter l'envoi de messages en double au même numéro de téléphone. Les messages au texte identique envoyés au même numéro dans un intervalle de moins de 5 minutes seront supprimés. Avec `off`, aucun doublon n'est supprimé.	Non	`off`
tag	Libellé du message permettant à l'utilisateur de le retrouver ultérieurement.	Non	-

Valeur `number`

La valeur number peut s'écrire comme suit :

Tableau de numéros de téléphone

[ "420777777777", "420888888888", "420999999999" ]

Canaux

L'objet channel détermine par quels canaux et dans quel ordre le message est envoyé. L'ordre des clés dans votre requête correspond à l'ordre de la cascade et le SMS n'y est pas ajouté automatiquement - voir Cascade de canaux.

CLÉ	OBJET DU CANAL
`sms`	SMS
`viber`	Viber – transactionnel
`rcs`	RCS
`whatsapp`	WhatsApp

Exemple de requête

POST /api/2.0/advanced/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": ["777777777", "777777778"], "text": "example text <first_name>", "variables": {"first_name": "John"}, "country": "cz", "schedule": "2023-08-14T18:30:00-01:00", "channel": { "whatsapp": { "sender": "420777777777", "expiration": 300, "message": { "text": "text" } }, "rcs": { "sender": "BulkGate", "expiration": 300, "message": { "text": "text" } }, "viber": { "sender": "BulkGate", "expiration": 100 }, "sms": { "sender_id": "gText", "sender_id_value": "Mr. Sender", "unicode": true } } }

Réponse

En cas de succès :

{ "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 2, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0, "duplicity_message": 0 } }, "response": [ { "status": "scheduled", "message_id": "transactional-64afe5f28ffc2-0", "part_id": [ "transactional-64afe5f28ffc2-0" ], "number": "420777777777", "channel": "viber" }, { "status": "scheduled", "message_id": "transactional-64afe5f28ffc2-1", "part_id": [ "transactional-64afe5f28ffc2-1" ], "number": "420777777778", "channel": "viber" } ] } }

Où :

part_ID est le tableau des ID des parties du message long d'origine, qui a été découpé parce qu'il dépassait la limite de 160 caractères d'un message unique. Plus d'informations ici.

En cas d'erreur :

{ "type": "invalid_phone_number", "code": 400, "error": "Invalid phone number", "detail": null }

{ "type": "unknown_identity", "code": 401, "error": "Unknown identity / unauthorized / empty application_id", "detail": null }

Où :

type et error (description de l'erreur) figurent dans le tableau des types d'erreurs
code correspond au code d'erreur HTTP
detail contient des informations complémentaires sur l'erreur

Consultez tous les types d'erreurs de la Simple API et de l'Advanced API ici.

Cette page vous a-t-elle été utile ?

Demander à l'IA Copié