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.
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 e codice di errore è elencato nella documentazione API di Entagl. Aprila con il link Per sviluppatori: documentazione API vicino alla parte superiore di questa pagina e condividila con il tuo sviluppatore.
Funzionalità
Configurazione e autenticazione
Apri Impostazioni → Integrazioni, scegli API e clicca Genera chiave API. Attiva l'interruttore nella scheda del canale API, poi chiama l'API su https://api.entagl.com con l'intestazione Authorization: Bearer <la tua chiave>. Ogni chiave funziona solo per un singolo 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)
Incolla un URL di callback nella scheda del canale API e clicca Salva. Entagl poi invia ogni risposta dell'agente a esso, firmata con l'intestazione X-Entagl-Signature (HMAC-SHA256). Usa un indirizzo HTTPS pubblico e clicca Invia consegna di test per controllare che funzioni. Il tuo server dovrebbe verificare la firma e rispondere con un codice 2xx entro circa 5 secondi. I callback falliti non vengono riprovati.
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- Apri Impostazioni → Integrazioni, scegli API e clicca Genera chiave API. Dagli un nome se vuoi, poi copia la chiave ora, perché viene mostrata solo una volta.
- Attiva l'interruttore nell'intestazione della scheda del canale API. Finché non è attivo, i messaggi inviati all'API vengono rifiutati.
- Consigliato: apri le impostazioni della scheda, incolla il tuo URL di callback e clicca Salva. Copia il Segreto di firma che appare, poi clicca Invia consegna di test.
- Dalla tua app, invia messaggi tramite POST a https://api.entagl.com/api/v1/messages e ricevi le risposte tramite callback o polling.
Suggerimenti
Domande frequenti
Questa pagina ti è stata utile?