Modelli

Gestisci i modelli usati da un account: modelli e-mail, intestazioni e modelli DLT per SMS, numero e modelli WhatsApp. Per leggerli serve l’ambito di invio del canale o templates:manage; per modificarli serve una chiave Owner o Admin con templates:manage.


Modelli e-mail

I modelli e-mail dell’account appartengono al suo spazio di lavoro predefinito, dove si trovano i messaggi dell’API e dove li elenca la dashboard. Un modello creato tramite API è HTML con segnaposto {{name}} compilati durante un invio. Un modello progettato nell’editor della dashboard può essere letto, usato per inviare ed eliminato, ma non sostituito, mantenendo coerenti HTML e progetto.

MetodoPercorsoFunzione
GET/external/v1/templatesModelli dal più recente, senza il relativo HTML
GET/external/v1/templates/{id}Un modello con il relativo HTML e le variabili previste
POST/external/v1/templatesCrea un modello da HTML: 201
PUT/external/v1/templates/{id}Sostituisce un modello creato da HTML: nome, oggetto e HTML
DELETE/external/v1/templates/{id}Elimina un modello: 204; non viene più elencato né usato per inviare
  • Nome
    name
    Tipo
    string
    Descrizione

    Obbligatorio: il nome del modello, al massimo 255 caratteri. Si applica anche la convalida standard dei nomi di Oblic; la sola lunghezza non basta.

  • Nome
    subject
    Tipo
    string
    Descrizione

    L’oggetto usato da un’e-mail inviata con il modello quando l’invio non ne specifica uno, al massimo 1,023 caratteri, con segnaposto propri. Un oggetto omesso o vuoto è salvato come null; gli spazi iniziali e finali di un oggetto non vuoto vengono rimossi.

  • Nome
    html
    Tipo
    string
    Descrizione

    Obbligatorio: l’HTML, salvato così come fornito, al massimo 65,535 byte UTF-8. I valori delle variabili vengono sottoposti a escape HTML quando l’invio compila i segnaposto; ciò non sanifica né isola in una sandbox l’HTML del modello.

Creare un modello

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 Creato

{
  "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
}
  • Un segnaposto è {{name}}: lettere e cifre ASCII, _, ., - e spazi solo all’interno del nome, al massimo 64 caratteri. variables elenca quelli presenti nell’oggetto e nell’HTML ignorando maiuscole e minuscole, nell’ordine e con la grafia della prima comparsa.
  • kind è html per un modello creato tramite API e designed per uno creato nell’editor della dashboard. Se il modello non ha un oggetto, forniscilo con l’invio; il tipo non sostituisce il controllo dell’oggetto restituito.
  • Le menzioni della dashboard, come @unsubscribe o @organizationName, vengono compilate solo da campagne e automazioni per ciascun destinatario. L’invio con un modello che ne contiene una viene rifiutato.
  • L’elenco usa cursor e limit per la paginazione: 25 elementi per pagina per impostazione predefinita, da 1 a 100, come descritto in Paginazione. Tratta il cursore restituito come un valore opaco.
RifiutocdQuando
400TEMPLATE_TOO_LARGEL’HTML supera 65,535 byte
404TEMPLATE_NOT_FOUNDL’account non ha un modello con quell’ID
409TEMPLATE_DESIGNEDSostituzione di un modello progettato nell’editor della dashboard

Intestazioni e modelli SMS

Un SMS usa un’intestazione DLT e corrisponde a un modello di contenuto DLT dell’entità DLT configurata di Cunomial. Entrambi vengono prima registrati su una piattaforma DLT e poi annotati qui per poterli associare a un invio SMS. Annotarli qui non li registra presso DLT. Nella risposta dell’account SMS, keepsRegistry e available descrivono l’autorizzazione e la disponibilità del registro configurato, non una promessa di consegna.

Vengono elencati solo i modelli approvati del registro; possono apparire anche modelli approvati non attivi. Un invio richiede inoltre un modello attivo e gli altri controlli descritti in Messaggi.

