Vai al contenuto
Sviluppatori
Canali e integrazioni

Canale API

Collega Entagl alla tua app o a Make: invia messaggi, ricevi risposte e gestisci il tuo workspace.

Panoramica

Il canale API ti permette di usare lo stesso agente AI che alimenta i tuoi DM dal chat del tuo sito, dalla tua app mobile o dal backend. Invi un messaggio, l’agente ragiona (con lo stesso buffering e risposte multi-messaggio, umane, di un vero DM) e la risposta ti arriva poco dopo, tramite callback webhook o polling. Configuralo in Canali → API: genera una API key, attiva il canale, poi scegli callback o polling. La stessa API permette anche al tuo sviluppatore, o a Make, di lavorare con contatti, conversazioni, prenotazioni, ordini e altro ancora. Vedi la scheda Workspace API.

Per gli sviluppatori: riferimento API
Ogni endpoint, campo ed evento webhook, con esempi di codice.

Schede in questa pagina

L’API non serve solo per la chat. Il tuo sviluppatore, o uno strumento come Make, può usarla per leggere e aggiornare gran parte del tuo workspace.

Cosa puoi fare con questa API

Oltre a inviare messaggi, l’API copre:

  • Contacts: crea, aggiorna, cerca, unisci, aggiungi note, marca come do-not-contact
  • Tags e lifecycle stages: aggiungi o rimuovi tag, sposta un contatto in un altro stage
  • Conversations: assegna a un teammate, chiudi con una nota di chiusura, metti in pausa o riprendi l’AI, aggiungi commenti del team, invia un messaggio come la tua azienda
  • Bookings e reminders: controlla gli orari disponibili, prenota, riprogramma, cancella, crea e chiudi promemoria
  • Orders e products: crea e aggiorna ordini e relativi articoli, gestisci il catalogo
  • Calls: avvia una chiamata telefonica AI o mettila in coda, leggi il risultato
  • Campaigns: visualizza le campagne e inviane una

Quando qualcosa cambia, Entagl può avvisare subito i tuoi strumenti tramite webhooks.

Due modi per accedere

Make. Quando colleghi Make, accedi con il tuo account Entagl. Make agisce quindi come te, con esattamente i tuoi permessi: un owner o admin può fare tutto, un team member solo ciò che consentono i suoi privilegi. Se il tuo login ha più di un workspace, scegli quale usare.

API key. Per il tuo server, crea una key in Canali → API oppure Impostazioni → API keys e inviala come Authorization: Bearer <your key>. Una key appartiene a un solo workspace e ha pieno accesso owner a quel workspace, quindi trattala come una password.

Sicuro da riprovare: l’header Idempotency-Key

A volte una richiesta passa ma la risposta si perde durante il ritorno. Se il tuo sistema non è sicuro che una richiesta sia andata a buon fine, può reinviarla con lo stesso header Idempotency-Key. Entro 24 ore Entagl riconosce la chiave, salta l’operazione e restituisce la prima risposta, così non ti ritrovi con due ordini o due contatti. Usare la stessa chiave per una richiesta diversa viene rifiutato con un errore.

Quante richieste puoi inviare

Fino a 120 richieste al minuto per ogni workspace. Oltre questo limite Entagl risponde con errore 429 (rate_limited). Aspetta un attimo e riprova. La maggior parte delle automazioni non ci va neanche vicino.

La documentazione completa dell’API

Ogni endpoint, campo ed errore è elencato nella documentazione API di Entagl. Se il tuo sviluppatore non ce l’ha ancora, scrivi a support@entagl.com e chiedi la documentazione dell’API.

Una API key dà pieno accesso owner al suo workspace. Conservala sul tuo server, mai in un sito o in un’app a cui i clienti possono accedere, e revocala appena sospetti che sia stata compromessa.
Le modifiche fatte tramite l’API vengono marcate nei tuoi webhook events come provenienti dall’API, così uno scenario Make può ignorare le proprie modifiche invece di entrare in loop.

Funzionalità

Configurazione e autenticazione

Genera una chiave API in Channels → API, attiva l'interruttore del canale, quindi chiama l'API su https://api.entagl.com con l'header Authorization: Bearer <la tua chiave>. Le chiavi sono limitate allo spazio di lavoro.

Inviare un messaggio

Invia POST /api/v1/messages con { message, externalUserId }. Ricevi subito un 202 e un conversationId. Riusa quel conversationId per continuare la conversazione. La risposta dell’agente arriva più tardi, non in questa risposta.

Webhook (callback) (consigliato)

Aggiungi un URL di callback HTTPS pubblico ed Entagl invierà lì ogni risposta dell'agente tramite POST, firmata con l'header X-Entagl-Signature (HMAC-SHA256). Verifica la firma e rispondi 2xx entro ~5 secondi. Non c'è alcun nuovo tentativo automatico.

Polling

Se non puoi ospitare un URL di callback, chiama GET /api/v1/conversations/:id/messages?since=<cursor> per recuperare le nuove risposte. Rimanda il cursor di ogni risposta come ?since= per ricevere solo i nuovi messaggi.

Sicurezza e isolamento

Le API key sono archiviate in formato hash e il secret di firma è criptato (entrambi vengono mostrati una sola volta). Ogni lookup è limitato al workspace: un conversation ID di un altro workspace restituisce 404 e non puoi passare un user ID (viene derivato dalla tua key).

Attività comuni

Configurare il canale API

Circa 3 min
  1. Vai su Channels → API e clicca su Generate API Key. Copiala subito, perché viene mostrata una sola volta.
  2. Attiva l'interruttore del canale nell'intestazione della scheda API.
  3. Consigliato: espandi la scheda, incolla un URL di callback HTTPS pubblico, salva e copia il segreto di firma.
  4. Dalla tua app, invia messaggi tramite POST a https://api.entagl.com/api/v1/messages e ricevi le risposte tramite callback o polling.

Suggerimenti

Le risposte sono asincrone. La POST restituisce 202 e la risposta dell’agente arriva tramite callback o polling, non nella risposta.
Un messaggio può produrre più risposte dopo un breve ritardo di buffering (circa 8 secondi, configurabile fino a ~5 minuti). Mostrale tutte, in ordine.
Un 202 non garantisce una risposta. L’agente può restare in silenzio se l’automazione è in pausa, un guardrail blocca il messaggio o il workspace ha esaurito i crediti.
I callback non hanno nuovi tentativi automatici. Tieni il polling come riserva e verifica sempre l'header X-Entagl-Signature prima di fidarti di una consegna.
Riutilizza il conversationId per continuare una conversazione; externalUserId è solo la tua etichetta per l'utente finale.
Per ora solo testo. Tieni al sicuro la tua API key e il signing secret: entrambi vengono mostrati una sola volta.

Domande frequenti

Questa pagina ti è stata utile?