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.

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. La tua API key DeepAgent (la trovi in Impostazioni > API)

Endpoint API

L'endpoint per triggerare una chiamata è:

POST https://api.deepagent.ai/v1/calls/outbound

Headers richiesti

Authorization: Bearer YOUR_API_KEY Content-Type: application/json

Body della richiesta

json

{  "agentId": "agent_xxxxxxxxxxxxx",  "phoneNumber": "+393331234567",  "variables": {  "nome": "Mario",  "cognome": "Rossi",  "prodotto": "Piano Premium",  "scadenza": "28/02/2026"  } }

agentId: l'ID dell'agente che deve effettuare la chiamata. Lo trovi nella pagina dettaglio agente.

phoneNumber: il numero da chiamare, in formato internazionale con prefisso.

variables: oggetto con le variabili dinamiche che l'agente userà durante la chiamata. Devono corrispondere ai placeholder nel prompt dell'agente.

Risposta

json

{  "success": true,  "callId": "call_xxxxxxxxxxxxx",  "status": "queued",  "estimatedStartTime": "2026-01-29T10:30:00Z" }

La chiamata viene messa in coda e parte entro pochi secondi. Puoi usare il callId per monitorare lo stato.

Integrazioni comuni

Da un form web

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

javascript

// Esempio Node.js app.post('/contact-form', async (req, res) => {  const { nome, telefono, interesse } = req.body;   await fetch('https://api.deepagent.ai/v1/calls/outbound', {  method: 'POST',  headers: {  'Authorization': 'Bearer ' + process.env.DEEPAGENT_API_KEY,  'Content-Type': 'application/json'  },  body: JSON.stringify({  agentId: 'agent_xxxxxxxxxxxxx',  phoneNumber: 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://api.deepagent.ai/v1/calls/outbound

• Authentication: Bearer Token

• Body: JSON con agentId, phoneNumber 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. Configura il webhook post-call nelle impostazioni dell'agente. DeepAgent invierà un POST al tuo endpoint con:

json

{  "callId": "call_xxxxxxxxxxxxx",  "agentId": "agent_xxxxxxxxxxxxx",  "phoneNumber": "+393331234567",  "status": "completed",  "duration": 127,  "outcome": "qualified",  "transcript": "...",  "collectedData": {  "interesse": "alto",  "budget": "5000-10000",  "tempistiche": "entro 1 mese"  },  "variables": {  "nome": "Mario",  "cognome": "Rossi"  } }

Questo ti permette di aggiornare il tuo CRM, inviare notifiche al team vendite, o triggerare altre automazioni in base all'esito.

Gestire code e rate limit

L'API ha rate limit per evitare abusi:

• 100 chiamate/minuto per account

• 1000 chiamate/ora per account

Se superi i limiti, ricevi un errore 429 (Too Many Requests). Implementa retry con exponential backoff nel tuo codice.

Le chiamate vengono messe in coda e processate in ordine. Se l'agente sta già gestendo una chiamata, le nuove aspettano che si liberi. Considera questo se triggeri molte chiamate in poco tempo.

Gestire errori

Possibili errori nella risposta:

400 Bad Request: parametri mancanti o formato errato. Verifica agentId e phoneNumber.

401 Unauthorized: API key mancante o invalida.

404 Not Found: agentId non esiste o non hai accesso.

429 Too Many Requests: rate limit superato, riprova tra qualche secondo.

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

Implementa sempre gestione errori nel tuo codice per loggare i problemi e notificare il team se necessario.

Monitoraggio

Tutte le chiamate triggerate via API appaiono nello Storico Chiamate con la fonte "API". Puoi filtrarle per vedere solo le chiamate attivate programmaticamente.

Per ogni chiamata vedi: orario, durata, esito, trascrizione, dati raccolti. Usa questi dati per analizzare le performance e ottimizzare l'agente.

Best practice

Valida il numero prima: verifica che il numero sia in formato corretto prima di chiamare l'API. Numeri malformati consumano una chiamata API senza effettuare realmente la telefonata.

Rispetta i consensi: triggera chiamate solo verso numeri che hanno dato consenso. 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 API nel tuo sistema per debug e audit.

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