## API-URL URL, an die HTTP-Anfragen gesendet werden: ```url https://portal.bulkgate.com/api/2.0/advanced/promotional ``` > [!NOTE] > Erreicht die Anfrage ihr Ziel nicht, wiederholen Sie sie auf dem [Backup-Server](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/backup-server/) `backup1.bulkgate.com`. ## Unterstützte HTTP-Methoden - `POST` - `application/json` ```http POST /api/2.0/advanced/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` ## Parametertabelle | PARAMETERNAME | WERT | PFLICHT | STANDARDWERT | |:------------------|:----------------------------------------------------------------|:--------------------------------------------------:|:------------------------------------------:| | application_id | [Anwendungs-ID](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-verwaltung/) | **Ja** | - | | application_token | [Anwendungstoken](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-tokens/) | **Ja** | - | | number | Array der Empfänger – [Wert number](#wert-number) | **Ja** oder `admins` oder `groups` | - | | groups | Array der Gruppennummern im BulkGate-Adressbuch. [Mehr Informationen](https://www.bulkgate.com/de/dokumentation/advanced-api/advanced-promotional-versand-an-gruppen-aus-dem-adressbuch/) | **Ja** oder `number` oder `admins` | - | | admins | Array der Nummern von BulkGate-Administratoren, die Benachrichtigungen erhalten. [Mehr Informationen](https://www.bulkgate.com/de/dokumentation/advanced-api/advanced-promotional-nachrichten-an-administratoren/) | **Ja** oder `number` oder `groups` | - | | text | Text der SMS-Nachricht (max. 612 Zeichen bzw. 268 Zeichen bei aktiviertem Unicode), Kodierung UTF-8 | **Ja**, wenn `number` als Array von Nummern angegeben ist oder der Parameter `groups` bzw. `admin` verwendet wird | - | | channel | Alternative Kanäle. Die Kanäle werden kaskadenartig in der Reihenfolge versucht, in der Sie sie im Objekt aufführen – kann die Nachricht über den ersten Kanal nicht zugestellt werden, wird der nächste in der Liste verwendet. SMS wird **nicht** automatisch angehängt; soll sie als letzte Ausweichmöglichkeit dienen, nehmen Sie das Objekt `sms` in die Kaskade auf. Ist gar kein Kanal angegeben, wird die Nachricht als SMS gesendet. | Nein | [SMS-Objekt](https://www.bulkgate.com/de/dokumentation/advanced-api/advanced-sms/) | | country | Geben Sie die Empfängernummern im internationalen Format an (mit Vorwahl, z. B. `44`) oder fügen Sie den [Ländercode](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) hinzu (`777777777` + `GB` = `44777777777`). Siehe das Beispiel zur Länderangabe. Ist der Wert **`null`**, wird die Angabe anhand der von Ihnen eingestellten Zeitzone ergänzt | Nein | `null` | | schedule | Planen Sie Datum und Uhrzeit des Versands als [Unix-Zeitstempel](https://en.wikipedia.org/wiki/Unix_time) oder im Format [ISO 8601.](https://en.wikipedia.org/wiki/ISO_8601) Siehe Beispiele unten | Nein | Sofort | | duplicates_check | Mit **`same_text`** verhindern Sie, dass doppelte Nachrichten an dieselbe Telefonnummer gesendet werden. Mit **`same_number`** unterbinden Sie das Senden einer Nachricht mit gleichem oder anderem Text an dieselbe Nummer. Bei **`null`** werden keine Duplikate entfernt. Duplikate werden **nur innerhalb eines einzelnen Batches** entfernt, nicht über mehrere Anfragen hinweg. | Nein | `null` | | tag | Label der Nachricht, über das Sie sie später wiederfinden. | Nein | - | ### Wert `number` Der Wert number kann auf zwei Arten angegeben werden: - Array von Telefonnummern ```json [ "420777777777", "420888888888", "420999999999" ] ``` - Assoziatives Array mit dem Schema `number`, `text` und `variables`, wobei nur der Parameter `number` Pflicht ist. Ist `number` nicht ausgefüllt, wird die Nachricht übersprungen. ```json [ {"number": "420777777777", "text": "test1 ", "variables": {"a": 5}}, {"number": "420888888888", "text": "test2 ", "variables": {"b": 5}}, {"number": "420999999999", "text": "test3 ", "variables": {"c": 3, "d": "abc"}} ] ``` Variablen aus dem Array `variables` können Sie in die Vorlage des Parameters `text` einfügen. ## Kanäle Das Objekt `channel` legt fest, über welche Kanäle und in welcher Reihenfolge die Nachricht gesendet wird. **Die Reihenfolge der Schlüssel in Ihrer Anfrage ist die Reihenfolge der Kaskade**, und SMS wird nicht automatisch angehängt – siehe [Kanalkaskade](https://www.bulkgate.com/de/dokumentation/advanced-api/advanced-kaskade/). | SCHLÜSSEL | KANALOBJEKT | |:-------------|:---------------------------------------------------------------| | `sms` | [SMS](https://www.bulkgate.com/de/dokumentation/advanced-api/advanced-sms/) | | `viber` | [Viber – Werbung](https://www.bulkgate.com/de/dokumentation/advanced-api/advanced-viber-werbung/) | | `rcs` | [RCS](https://www.bulkgate.com/de/dokumentation/advanced-api/advanced-rcs/) | | `whatsapp` | [WhatsApp](https://www.bulkgate.com/de/dokumentation/advanced-api/advanced-whatsapp/) | ## Anfragebeispiele **Beispiel einer vollständigen Anfrage:** ```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: Die Zukunft der mobilen Kommunikation für Unternehmen", "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": "Zu 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: Die Zukunft der mobilen Kommunikation für Unternehmen*\n\nHaben Sie sich schon einmal gewünscht, in einer SMS mehr als nur Text zu senden, etwa ein hochauflösendes Bild oder eine interaktive Schaltfläche? Oder hätten Sie gern eine Lesebestätigung, um sicherzugehen, dass Ihre Nachricht angekommen ist? Rich Communication Services (RCS) revolutionieren die Kommunikation von Unternehmen, verbessern das Messaging-Erlebnis und überwinden diese Einschränkungen." }, "sms": { "sender_id": "gText", "sender_id_value": "Lt-Hagan", "unicode": true, "text": "RCS: Die Zukunft der mobilen Kommunikation für Unternehmen" } } } ``` **Beispiel einer Anfrage, bei der die Empfänger als Array von Nummern angegeben werden und die Zeit als Unix-Zeitstempel geplant wird:** ```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" } ``` ## Antwort **Bei Erfolg:** ```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" } ] } } ``` Dabei gilt: - **part_ID** ist das Array der IDs der Teile einer ursprünglich langen Nachricht, die aufgeteilt wurde, weil sie das Limit von 160 Zeichen für eine einzelne Nachricht überschritt. Mehr Informationen [hier](https://www.bulkgate.com/de/hilfe-center/sms/nachrichtenverkettung/). **Bei einem Fehler:** ```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 } ``` Dabei gilt: - **type** und **error** (Beschreibung des Fehlers) finden Sie in der [Tabelle der Fehlertypen](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-fehlertypen/) - **code** ist der HTTP-Fehlercode - **detail** enthält zusätzliche Informationen zum Fehler Alle Fehlertypen für die Simple API und die Advanced API finden Sie [hier](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-fehlertypen/).