## URL de l'API
URL utilisée pour l'envoi des requêtes HTTP :
```url
https://portal.bulkgate.com/api/2.0/advanced/promotional
```
> [!NOTE]
> Si la requête n'atteint pas sa destination, renvoyez-la sur le [serveur de secours](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/serveur-de-secours/) `backup1.bulkgate.com`.
## Méthodes HTTP prises en charge
- `POST` - `application/json`
```http
POST /api/2.0/advanced/promotional 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 | [ID d'application](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/administration-api/) | **Oui** | - |
| application_token | [Jeton d'application](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/tokens-d-api/) | **Oui** | - |
| number | Tableau des destinataires - [Valeur number](#valeur-number) | **Oui** ou `admins` ou `groups` | - |
| groups | Tableau des numéros de groupes du carnet d'adresses BulkGate. [Plus d'informations](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-promotional-envoi-aux-groupes-du-carnet-d-adresses/) | **Oui** ou `number` ou `admins` | - |
| admins | Tableau des numéros des administrateurs BulkGate qui reçoivent les notifications. [Plus d'informations](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-promotional-envoi-aux-administrateurs/) | **Oui** ou `number` ou `groups` | - |
| text | Texte du message SMS (612 caractères max., ou 268 caractères si l'Unicode est activé), encodage UTF-8 | **Oui**, si `number` est un tableau de numéros ou si le paramètre `groups` ou `admin` est utilisé | - |
| 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 à 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 dernière solution de repli, incluez l'objet `sms` dans la cascade. Si aucun canal n'est indiqué, le message est envoyé par SMS. | Non | [Objet SMS](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-sms/) |
| country | Indiquez les numéros des destinataires au format international (avec l'indicatif, p. ex. `420`) ou ajoutez le [code pays](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`777777777` + `CZ` = `420777777777`). Voir l'exemple de requête avec pays. Si la valeur est **`null`**, le fuseau horaire que vous avez défini sert à compléter l'information | Non | `null` |
| schedule | Planification de la date et de l'heure d'envoi au format [timestamp Unix](https://en.wikipedia.org/wiki/Unix_time) ou [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Voir les exemples ci-dessous | Non | Maintenant |
| duplicates_check | Choisissez **`same_text`** pour éviter l'envoi de messages en double au même numéro de téléphone. Avec **`same_number`**, vous empêchez l'envoi au même numéro d'un message au texte identique comme différent. Avec **`null`**, aucun doublon n'est supprimé. Les doublons sont supprimés **uniquement au sein d'un même lot**, et non d'une requête à l'autre. | Non | `null` |
| tag | Libellé du message permettant à l'utilisateur de le retrouver ultérieurement. | Non | - |
### Valeur `number`
La valeur number peut être écrite de deux façons :
- Tableau de numéros de téléphone
```json
[
"420777777777",
"420888888888",
"420999999999"
]
```
- Tableau associatif avec la structure `number`, `text` et `variables`, dont le seul paramètre obligatoire est `number`. Si `number` n'est pas renseigné, le message est ignoré.
```json
[
{"number": "420777777777", "text": "test1 ", "variables": {"a": 5}},
{"number": "420888888888", "text": "test2 ", "variables": {"b": 5}},
{"number": "420999999999", "text": "test3 ", "variables": {"c": 3, "d": "abc"}}
]
```
Vous pouvez insérer les variables du tableau `variables` dans le modèle du paramètre `text`.
## Canaux
L'objet `channel` détermine par quels canaux le message est envoyé et dans quel ordre. **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](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-cascade/).
| CLÉ | OBJET DE CANAL |
|:-------------|:---------------------------------------------------------------|
| `sms` | [SMS](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-sms/) |
| `viber` | [Viber – promotionnel](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-viber-promotionnel/) |
| `rcs` | [RCS](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-rcs/) |
| `whatsapp` | [WhatsApp](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-whatsapp/) |
## Exemples de requêtes
**Exemple de requête complète :**
```http-json
POST /api/2.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
{
"application_id": 451,
"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
"number": [
{"number": "420777777777", "text": "test1 ", "variables": {"a": 5}},
{"number": "420888888888", "text": "test2 ", "variables": {"b": 5}},
{"number": "420999999999", "text": "test3 ", "variables": {"c": 3, "d": "abc"}}
],
"groups": [1, 2],
"admins": [1, 4],
"text": "RCS : l'avenir de la messagerie mobile pour les entreprises",
"country": "cz",
"schedule": "2018-05-14T18:30:00-01:00",
"channel": {
"whatsapp": {
"sender": "420777777777",
"expiration": 300,
"message": {
"text": "text"
}
},
"rcs": {
"sender": "BulkGate",
"expiration": 300,
"message": {
"text": "text"
}
},
"viber": {
"sender": "Lt. Hagan",
"expiration": 100,
"button": {
"caption": "Aller sur BulkGate",
"url": "https://www.bulkgate.com/en/blog/rcs-the-future-of-mobile-messaging-for-businesses/"
},
"image": "https://www.bulkgate.com/assets/illustrations/rcs-rich-communication-services.jpg",
"text": "*RCS : l'avenir de la messagerie mobile pour les entreprises*\n\nVous avez déjà souhaité envoyer plus que du simple texte dans un SMS, comme une image haute résolution ou un bouton interactif ? Ou peut-être auriez-vous aimé recevoir un accusé de lecture pour confirmer que votre message est bien arrivé ? Les Rich Communication Services (RCS) sont là pour révolutionner la communication des entreprises, améliorer votre expérience de messagerie et dépasser ces limites."
},
"sms": {
"sender_id": "gText",
"sender_id_value": "Lt-Hagan",
"unicode": true,
"text": "RCS : l'avenir de la messagerie mobile pour les entreprises"
}
}
}
```
**Exemple de requête indiquant les destinataires sous forme de tableau de numéros et planifiant l'envoi via un timestamp Unix :**
```http-json
POST /api/2.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
{
"application_id": 451,
"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
"number": [
"420777777777",
"420888888888",
"420999999999"
],
"text": "Hello, ",
"schedule": "1526992636"
}
```
## Réponse
**En cas de succès :**
```json
{
"data":{
"total":{
"status":{
"sent":0,
"accepted":0,
"scheduled":2,
"error":0,
"blacklisted":0,
"invalid_number":1,
"invalid_sender":0
}
},
"response":[
{
"status":"scheduled",
"sms_id":"idyrcmdd-0",
"part_id":[
"idyrcmdd-0_1",
"idyrcmdd-0"
],
"number":"420777777777",
"channel":"sms"
},
{
"status":"scheduled",
"sms_id":"idyrcmdd-1",
"part_id":[
"idyrcmdd-1_1",
"idyrcmdd-1"
],
"number":"420888888888",
"channel":"sms"
},
{
"status":"invalid_number",
"code":400,
"error":"Invalid phone number",
"detail":null,
"number":"420999999999",
"channel":"sms"
}
]
}
}
```
Où :
- **part_ID** est le tableau des ID des parties du message long d'origine, scindé parce qu'il dépassait la limite de 160 caractères d'un message unique. Plus d'informations [ici](https://www.bulkgate.com/fr/centre-d-aide/sms/concatenation-des-messages/).
**En cas d'erreur :**
```json
{
"type": "invalid_phone_number",
"code": 400,
"error": "Invalid phone number",
"detail": null
}
```
```json
{
"type": "unknown_identity",
"code": 401,
"error": "Unknown identity / unauthorized / empty application_id",
"detail": null
}
```
Où :
- **type** et **error** (description de l'erreur) sont décrits dans le [tableau des types d'erreurs](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/types-d-erreurs-api/)
- **code** représente le code d'erreur HTTP
- **detail** contient des informations complémentaires sur l'erreur
Tous les types d'erreurs de la Simple API et de l'Advanced API sont disponibles [ici](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/types-d-erreurs-api/).