API v2 con OAuth
La nuova versione dell'API Oblic usa gli oggetti visibili in Oblic, percorsi, segmenti e messaggi, nello spazio collegato da una persona. Usa token di accesso OAuth 2.1 anziché chiavi API e agisce con il ruolo della persona. /external/v1 continua a funzionare con le chiavi API.
Il documento OpenAPI di questa versione è external-v2.json, mostrato come versione 2 nella documentazione OpenAPI.
Ottenere un token
L'API v2 non accetta mai una chiave API: inviandola si riceve 401 API_KEY_NOT_ACCEPTED. Una persona collega invece l'applicazione a uno dei propri spazi, dove l'applicazione agisce per suo conto.
Il deployment Oblic deve avere il server di autorizzazione OAuth attivo, l'API v2 tra le risorse consentite, chiavi di firma e pagina di consenso configurate e il client registrato. Conferma la disponibilità con l'assistenza Oblic prima dell'integrazione; gli URL di esempio non dimostrano che un deployment sia configurato.
- Registra l'applicazione. Comunica all'assistenza Oblic nome, URI di reindirizzamento e ambiti richiesti per ricevere un identificatore client. I client sono pubblici: non esiste un segreto client e ogni autorizzazione usa PKCE. Solo un server o un'app nativa può usare l'API: nessuna origine del browser è consentita né sull'endpoint dei token né sull'API.
- Invita la persona ad accedere. Apri l'endpoint di autorizzazione con il
resourcedell'API v2 escope=read sendper inviare messaggi, oppurescope=readper la sola lettura. La persona accede a Oblic, sceglie lo spazio e approva gli ambiti. - Scambia il codice sull'endpoint dei token con lo stesso
resource. - Chiama l'API con
Authorization: Bearer <access token>.
| Server di autorizzazione | https://api.oblic.app (metadati in /.well-known/oauth-authorization-server) |
| Endpoint di autorizzazione | https://api.oblic.app/oauth2/authorize |
| Endpoint dei token | https://api.oblic.app/oauth2/token |
| Risorsa | https://api.oblic.app/external/v2 |
| PKCE | Solo S256 |
| Token di accesso | valido per un'ora per impostazione predefinita |
| Token di aggiornamento | sostituito a ogni uso; per impostazione predefinita scade dopo 30 giorni senza utilizzo e 90 giorni dal collegamento iniziale |
Scambiare il codice
curl -X POST https://api.oblic.app/oauth2/token \
-d grant_type=authorization_code \
-d client_id=YOUR_CLIENT_ID \
-d code=THE_CODE \
-d redirect_uri=https://app.example.com/callback \
-d code_verifier=YOUR_CODE_VERIFIER \
-d resource=https://api.oblic.app/external/v2
Un token emesso per un'altra risorsa, come il server MCP di Oblic, non funziona qui. Una richiesta senza token utilizzabile riceve 401 con l'intestazione WWW-Authenticate che indica i metadati della risorsa, https://api.oblic.app/.well-known/oauth-protected-resource/external/v2.
Ambiti e ruoli
- Nome
read- Tipo
- scope
- Descrizione
Richiedilo sempre: un token senza questo ambito viene rifiutato. Permette di leggere percorsi e segmenti dello spazio e messaggi inviati tramite API.
- Nome
send- Tipo
- scope
- Descrizione
Permette di accodare invii e-mail, SMS e WhatsApp per l'organizzazione; non implica che il fornitore li abbia consegnati. La persona vede questo ambito su una riga distinta prima di approvarlo.
Un ambito non supera mai il ruolo della persona, verificato a ogni richiesta. Rimuovere il ruolo o l'appartenenza all'organizzazione interrompe immediatamente l'accesso del token.
- Percorsi e segmenti appartengono allo spazio scelto dalla persona; qualsiasi ruolo in quello spazio può leggerli.
- I messaggi inviati tramite API appartengono allo spazio predefinito dell'organizzazione, come con una chiave API. L'invio richiede
sende il ruolo Owner, Admin o Editor in tale spazio; qualsiasi ruolo nello spazio permette la lettura.
Il token non è soggetto all'elenco IP consentiti dell'organizzazione per le chiavi API: viene usato dai server dell'applicazione, nei limiti del ruolo della persona e degli ambiti approvati.
Endpoint dell'API
Ogni risposta contiene {"status": "success", "data": …, "errors": null}, oppure "status": "error" con gli errori.
| Metodo | Percorso | Funzione |
|---|---|---|
GET | /external/v2/journeys | Campagne, automazioni, bot WhatsApp e percorsi creati in Journeys dello spazio, modificati più di recente per primi |
GET | /external/v2/journeys/{id} | Un percorso |
GET | /external/v2/segments | Le liste dello spazio, poi i segmenti dinamici |
GET | /external/v2/segments/{id} | Un segmento |
POST | /external/v2/messages/email | Invia un'e-mail da un mittente verificato |
POST | /external/v2/messages/sms | Invia un SMS conforme a uno dei modelli DLT |
POST | /external/v2/messages/whatsapp | Invia un modello WhatsApp approvato o una risposta entro 24 ore |
GET | /external/v2/messages | Messaggi inviati tramite API, più recenti per primi, con i parametri della lista v1 |
GET | /external/v2/messages/{messageId} | Un messaggio inviato tramite API e il relativo esito |
Elencare i percorsi
- Nome
offset- Tipo
- integer
- Descrizione
Inizio della pagina;
0per impostazione predefinita.
- Nome
limit- Tipo
- integer
- Descrizione
Numero di percorsi, da 1 a 100;
50per impostazione predefinita.
- Nome
mode- Tipo
- string
- Descrizione
campaign,automation,botojourneyper un percorso creato in Journeys.
- Nome
status- Tipo
- string
- Descrizione
Stati consentiti:
draft,scheduled,live,pausedodone.
- Nome
search- Tipo
- string
- Descrizione
Parte del nome di un percorso.
Il nextOffset della pagina indica l'inizio della successiva ed è null nell'ultima.
Elencare i percorsi
curl 'https://api.oblic.app/external/v2/journeys?status=live&limit=20' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Risposta
{
"status": "success",
"data": {
"journeys": [
{
"id": "CMP000R7ZM4Q2VXH00",
"mode": "campaign",
"name": "Weekly offer",
"status": "live",
"createdAt": "2026-10-01T09:30:00Z",
"updatedAt": "2026-10-12T14:05:00Z"
}
],
"nextOffset": null
},
"errors": null
}
Inviare un messaggio
I corpi sono quelli di /external/v1/messages. L'invio viene accodato e riceve 202 con l'identificatore del messaggio. Ripeti con la stessa intestazione Idempotency-Key, da 1 a 255 caratteri, come negli invii v1: lo stesso invio restituisce il primo identificatore senza inviare ancora; la stessa chiave con un messaggio diverso dà 409 IDEMPOTENCY_CONFLICT. La chiave appartiene all'applicazione: un'altra applicazione o una chiave API con lo stesso valore invia un messaggio distinto.
Inviare un'e-mail
curl -X POST https://api.oblic.app/external/v2/messages/email \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: order-4471-shipped' \
-d '{
"to": ["customer@example.com"],
"subject": "Your order has shipped",
"html": "<p>Your order 4471 is on its way.</p>"
}'
Risposta
{
"status": "success",
"data": { "id": "msg_4f9c2a7e1b8d4e0f9a6c3b2d1e0f9a8b", "status": "queued" },
"errors": null
}
Leggi l'esito con GET /external/v2/messages/{messageId}.
Errori dell'API
| Stato HTTP | Codice di errore | Significato |
|---|---|---|
| 401 | MISSING_ACCESS_TOKEN | Nessun token di accesso inviato |
| 401 | INVALID_ACCESS_TOKEN | Token scaduto, emesso per altra risorsa, senza read o persona uscita dall'organizzazione: aggiornalo o collegati di nuovo |
| 401 | API_KEY_NOT_ACCEPTED | Chiave API inviata: usala con /external/v1 |
| 403 | INSUFFICIENT_SCOPE | Ambito necessario assente, indicato in WWW-Authenticate: collegati di nuovo e approvalo |
| 403 | FORBIDDEN | Il ruolo della persona non permette questa operazione |
| 403 | EMAIL_SUSPENDED | E-mail dell'account sospese per rimbalzi o segnalazioni di spam, come in /external/v1 |
| 400 | BAD_REQUEST, INVALID_IDEMPOTENCY_KEY | Parametro, intestazione o corpo assente o illeggibile |
| 400 | nome del campo, per esempio TO | Un campo del corpo non è valido |
| 402 | INSUFFICIENT_BALANCE | Un invio SMS o WhatsApp di marketing richiede fondi nel portafoglio pagante; un portafoglio vuoto non blocca codici di accesso, messaggi transazionali o risposte |
| 404 | JOURNEY_NOT_FOUND, SEGMENT_NOT_FOUND, MESSAGE_NOT_FOUND | Non presente nello spazio o non inviato tramite API |
| 404 | NOT_FOUND | La rotta non esiste |
| 405 | METHOD_NOT_ALLOWED | La rotta non accetta il metodo: Allow elenca quelli consentiti |
| 415 | UNSUPPORTED_MEDIA_TYPE | Corpo non inviato come application/json |
| 422 | UNVERIFIED_SENDER | Mittente dell'e-mail non verificato |
| 429 | RATE_LIMITED, QUOTA_EXCEEDED | Limiti orari o quota mensile e-mail superati, come in /external/v1; Retry-After indica quando riprovare |
Anche un SMS o WhatsApp può essere rifiutato con un motivo specifico, come in /external/v1: modello non approvato, numero disiscritto dal marketing, numero non collegato o limite raggiunto, con Retry-After quando conviene riprovare più tardi.