L'API di Entagl permette al tuo software di lavorare con un workspace Entagl: contatti, conversazioni, messaggi, prenotazioni, promemoria, ordini, prodotti, chiamate AI e campagne. I webhook avvisano i tuoi sistemi nel momento in cui succede qualcosa. È la stessa API usata dall'app Entagl per Make.

Richieste e risposte sono JSON su HTTPS. I nomi dei campi sono in snake_case. Gli ID sono numeri interi, salvo diversa indicazione di un endpoint. Gli orari sono stringhe ISO 8601; le risposte usano UTC.

Invia un token con ogni richiesta nell'header Authorization: Authorization: Bearer <token>. Funzionano due tipi di token:

Un header mancante risponde 401 unauthenticated. Una chiave errata o revocata risponde 401 invalid_api_key. Un token OAuth scaduto risponde 401 invalid_token: aggiornalo e riprova.

Ogni richiesta lavora su un solo workspace. Una API key usa sempre il proprio workspace. Un login OAuth può appartenere a più workspace (di sua proprietà o a cui partecipa come membro del team): invia l'header X-Entagl-Workspace con l'ID del workspace per sceglierne uno. Con un solo workspace l'header è facoltativo. GET /me funziona senza l'header ed elenca ogni workspace che il login può usare.

Senza l'header su un login con più workspace ricevi 400 workspace_required; un workspace a cui il login non può accedere risponde 403 workspace_forbidden. Un ID che appartiene a un altro workspace risponde sempre 404 not_found, mai 403.

Ogni endpoint qui sotto mostra il permesso di cui ha bisogno. Proprietari, admin e API key superano ogni controllo. I membri del team lo superano quando il loro ruolo ha quel permesso spuntato nelle impostazioni del team: contacts, inbox, calendar, orders, business_pages, call_agent, campaigns o integrations. Senza di esso l'API risponde 403 insufficient_permissions.

Invia i corpi come JSON con Content-Type: application/json. La maggior parte degli endpoint rifiuta con 422 i campi sconosciuti nel corpo, così un errore di battitura non passa mai in silenzio. Ogni errore ha la stessa forma: un code stabile su cui ramificare, un message leggibile e, per gli errori di validazione, una lista details che indica ogni campo errato.

Le route contrassegnate come Formato di risposta legacy sono precedenti a queste convenzioni: restituiscono semplici oggetti o array JSON e rispondono alla maggior parte degli errori come { "message": "…" }.

Gli endpoint contrassegnati come Paginato restituiscono prima gli elementi più recenti, in una struttura di lista. Chiedi fino a 100 elementi con limit (predefinito 25). Quando has_more è true, passa next_cursor come starting_after per ottenere la pagina successiva. Le altre liste restituiscono tutto in una volta con has_more: false.

Ogni endpoint POST nel formato standard accetta l'header Idempotency-Key (fino a 200 caratteri). Usa un valore unico per ogni operazione, ad esempio un UUID. Entagl conserva la prima risposta per 24 ore: un nuovo tentativo con la stessa chiave e lo stesso body riceve quella risposta con Idempotent-Replayed: true, e niente viene eseguito due volte. Le route contrassegnate come Formato di risposta legacy funzionano diversamente, vedi sotto.

• La stessa chiave con un corpo diverso risponde 409 idempotency_key_reused.
• Finché la prima richiesta è ancora in corso, o se non è mai terminata, un nuovo tentativo risponde 409 request_in_progress. Controlla l'esito, poi riprova con una nuova chiave.
• Ogni esito viene conservato, errori compresi. Per riprovare una richiesta fallita, usa una nuova chiave.
• Le chiavi sono legate al workspace e alla credenziale.

Route legacy. Anche POST /messages accetta Idempotency-Key (o un message_id nel body): ripetere un messaggio già accettato risponde 202 con lo stesso conversationId e non viene elaborato due volte, mentre la stessa chiave con un body diverso risponde 409. POST /chat non ha protezione dai tentativi ripetuti: un nuovo tentativo riavvia l'AI, quindi controlla l'esito prima di riprovare.

Ogni workspace può fare 120 richieste al minuto, condivise tra tutte le sue API key e connessioni. Le risposte includono RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset (secondi che mancano al reset della finestra). Oltre il limite ricevi 429 rate_limited con un header Retry-After: attendi quei secondi, poi riprova. Le route legacy del canale API non rientrano in questo limite.