Vai al contenuto
Canali e integrazioni

Canale API

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

1 Attiva le risposte AI per il canale API. Screenshot preso il 10 novembre 2026.

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 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.

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

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
  1. 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.
  2. Attiva l'interruttore nell'intestazione della scheda del canale API. Finché non è attivo, i messaggi inviati all'API vengono rifiutati.
  3. 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.
  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?