MetodoPercorsoFunzione
GET/external/v1/sms/accountLimiti dell’account, invii del mese e tipi di messaggio consentiti
GET/external/v1/sms/sendersIntestazioni proprie dell’account, [{"senderId": …, "isDefault": …}]
PUT/external/v1/sms/senders/{senderId}Aggiunge un’intestazione di sei lettere o sei cifre; {"isDefault": true} la rende predefinita
DELETE/external/v1/sms/senders/{senderId}Elimina un’intestazione non usata da alcun modello: 204
GET/external/v1/sms/templatesI modelli dell’account, poi quelli condivisi dall’account principale
POST/external/v1/sms/templatesAggiunge un modello: 201
PUT/external/v1/sms/templates/{id}Modifica un modello fornito per intero
DELETE/external/v1/sms/templates/{id}Elimina un modello: 204
PUT/external/v1/sms/templates/{id}/sharingConsente l’invio a nessuno, a tutti o ai sottoaccount indicati
  • Nome
    templateId
    Tipo
    string
    Descrizione

    Obbligatorio: l’ID DLT del modello, fino a 32 cifre.

  • Nome
    senderId
    Tipo
    string
    Descrizione

    Obbligatorio: un’intestazione dell’account. Un modello promozionale usa un’intestazione di sei cifre, gli altri una di sei lettere.

  • Nome
    name
    Tipo
    string
    Descrizione

    Obbligatorio: un nome a scelta, al massimo 80 caratteri.

  • Nome
    body
    Tipo
    string
    Descrizione

    Obbligatorio: il testo registrato su DLT, al massimo 2,000 caratteri, con ogni variabile come {#var#}, fino a 30 variabili.

  • Nome
    variableKeys
    Tipo
    string[]
    Descrizione

    Un nome per ciascuna variabile, in ordine, come ["otp", "minutes"]. Se omesso o vuoto, vengono usati i nomi posizionali da 1 a n. Se specificati, i nomi devono essere univoci e contenere lettere o cifre ASCII o _, da 1 a 30 caratteri ciascuno; il loro numero deve coincidere con quello delle variabili.

  • Nome
    type
    Tipo
    string
    Descrizione

    Obbligatorio: il tipo DLT, transactional, service_implicit, service_explicit o promotional.

  • Nome
    unicode
    Tipo
    boolean
    Descrizione

    Indica se il testo è Unicode; false per impostazione predefinita.

  • Nome
    active
    Tipo
    boolean
    Descrizione

    Indica se l’invio è consentito; true per impostazione predefinita.

Aggiungere un modello

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"
  }'
  • Solo gli account per cui Oblic registra SMS aggiungono e modificano intestazioni e modelli; gli altri ricevono 403 REGISTRY_NOT_ALLOWED e usano i modelli condivisi con loro.
  • La condivisione accetta {"scope": "none" | "all" | "selected", "accounts": […]}, al massimo 1,000 valori externalId di sottoaccount per selected. Ogni account indicato deve appartenere al principale. Una selezione vuota non condivide con alcun sottoaccount.
  • La selezione predefinita di un’intestazione viene impostata con ogni PUT: senza "isDefault": true l’intestazione non è predefinita. Impostarne una come predefinita rimuove questo stato dalla precedente dell’account.
RifiutocdQuando
400INVALID_TEMPLATEL’intestazione non corrisponde al tipo, ci sono più di 30 variabili o variableKeys non assegna un nome a ciascuna esattamente una volta
403REGISTRY_NOT_ALLOWEDL’account non registra SMS propri
404TEMPLATE_NOT_FOUND, SENDER_NOT_FOUND, ACCOUNT_NOT_FOUNDModello, intestazione o sottoaccount inesistente
409TEMPLATE_EXISTSUn modello con quell’ID DLT è già registrato
409SENDER_IN_USEEliminazione di un’intestazione usata da modelli
422SENDER_NOT_ALLOWEDL’intestazione non appartiene all’account
422MESSAGE_TYPE_NOT_ENABLEDIl tipo del modello non è tra quelli inviati da Oblic: messageTypes dell’account, solo service_implicit per impostazione predefinita

Numero e modelli WhatsApp

