Come far partire le campagne outbound da trigger API

Panoramica

A differenza delle campagne batch dove carichi una lista e fai partire tutte le chiamate, i trigger API ti permettono di avviare una singola chiamata in tempo reale. Quando un evento accade nel tuo sistema (nuovo lead, ordine completato, appuntamento creato), la tua applicazione chiama l'API DeepAgent e l'agente telefona immediatamente al contatto.

Questa guida copre il caso d'uso più comune. Il riferimento completo e sempre aggiornato di tutti gli endpoint è nella documentazione API DeepAgent.

Casi d'uso tipici

Lead in tempo reale: un potenziale cliente compila un form sul sito, l'agente lo chiama entro 30 secondi per qualificarlo.

Conferma ordine: il cliente completa un acquisto, l'agente chiama per confermare i dettagli e proporre upsell.

Reminder appuntamento: 24 ore prima di un appuntamento, il gestionale triggera una chiamata di conferma.

Alert e notifiche: un sistema di monitoraggio rileva un problema, l'agente chiama il responsabile per avvisarlo.

Prerequisiti

Per usare i trigger API devi avere:

1. Un agente outbound configurato e attivo

2. Un numero di telefono assegnato all'agente

3. Una API key DeepAgent con lo scope calls:write (la generi da Impostazioni > API)

Endpoint API

L'endpoint per avviare una chiamata in uscita è:

POST https://platform.deepagent.app/api/v1/calls

Headers richiesti

Authorization: Bearer da_<env>_<key_id>_<secret>Content-Type: application/jsonIdempotency-Key: <stringa univoca per ogni richiesta>

Idempotency-Key è obbligatoria. Serve a evitare che un retry dopo un timeout faccia squillare due volte il telefono di un cliente: stessa chiave e stesso corpo restituiscono la risposta originale, stessa chiave con un corpo diverso risponde 409. Usa un UUID generato dal tuo sistema.

Esiste anche un header opzionale X-Workspace-Id, per indicare il workspace su cui operare. Va omesso se la chiave ne ha uno solo: è ammesso solo per le chiavi con delega partner.

Body della richiesta

{  "agent_id": "6f1c9a24-8b3d-4f7a-9c25-1d0e7a3b5c88",  "to": "+393331234567",  "variables": {  "nome": "Mario",  "cognome": "Rossi",  "prodotto": "Piano Premium",  "scadenza": "28/02/2026"  } }

agent_id (obbligatorio): l'UUID dell'agente che deve chiamare. Deve essere attivo e avere un numero assegnato, altrimenti la chiamata non parte. Lo trovi nella pagina di dettaglio dell'agente.

to (obbligatorio): il numero da chiamare in formato E.164, quindi con il + e il prefisso internazionale. Se il numero è nelle esclusioni, la chiamata viene rifiutata.

variables: le variabili dinamiche che l'agente userà durante la chiamata. Devono corrispondere ai placeholder nel prompt dell'agente e i valori devono essere stringhe: numeri e booleani vanno convertiti prima dell'invio.

phone_number_id (facoltativo): il numero di partenza. Se lo ometti si usa quello assegnato all'agente.

skip_time_check (facoltativo, default false): salta la finestra oraria configurata sull'agente. Lasciandolo a false eviti chiamate fuori orario, che sono un problema di conformità prima che di educazione.

Risposta

In caso di successo ricevi un 202 Accepted:

{  "data": {  "id": "9d84a1f0-52c7-4a1e-9f33-0b6e2c7d4411",  "status": "queued",  "agent_id": "6f1c9a24-8b3d-4f7a-9c25-1d0e7a3b5c88",  "phone_number_id": "b27f5e13-90aa-4c6d-8e21-77c4d9f0a562"  } }

La risposta arriva prima che il telefono squilli: lo stato è sempre queued. Usa data.id con GET /v1/calls/{id} per seguire l'esito della chiamata.

Integrazioni comuni

Da un form web

Quando un utente compila un form di contatto, il tuo backend può avviare immediatamente una chiamata:

// Esempio Node.js app.post('/contact-form', async (req, res) => {  const { nome, telefono, interesse } = req.body;   await fetch('https://platform.deepagent.app/api/v1/calls', {  method: 'POST',  headers: {  'Authorization': 'Bearer ' + process.env.DEEPAGENT_API_KEY,  'Content-Type': 'application/json',  'Idempotency-Key': crypto.randomUUID()  },  body: JSON.stringify({  agent_id: '6f1c9a24-8b3d-4f7a-9c25-1d0e7a3b5c88',  to: telefono,  variables: { nome, interesse }  })  });   res.json({ message: 'Ti richiamiamo subito!' }); });

