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.


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.

MethodePfadFunktion
GET/external/v1/templatesVorlagen, neueste zuerst, ohne ihr HTML
GET/external/v1/templates/{id}Eine Vorlage mit ihrem HTML und den erwarteten Variablen
POST/external/v1/templatesErstellt 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 null gespeichert; 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. variables listet die Platzhalter aus Betreff und HTML ohne Unterscheidung der Großschreibung in Reihenfolge und Schreibweise ihres ersten Auftretens auf.
  • kind ist html bei einer per API erstellten und designed bei 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 @unsubscribe oder @organizationName werden 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 cursor und limit paginiert: standardmäßig 25 pro Seite, zwischen 1 und 100, wie unter Paginierung beschrieben. Behandeln Sie den zurückgegebenen Cursor als undurchsichtigen Wert.
AblehnungcdBedingung
400TEMPLATE_TOO_LARGEDas HTML überschreitet 65,535 Bytes
404TEMPLATE_NOT_FOUNDDas Konto hat keine Vorlage mit dieser ID
409TEMPLATE_DESIGNEDErsetzen 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.

MethodePfadFunktion
GET/external/v1/sms/accountKontolimits, Versandmenge dieses Monats und erlaubte Nachrichtentypen
GET/external/v1/sms/sendersDie 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/templatesEigene Vorlagen des Kontos, danach die vom übergeordneten Konto freigegebenen
POST/external/v1/sms/templatesFü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}/sharingErlaubt 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 Positionsnamen 1 bis n verwendet. 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_explicit oder promotional.

  • 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_ALLOWED und verwenden die für sie freigegebenen Vorlagen.
  • Die Freigabe akzeptiert {"scope": "none" | "all" | "selected", "accounts": […]}, höchstens 1,000 Unterkonto-externalId-Werte für selected. 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 PUT gesetzt: Ohne "isDefault": true ist sie nicht der Standard. Wird eine Kennung zum Standard, verliert die vorherige Standardkennung des Kontos diese Markierung.
AblehnungcdBedingung
400INVALID_TEMPLATEDie Absenderkennung passt nicht zum Typ, es gibt mehr als 30 Variablen oder variableKeys benennt nicht jede genau einmal
403REGISTRY_NOT_ALLOWEDDas Konto registriert keine eigenen SMS
404TEMPLATE_NOT_FOUND, SENDER_NOT_FOUND, ACCOUNT_NOT_FOUNDVorlage, Absenderkennung oder Unterkonto nicht vorhanden
409TEMPLATE_EXISTSEine Vorlage mit dieser DLT-ID ist bereits registriert
409SENDER_IN_USELöschen einer von Vorlagen verwendeten Absenderkennung
422SENDER_NOT_ALLOWEDDie Absenderkennung gehört nicht zum Konto
422MESSAGE_TYPE_NOT_ENABLEDDer 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.

MethodePfadFunktion
POST/external/v1/whatsapp/connectionVerbindet die Nummer oder ersetzt die verbundene Nummer
GET/external/v1/whatsapp/connectionDie verbundene Nummer; ohne Nummer 404 WHATSAPP_NOT_CONNECTED
DELETE/external/v1/whatsapp/connectionTrennt sie: 204
GET/external/v1/whatsapp/templatesVorlagen mit dem jeweiligen Prüfstatus von Meta
POST/external/v1/whatsapp/templatesReicht 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 _, etwa order_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ückgegebenen name, 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, etwa en, hi oder en_US; ohne Angabe en. Ein Name kann je Sprache eine Vorlage haben; derselbe Name mit derselben Sprache ist ein Konflikt.

  • Name
    category
    Typ
    string
    Beschreibung

    Erforderlich: MARKETING, UTILITY oder AUTHENTICATION.

  • 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 status einer Vorlage ist der gespeicherte Prüfstatus von Meta, etwa PENDING, APPROVED oder REJECTED; rejectionReason kann fehlen. 201 bedeutet eingereicht, nicht genehmigt. Nur APPROVED-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), lastInboundAt und sessionOpenUntil: das 24-Stunden-Fenster seit seiner letzten eingehenden Nachricht. optedOut betrifft Marketing, nicht jede Nachricht. Ohne eingehenden Verlauf sind lastInboundAt und sessionOpenUntil gleich null. Ein Sitzungszeitstempel allein garantiert nicht die Annahme eines Versands; die anderen Prüfungen gelten weiterhin.
AblehnungcdBedingung
409TEMPLATE_EXISTSDas Konto hat eine Vorlage mit diesem Namen in dieser Sprache
422WHATSAPP_NOT_CONNECTEDEinreichen einer Vorlage ohne verbundene Nummer
422TEMPLATE_NAME_TOO_LONGDer Name ist für Meta zu lang
422TEMPLATE_REFUSEDMeta hat die Vorlage abgelehnt; allgemeine lokalisierte Ablehnung statt unbearbeitetem Antworttext von Meta
422INVALID_NUMBERDie Empfängernummer hat kein internationales Format
502WHATSAPP_CODE_REFUSED, WHATSAPP_SUBSCRIBE_REFUSED, WHATSAPP_REGISTER_REFUSEDMeta hat einen Schritt beim Verbinden der Nummer abgelehnt
503WHATSAPP_UNAVAILABLEMeta war während eines Verbindungsschritts nicht erreichbar
War diese Seite hilfreich?