Senden
Senden
Senden Sie eine SMS-Vorlage an einen oder mehrere Benutzer
URL
https://sms.api.engagelab.cc/v1/send
https://sms.api.engagelab.cc/v1/send
Diesen Codeblock im schwebenden Fenster anzeigen
HTTP-Anfragemethode
POST
POST
Diesen Codeblock im schwebenden Fenster anzeigen
Content-Type
Content-Type: application/json;charset=utf-8
Content-Type: application/json;charset=utf-8
Diesen Codeblock im schwebenden Fenster anzeigen
Anfrage-Header
| Header | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| Authorization | String | ja | Basic base64(sms_user:sms_key) |
Beschreibung der Body-Parameter
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| from | string | nein | Der Absendername kann aus 3-11 Zeichen bestehen und darf nur englische Buchstaben und Zahlen enthalten. Standard ist leer, Anzeige je nach tatsächlichem Effekt. |
| to | array | ja | Liste der Mobiltelefonnummern, maximal 1000 pro Liste. |
| body | object | ja | Einstellungen für den SMS-Inhalt |
| template_id | int | ja | ID der Vorlage |
| msg_type | int | nein | SMS-Typ, 2 steht für internationale SMS, Standardwert ist 2. |
| label_id | int | nein | SMS-Kennzeichnung |
| vars | object | nein | Variablen. Bis zu 1MB |
| custom_args | object | nein | Optional vom Kunden angepasste Felder. Maximale Größe ist 1KB. |
| request_id | string | nein | ID dieser Sendeanfrage; maximal 128 Zeichen. |
Tipps:
- Vars werden für Variablenersetzung im Nachrichteninhalt verwendet. Das Format ist ein JSON-Objekt, z.B. {"varname": ["value1", "value2"]}, wobei varname die Variable im Nachrichtentext ist.
- Beispiel für den Nachrichtentext: Willkommen beim %sp% SMS-Dienst. Entsprechender vars-Wert: {"sp": "engagelab"}. Ergebnis der SMS-Inhaltsersetzung: Willkommen bei EngageLab SMS-Dienst.
- Jeder Wert in vars darf standardmäßig nicht länger als 16 Zeichen sein und wird als String formatiert. Variablen dürfen keine HTTP-Links enthalten (bei speziellen Anforderungen kontaktieren Sie bitte den Kundenservice).
- Das System ersetzt die Variablen in der SMS-Vorlage durch die Parameter in vars und alle Telefonnummern erhalten denselben ersetzten Inhalt.
- Die selbst definierten customer_args werden im Header eingebettet; die nachfolgenden SMSHook-Daten werden Ihnen zurückgesendet.
- Die request_id dient zur Vermeidung von mehrfachen Einreichungen und ist 1 Stunde lang gültig. Bei mehrfacher Einreichung innerhalb einer Stunde wird das Ergebnis der letzten Anfrage zurückgegeben.
Beispielanfrage
curl -X POST "https://sms.api.engagelab.cc/v1/send"
--header "Authorization: Basic <<YOUR_SMS_KEY_HERE>>"
--header "Content-Type: application/json"
--data '{
"from": "xxxx",
"to": ["+12673800456", "+12673800455"],
"request_id":"123",
"body":{
"template_id": 2336,
"label_id": 231,
"vars": {
"week": "Dienstag"
}
}
}'
curl -X POST "https://sms.api.engagelab.cc/v1/send"
--header "Authorization: Basic <<YOUR_SMS_KEY_HERE>>"
--header "Content-Type: application/json"
--data '{
"from": "xxxx",
"to": ["+12673800456", "+12673800455"],
"request_id":"123",
"body":{
"template_id": 2336,
"label_id": 231,
"vars": {
"week": "Dienstag"
}
}
}'
Diesen Codeblock im schwebenden Fenster anzeigen
Beschreibung der Rückgabewerte
| Parameter | Beschreibung |
|---|---|
| success_count | Anzahl erfolgreicher Übertragungen |
| sms_ids | Liste der erfolgreich gesendeten SMS-IDs |
| failed_count | Anzahl der fehlgeschlagenen Sendungen |
| failed_items | Liste der fehlgeschlagenen Telefonnummern und Fehlerursachen |
| phone | Telefonnummer |
| message | Grund des Fehlschlags |
| request_id | ID dieser Sendeanfrage |
| custom_args | Vom Kunden optional angepasste Felder |
Beispiel für Rückgabewerte
Erfolgreiche Antwort
HTTP Status: 200
// Beispiel für erfolgreiche Rückgabewerte
{
"sms_ids": ["1458113381893_15_3_11_1ainnq$+12673800456", "1458113381893_15_3_11_1ainnq$+12673800456"],
"request_id": "123"
}
// Beispiel für teilweise erfolgreiche Rückgabewerte
{
"code": 41031,
"message": "partial success",
"success_count": 1,
"sms_ids": ["1458113381893_15_3_11_1ainnq$+12673800456"],
"request_id": "123",
"failed_count": 1,
"failed_items": [
{
"phone": "1233",
"message": "Ungültiges Telefonnummernformat"
}
]
}
// Beispiel für erfolgreiche Rückgabewerte
{
"sms_ids": ["1458113381893_15_3_11_1ainnq$+12673800456", "1458113381893_15_3_11_1ainnq$+12673800456"],
"request_id": "123"
}
// Beispiel für teilweise erfolgreiche Rückgabewerte
{
"code": 41031,
"message": "partial success",
"success_count": 1,
"sms_ids": ["1458113381893_15_3_11_1ainnq$+12673800456"],
"request_id": "123",
"failed_count": 1,
"failed_items": [
{
"phone": "1233",
"message": "Ungültiges Telefonnummernformat"
}
]
}
Diesen Codeblock im schwebenden Fenster anzeigen
Fehlerhafte Antwort
HTTP Status: 401
{
"code": 30000,
"message": "Nicht autorisiert."
}
{
"code": 30000,
"message": "Nicht autorisiert."
}
Diesen Codeblock im schwebenden Fenster anzeigen
Fehlerhafte Antwort
HTTP Status: 400
// Beispiel für fehlgeschlagene Rückgabe
{
"code": 32002,
"message": "Ungültiges Telefonnummernformat"
}
// Beispiel für fehlgeschlagene Rückgabe
{
"code": 32002,
"message": "Ungültiges Telefonnummernformat"
}
Diesen Codeblock im schwebenden Fenster anzeigen
