Vorlagen
Verwalten Sie die Vorlagen eines Kontos: E-Mail-Vorlagen, SMS-Absenderkennungen und DLT-Vorlagen sowie die WhatsApp-Nummer und Vorlagen. Zum Lesen ist die Sendeberechtigung des Kanals oder templates:manage erforderlich; Änderungen benötigen einen Owner- oder Admin-Schlüssel mit templates:manage.
Diese /external/v1-Routen verwenden API-Schlüssel. OAuth-Zugriffstoken verwenden API v2; ein vorhandenes Beispiel belegt nicht, dass eine Bereitstellung für diese Version eingerichtet ist.
E-Mail-Vorlagen
Die E-Mail-Vorlagen des Kontos gehören zu seinem Standardarbeitsbereich, in dem auch die API-Nachrichten liegen und das Dashboard sie auflistet. Eine per API erstellte Vorlage enthält HTML mit {{name}}-Platzhaltern, die beim Senden ausgefüllt werden. Eine im Dashboard-Editor entworfene Vorlage kann gelesen, zum Senden verwendet und gelöscht, aber nicht ersetzt werden, damit HTML und Entwurf zusammenpassen.
| Methode | Pfad | Funktion |
|---|---|---|
GET | /external/v1/templates | Vorlagen, neueste zuerst, ohne ihr HTML |
GET | /external/v1/templates/{id} | Eine Vorlage mit ihrem HTML und den erwarteten Variablen |
POST | /external/v1/templates | Erstellt eine Vorlage aus HTML: 201 |
PUT | /external/v1/templates/{id} | Ersetzt eine aus HTML erstellte Vorlage: Name, Betreff und HTML |
DELETE | /external/v1/templates/{id} | Löscht eine Vorlage: 204; sie wird nicht mehr aufgelistet oder zum Senden verwendet |
- Name
name- Typ
- string
- Beschreibung
Erforderlich: der Vorlagenname, höchstens 255 Zeichen. Auch die standardmäßige Namensprüfung von Oblic gilt; die richtige Länge allein reicht nicht aus.
- Name
subject- Typ
- string
- Beschreibung
Der Betreff für eine mit dieser Vorlage gesendete E-Mail, wenn beim Senden keiner angegeben wird; höchstens 1,023 Zeichen, mit eigenen Platzhaltern. Ein fehlender oder leerer Betreff wird als
nullgespeichert; bei einem nicht leeren Betreff werden führende und nachfolgende Leerzeichen entfernt.
- Name
html- Typ
- string
- Beschreibung
Erforderlich: das unverändert gespeicherte HTML, höchstens 65,535 UTF-8-Bytes. Variablenwerte werden beim Ausfüllen der Platzhalter für HTML maskiert; dadurch wird das HTML der Vorlage weder bereinigt noch in einer Sandbox isoliert.
Vorlage erstellen
curl -X POST https://api.oblic.app/external/v1/templates \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"name": "Order shipped",
"subject": "Order {{order_id}} is on its way",
"html": "<p>Hi {{first_name}}, your order {{order_id}} has shipped.</p>"
}'
201 Erstellt
{
"status": "success",
"data": {
"id": "TEM000R7ZM4Q2VXH00",
"name": "Order shipped",
"subject": "Order {{order_id}} is on its way",
"kind": "html",
"variables": ["order_id", "first_name"],
"html": "<p>Hi {{first_name}}, your order {{order_id}} has shipped.</p>",
"createdAt": "2026-10-24T09:30:00Z",
"updatedAt": "2026-10-24T09:30:00Z"
},
"errors": null
}
- Ein Platzhalter ist
{{name}}: ASCII-Buchstaben und -Ziffern,_,.,-und Leerzeichen nur innerhalb des Namens, höchstens 64 Zeichen.variableslistet die Platzhalter aus Betreff und HTML ohne Unterscheidung der Großschreibung in Reihenfolge und Schreibweise ihres ersten Auftretens auf. kindisthtmlbei einer per API erstellten unddesignedbei einer im Dashboard-Editor entworfenen Vorlage. Hat eine Vorlage keinen Betreff, geben Sie beim Senden einen an; ihr Typ ersetzt nicht die Prüfung des zurückgegebenen Betreffs.- Dashboard-Erwähnungen wie
@unsubscribeoder@organizationNamewerden nur durch Kampagnen und Automatisierungen je Empfänger ausgefüllt. Das Senden mit einer Vorlage, die eine solche enthält, wird abgelehnt. - Die Liste wird mit
cursorundlimitpaginiert: standardmäßig 25 pro Seite, zwischen 1 und 100, wie unter Paginierung beschrieben. Behandeln Sie den zurückgegebenen Cursor als undurchsichtigen Wert.
| Ablehnung | cd | Bedingung |
|---|---|---|
| 400 | TEMPLATE_TOO_LARGE | Das HTML überschreitet 65,535 Bytes |
| 404 | TEMPLATE_NOT_FOUND | Das Konto hat keine Vorlage mit dieser ID |
| 409 | TEMPLATE_DESIGNED | Ersetzen einer im Dashboard-Editor entworfenen Vorlage |
SMS-Absenderkennungen und Vorlagen
Eine SMS verwendet eine DLT-Absenderkennung und entspricht einer DLT-Inhaltsvorlage unter der konfigurierten DLT-Entität von Cunomial. Beides wird zuerst auf einer DLT-Plattform registriert und hier anschließend erfasst, um einem SMS-Versand zugeordnet werden zu können. Die Erfassung hier ist keine DLT-Registrierung. keepsRegistry und available in der SMS-Kontoantwort beschreiben die konfigurierte Registrierungsberechtigung und Verfügbarkeit, keine Zustellungszusage.
Nur genehmigte Registrierungsvorlagen werden aufgelistet; inaktive genehmigte Vorlagen können weiterhin erscheinen. Zum Senden sind außerdem eine aktive Vorlage und die weiteren unter Nachrichten beschriebenen Prüfungen erforderlich.
| Methode | Pfad | Funktion |
|---|---|---|
GET | /external/v1/sms/account | Kontolimits, Versandmenge dieses Monats und erlaubte Nachrichtentypen |
GET | /external/v1/sms/senders | Die eigenen Absenderkennungen des Kontos, [{"senderId": …, "isDefault": …}] |
PUT | /external/v1/sms/senders/{senderId} | Fügt eine Absenderkennung aus sechs Buchstaben oder sechs Ziffern hinzu; {"isDefault": true} macht sie zum Standard |
DELETE | /external/v1/sms/senders/{senderId} | Löscht eine von keiner Vorlage verwendete Absenderkennung: 204 |
GET | /external/v1/sms/templates | Eigene Vorlagen des Kontos, danach die vom übergeordneten Konto freigegebenen |
POST | /external/v1/sms/templates | Fügt eine Vorlage hinzu: 201 |
PUT | /external/v1/sms/templates/{id} | Ändert eine vollständig angegebene Vorlage |
DELETE | /external/v1/sms/templates/{id} | Löscht eine Vorlage: 204 |
PUT | /external/v1/sms/templates/{id}/sharing | Erlaubt keinem, allen oder den benannten Unterkonten, damit zu senden |
- Name
templateId- Typ
- string
- Beschreibung
Erforderlich: die DLT-ID der Vorlage, bis zu 32 Ziffern.
- Name
senderId- Typ
- string
- Beschreibung
Erforderlich: eine Absenderkennung des Kontos. Werbevorlagen verwenden eine Kennung aus sechs Ziffern, die anderen eine aus sechs Buchstaben.
- Name
name- Typ
- string
- Beschreibung
Erforderlich: ein selbst gewählter Name mit höchstens 80 Zeichen.
- Name
body- Typ
- string
- Beschreibung
Erforderlich: der bei DLT registrierte Text mit höchstens 2,000 Zeichen und jeder Variablen als
{#var#}, höchstens 30 Variablen.
- Name
variableKeys- Typ
- string[]
- Beschreibung
Ein Name je Variable in der richtigen Reihenfolge, etwa
["otp", "minutes"]. Bei fehlender oder leerer Liste werden die Positionsnamen1bisnverwendet. Angegebene Namen müssen eindeutig sein und aus ASCII-Buchstaben, -Ziffern oder_bestehen, jeweils 1 bis 30 Zeichen; ihre Anzahl muss der Variablenanzahl entsprechen.
- Name
type- Typ
- string
- Beschreibung
Erforderlich: der DLT-Typ
transactional,service_implicit,service_explicitoderpromotional.
- Name
unicode- Typ
- boolean
- Beschreibung
Ob der Text Unicode verwendet; standardmäßig
false.
- Name
active- Typ
- boolean
- Beschreibung
Ob die Vorlage gesendet werden darf; standardmäßig
true.
Vorlage hinzufügen
curl -X POST https://api.oblic.app/external/v1/sms/templates \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"templateId": "1107161234567890123",
"senderId": "EXMPLE",
"name": "Sign-in code",
"body": "Your Example code is {#var#}. It is valid for {#var#} minutes.",
"variableKeys": ["code", "minutes"],
"type": "service_implicit"
}'
- Nur Konten, für die Oblic SMS registriert, fügen Absenderkennungen und Vorlagen hinzu oder ändern sie; andere Konten erhalten
403 REGISTRY_NOT_ALLOWEDund verwenden die für sie freigegebenen Vorlagen. - Die Freigabe akzeptiert
{"scope": "none" | "all" | "selected", "accounts": […]}, höchstens 1,000 Unterkonto-externalId-Werte fürselected. Jedes benannte Konto muss zum übergeordneten Konto gehören. Eine leere Auswahl gibt die Vorlage für kein Unterkonto frei. - Die Standardmarkierung einer Absenderkennung wird mit jedem
PUTgesetzt: Ohne"isDefault": trueist sie nicht der Standard. Wird eine Kennung zum Standard, verliert die vorherige Standardkennung des Kontos diese Markierung.
| Ablehnung | cd | Bedingung |
|---|---|---|
| 400 | INVALID_TEMPLATE | Die Absenderkennung passt nicht zum Typ, es gibt mehr als 30 Variablen oder variableKeys benennt nicht jede genau einmal |
| 403 | REGISTRY_NOT_ALLOWED | Das Konto registriert keine eigenen SMS |
| 404 | TEMPLATE_NOT_FOUND, SENDER_NOT_FOUND, ACCOUNT_NOT_FOUND | Vorlage, Absenderkennung oder Unterkonto nicht vorhanden |
| 409 | TEMPLATE_EXISTS | Eine Vorlage mit dieser DLT-ID ist bereits registriert |
| 409 | SENDER_IN_USE | Löschen einer von Vorlagen verwendeten Absenderkennung |
| 422 | SENDER_NOT_ALLOWED | Die Absenderkennung gehört nicht zum Konto |
| 422 | MESSAGE_TYPE_NOT_ENABLED | Der Vorlagentyp gehört nicht zu den von Oblic gesendeten Typen: messageTypes des Kontos, standardmäßig nur service_implicit |
WhatsApp-Nummer und Vorlagen
Eine WhatsApp-Nachricht wird von der verbundenen WhatsApp-Business-Nummer des Kontos mit einer von Meta genehmigten Vorlage gesendet.
| Methode | Pfad | Funktion |
|---|---|---|
POST | /external/v1/whatsapp/connection | Verbindet die Nummer oder ersetzt die verbundene Nummer |
GET | /external/v1/whatsapp/connection | Die verbundene Nummer; ohne Nummer 404 WHATSAPP_NOT_CONNECTED |
DELETE | /external/v1/whatsapp/connection | Trennt sie: 204 |
GET | /external/v1/whatsapp/templates | Vorlagen mit dem jeweiligen Prüfstatus von Meta |
POST | /external/v1/whatsapp/templates | Reicht eine Vorlage bei Meta zur Prüfung ein: 201 |
GET | /external/v1/whatsapp/recipients/{number} | Was das Konto derzeit an eine Nummer senden darf |
Die Verbindung verwendet das Ergebnis von Embedded Signup mit der Meta-App von Oblic: code, phoneNumberId, wabaId, optional businessId und die sechsstellige pin, mit der die Nummer registriert wird. Der status der Antwort ist INTEGRATED, sobald alle Verbindungsschritte bestätigt sind; eine unterbrochene Verbindung bleibt PENDING. Wiederholen Sie den Vorgang mit gültigen Registrierungsdaten; ein verbrauchter oder abgelaufener Code funktioniert nicht garantiert erneut. Lehnt Meta einen Schritt ab, lautet die Antwort 502 mit dem betreffenden Code, etwa WHATSAPP_REGISTER_REFUSED, ohne den unbearbeiteten Antwortinhalt zurückzugeben.
- Name
name- Typ
- string
- Beschreibung
Erforderlich: ASCII-Kleinbuchstaben, Ziffern und
_, etwaorder_shipped. Der von Oblic um Konto und Sprache erweiterte Name darf höchstens 100 Zeichen haben; eine Überschreitung wird vor dem Meta-Aufruf abgelehnt. Verwenden Sie beim Senden den zurückgegebenenname, statt anzunehmen, dass die kurze Eingabe dem bei Meta gespeicherten Namen entspricht.
- Name
language- Typ
- string
- Beschreibung
Vorlagensprache: zwei ASCII-Kleinbuchstaben, optional
_und zwei ASCII-Großbuchstaben, etwaen,hioderen_US; ohne Angabeen. Ein Name kann je Sprache eine Vorlage haben; derselbe Name mit derselben Sprache ist ein Konflikt.
- Name
category- Typ
- string
- Beschreibung
Erforderlich:
MARKETING,UTILITYoderAUTHENTICATION.
- Name
components- Typ
- object[]
- Beschreibung
Erforderlich: Kopf, Nachrichtentext, Fuß und Schaltflächen der Vorlage im Meta-Format, mit Beispielen für ihre Variablen.
Vorlage einreichen
curl -X POST https://api.oblic.app/external/v1/whatsapp/templates \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"name": "order_shipped",
"language": "en",
"category": "UTILITY",
"components": [
{
"type": "BODY",
"text": "Hi {{1}}, your order {{2}} has shipped.",
"example": { "body_text": [["Asha", "1042"]] }
}
]
}'
- Der
statuseiner Vorlage ist der gespeicherte Prüfstatus von Meta, etwaPENDING,APPROVEDoderREJECTED;rejectionReasonkann fehlen.201bedeutet eingereicht, nicht genehmigt. NurAPPROVED-Vorlagen können gesendet werden. Eine Frist für den Prüfungsabschluss wird nicht zugesagt. - Ein Empfänger liefert
number,optedOut, Zeitpunkt und Art (optedOutAt,optOutSource),lastInboundAtundsessionOpenUntil: das 24-Stunden-Fenster seit seiner letzten eingehenden Nachricht.optedOutbetrifft Marketing, nicht jede Nachricht. Ohne eingehenden Verlauf sindlastInboundAtundsessionOpenUntilgleichnull. Ein Sitzungszeitstempel allein garantiert nicht die Annahme eines Versands; die anderen Prüfungen gelten weiterhin.
| Ablehnung | cd | Bedingung |
|---|---|---|
| 409 | TEMPLATE_EXISTS | Das Konto hat eine Vorlage mit diesem Namen in dieser Sprache |
| 422 | WHATSAPP_NOT_CONNECTED | Einreichen einer Vorlage ohne verbundene Nummer |
| 422 | TEMPLATE_NAME_TOO_LONG | Der Name ist für Meta zu lang |
| 422 | TEMPLATE_REFUSED | Meta hat die Vorlage abgelehnt; allgemeine lokalisierte Ablehnung statt unbearbeitetem Antworttext von Meta |
| 422 | INVALID_NUMBER | Die Empfängernummer hat kein internationales Format |
| 502 | WHATSAPP_CODE_REFUSED, WHATSAPP_SUBSCRIBE_REFUSED, WHATSAPP_REGISTER_REFUSED | Meta hat einen Schritt beim Verbinden der Nummer abgelehnt |
| 503 | WHATSAPP_UNAVAILABLE | Meta war während eines Verbindungsschritts nicht erreichbar |