Da n8n

Crea un workflow n8n con un nodo HTTP Request che chiama l'API DeepAgent. Puoi triggerare il workflow da qualsiasi evento: nuovo record in Airtable, nuovo ordine WooCommerce, nuovo ticket Zendesk.

Configurazione nodo HTTP Request:

• Method: POST

• URL: https://platform.deepagent.app/api/v1/calls

• Authentication: Bearer Token

• Header aggiuntivo: Idempotency-Key, valorizzato con l'id del record che ha scatenato il workflow

• Body: JSON con agent_id, to e variables mappate dai nodi precedenti

Da Zapier / Make

Usa l'azione "Webhook" per chiamare l'API DeepAgent quando si verifica un trigger in un'altra app.

Da CRM (HubSpot, Salesforce, Pipedrive)

Configura un workflow nel CRM che, quando un lead entra in una determinata fase, chiama un webhook. Il webhook può essere un endpoint tuo che poi chiama l'API DeepAgent, oppure puoi usare n8n/Zapier come intermediario.

Webhook di callback

Puoi ricevere una notifica quando la chiamata termina, sottoscrivendo un webhook. Gli eventi disponibili sono call.completed, call.failed, campaign.completed, recall.scheduled, message.received e contact.created.

L'endpoint di destinazione deve essere in https, perché il payload contiene dati dei tuoi clienti. Alla creazione della sottoscrizione ricevi un secret, mostrato una sola volta: serve a verificare la firma X-DeepAgent-Signature di ogni consegna, nel formato t=<epoch>,v1=<hmac-sha256 di "<t>.<body>">. Verifica sempre la firma prima di elaborare il contenuto: senza quel controllo il tuo endpoint accetta qualsiasi POST arrivi da Internet.

La struttura esatta del payload di ogni evento è nella documentazione API. Con questi dati puoi aggiornare il tuo CRM, notificare il team vendite o innescare altre automazioni in base all'esito.

Gestire code e rate limit

L'API è soggetta a rate limit: al superamento ricevi un 429 Too Many Requests. Implementa un retry con exponential backoff, riusando la stessa Idempotency-Key della richiesta originale, così un retry non genera una seconda telefonata.

Le chiamate vengono messe in coda e processate in ordine. Se l'agente sta già gestendo una chiamata, le nuove aspettano che si liberi: tienine conto se ne avvii molte in poco tempo.

Gestire errori

Ogni errore risponde con un oggetto error che contiene code (il codice stabile su cui scrivere la logica), message (in inglese, può cambiare fra versioni: non confrontarlo nel codice), details e request_id. Riporta sempre il request_id quando segnali un problema al supporto: è ciò che permette di ritrovare la richiesta nei log.

400 Bad Request: parametri mancanti o formato errato. Verifica agent_id e il formato E.164 di to.

401 Unauthorized: API key mancante, non valida o revocata.

403 Forbidden: la chiave non ha lo scope calls:write, oppure non è autorizzata sul workspace richiesto.

409 Conflict: hai riusato una Idempotency-Key con un corpo diverso.

429 Too Many Requests: rate limit superato, riprova con backoff.

500 Internal Server Error: problema lato DeepAgent, riprova o contatta il supporto con il request_id.

Monitoraggio

Tutte le chiamate avviate via API appaiono nello Storico Chiamate. Puoi filtrarle per vedere solo quelle attivate programmaticamente.

Via API, GET /v1/calls/{id} restituisce il dettaglio della singola chiamata, mentre GET /v1/calls/{id}/transcript e GET /v1/calls/{id}/recording danno trascrizione e registrazione. Usa questi dati per analizzare le performance e ottimizzare l'agente.

Best practice

Valida il numero prima: verifica che sia in E.164 prima di chiamare l'API. Numeri malformati consumano una richiesta senza effettuare la telefonata.

Genera una Idempotency-Key deterministica: usando l'id del record di origine (lead, ordine, appuntamento) eviti doppie chiamate anche se il tuo sistema ritenta.

Rispetta i consensi: avvia chiamate solo verso numeri che hanno dato consenso, e tieni traccia del consenso nel tuo sistema.

Limita i retry automatici: se un numero non risponde, non ritriggerare immediatamente. Usa logica di backoff o programma un retry manuale.

Logga tutto: salva le risposte dell'API, incluso il request_id, per debug e audit.

Testa prima: prima di collegare l'API al sistema di produzione, prova con numeri di test per verificare che tutto funzioni.