Un messaggio WhatsApp viene inviato dal numero WhatsApp Business collegato dell’account, usando un modello approvato da Meta.

MetodoPercorsoFunzione
POST/external/v1/whatsapp/connectionCollega il numero o sostituisce quello collegato
GET/external/v1/whatsapp/connectionIl numero collegato; 404 WHATSAPP_NOT_CONNECTED se assente
DELETE/external/v1/whatsapp/connectionLo scollega: 204
GET/external/v1/whatsapp/templatesI modelli con la revisione di Meta per ciascuno
POST/external/v1/whatsapp/templatesInvia un modello a Meta per la revisione: 201
GET/external/v1/whatsapp/recipients/{number}Cosa può inviare ora l’account a un numero

Il collegamento usa il risultato di Embedded Signup eseguito con l’app Meta di Oblic: code, phoneNumberId, wabaId, facoltativamente businessId e il pin a sei cifre con cui è registrato il numero. Lo status della risposta è INTEGRATED quando ogni passaggio è confermato; un collegamento interrotto resta PENDING. Riprova con dati di registrazione validi; un codice usato o scaduto non è garantito che funzioni di nuovo. Se Meta rifiuta un passaggio, la risposta è 502 con il relativo codice, come WHATSAPP_REGISTER_REFUSED, senza restituire il corpo grezzo della risposta.

  • Nome
    name
    Tipo
    string
    Descrizione

    Obbligatorio: lettere ASCII minuscole, cifre e _, come order_shipped. Il nome esteso da Oblic, qualificato per account e lingua, deve avere al massimo 100 caratteri; il superamento viene rifiutato prima di chiamare Meta. Per inviare usa il name restituito, senza supporre che il nome breve immesso sia quello salvato da Meta.

  • Nome
    language
    Tipo
    string
    Descrizione

    Lingua del modello: due lettere ASCII minuscole, facoltativamente _ e due lettere ASCII maiuscole, come en, hi o en_US; en se omessa. Un nome può avere un modello per lingua; ripetere nome e lingua crea un conflitto.

  • Nome
    category
    Tipo
    string
    Descrizione

    Obbligatorio: MARKETING, UTILITY o AUTHENTICATION.

  • Nome
    components
    Tipo
    object[]
    Descrizione

    Obbligatorio: intestazione, corpo, piè di pagina e pulsanti del modello, nel formato Meta, con esempi delle variabili.

Inviare un modello in revisione

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"]] }
      }
    ]
  }'
  • Lo status di un modello è lo stato di revisione salvato da Meta, per esempio PENDING, APPROVED o REJECTED; rejectionReason può essere assente. 201 significa inviato per revisione, non approvato. Si possono inviare solo modelli APPROVED. Non è promesso un termine per completare la revisione.
  • Un destinatario restituisce number, optedOut, quando e come (optedOutAt, optOutSource), lastInboundAt e sessionOpenUntil: la finestra di 24 ore dall’ultimo messaggio in entrata. optedOut riguarda il marketing, non tutti i messaggi. Senza cronologia in entrata, lastInboundAt e sessionOpenUntil sono null. Un timestamp di sessione da solo non garantisce che un invio sia accettato: restano validi gli altri controlli.
RifiutocdQuando
409TEMPLATE_EXISTSL’account ha un modello con quel nome in quella lingua
422WHATSAPP_NOT_CONNECTEDInvio di un modello in revisione senza un numero collegato
422TEMPLATE_NAME_TOO_LONGIl nome è troppo lungo per Meta
422TEMPLATE_REFUSEDMeta ha rifiutato il modello; rifiuto generico localizzato, non il testo grezzo della risposta di Meta
422INVALID_NUMBERIl numero del destinatario non è in formato internazionale
502WHATSAPP_CODE_REFUSED, WHATSAPP_SUBSCRIBE_REFUSED, WHATSAPP_REGISTER_REFUSEDMeta ha rifiutato un passaggio del collegamento del numero
503WHATSAPP_UNAVAILABLEMeta non era raggiungibile durante un passaggio del collegamento
Questa pagina è stata utile?