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.
Queste route /external/v1 usano chiavi API. I token di accesso OAuth usano l’API v2; la presenza di un esempio non dimostra che un ambiente sia configurato per quella versione.
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.
| Metodo | Percorso | Funzione |
|---|---|---|
GET | /external/v1/templates | Modelli 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/templates | Crea 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.variableselenca quelli presenti nell’oggetto e nell’HTML ignorando maiuscole e minuscole, nell’ordine e con la grafia della prima comparsa. kindèhtmlper un modello creato tramite API edesignedper 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
@unsubscribeo@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
cursorelimitper 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.
| Rifiuto | cd | Quando |
|---|---|---|
| 400 | TEMPLATE_TOO_LARGE | L’HTML supera 65,535 byte |
| 404 | TEMPLATE_NOT_FOUND | L’account non ha un modello con quell’ID |
| 409 | TEMPLATE_DESIGNED | Sostituzione 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.
| Metodo | Percorso | Funzione |
|---|---|---|
GET | /external/v1/sms/account | Limiti dell’account, invii del mese e tipi di messaggio consentiti |
GET | /external/v1/sms/senders | Intestazioni 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/templates | I modelli dell’account, poi quelli condivisi dall’account principale |
POST | /external/v1/sms/templates | Aggiunge 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}/sharing | Consente 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 da1an. 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_explicitopromotional.
- Nome
unicode- Tipo
- boolean
- Descrizione
Indica se il testo è Unicode;
falseper impostazione predefinita.
- Nome
active- Tipo
- boolean
- Descrizione
Indica se l’invio è consentito;
trueper 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_ALLOWEDe usano i modelli condivisi con loro. - La condivisione accetta
{"scope": "none" | "all" | "selected", "accounts": […]}, al massimo 1,000 valoriexternalIddi sottoaccount perselected. 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": truel’intestazione non è predefinita. Impostarne una come predefinita rimuove questo stato dalla precedente dell’account.
| Rifiuto | cd | Quando |
|---|---|---|
| 400 | INVALID_TEMPLATE | L’intestazione non corrisponde al tipo, ci sono più di 30 variabili o variableKeys non assegna un nome a ciascuna esattamente una volta |
| 403 | REGISTRY_NOT_ALLOWED | L’account non registra SMS propri |
| 404 | TEMPLATE_NOT_FOUND, SENDER_NOT_FOUND, ACCOUNT_NOT_FOUND | Modello, intestazione o sottoaccount inesistente |
| 409 | TEMPLATE_EXISTS | Un modello con quell’ID DLT è già registrato |
| 409 | SENDER_IN_USE | Eliminazione di un’intestazione usata da modelli |
| 422 | SENDER_NOT_ALLOWED | L’intestazione non appartiene all’account |
| 422 | MESSAGE_TYPE_NOT_ENABLED | Il 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.
| Metodo | Percorso | Funzione |
|---|---|---|
POST | /external/v1/whatsapp/connection | Collega il numero o sostituisce quello collegato |
GET | /external/v1/whatsapp/connection | Il numero collegato; 404 WHATSAPP_NOT_CONNECTED se assente |
DELETE | /external/v1/whatsapp/connection | Lo scollega: 204 |
GET | /external/v1/whatsapp/templates | I modelli con la revisione di Meta per ciascuno |
POST | /external/v1/whatsapp/templates | Invia 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
_, comeorder_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 ilnamerestituito, 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, comeen,hioen_US;ense omessa. Un nome può avere un modello per lingua; ripetere nome e lingua crea un conflitto.
- Nome
category- Tipo
- string
- Descrizione
Obbligatorio:
MARKETING,UTILITYoAUTHENTICATION.
- 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
statusdi un modello è lo stato di revisione salvato da Meta, per esempioPENDING,APPROVEDoREJECTED;rejectionReasonpuò essere assente.201significa inviato per revisione, non approvato. Si possono inviare solo modelliAPPROVED. Non è promesso un termine per completare la revisione. - Un destinatario restituisce
number,optedOut, quando e come (optedOutAt,optOutSource),lastInboundAtesessionOpenUntil: la finestra di 24 ore dall’ultimo messaggio in entrata.optedOutriguarda il marketing, non tutti i messaggi. Senza cronologia in entrata,lastInboundAtesessionOpenUntilsononull. Un timestamp di sessione da solo non garantisce che un invio sia accettato: restano validi gli altri controlli.
| Rifiuto | cd | Quando |
|---|---|---|
| 409 | TEMPLATE_EXISTS | L’account ha un modello con quel nome in quella lingua |
| 422 | WHATSAPP_NOT_CONNECTED | Invio di un modello in revisione senza un numero collegato |
| 422 | TEMPLATE_NAME_TOO_LONG | Il nome è troppo lungo per Meta |
| 422 | TEMPLATE_REFUSED | Meta ha rifiutato il modello; rifiuto generico localizzato, non il testo grezzo della risposta di Meta |
| 422 | INVALID_NUMBER | Il numero del destinatario non è in formato internazionale |
| 502 | WHATSAPP_CODE_REFUSED, WHATSAPP_SUBSCRIBE_REFUSED, WHATSAPP_REGISTER_REFUSED | Meta ha rifiutato un passaggio del collegamento del numero |
| 503 | WHATSAPP_UNAVAILABLE | Meta non era raggiungibile durante un passaggio del collegamento |