API Zapier e Make

Le app Whappy su Zapier e Make usano questa API. Puoi chiamarla anche tu per iscrivere qualsiasi URL agli eventi di Whappy, o per aggiungere lead.

URL di base e autenticazione

https://api.whappy.ai/v1

Invia la chiave API nell’header X-API-Key in ogni richiesta:

X-API-Key: your_api_key

Copia la chiave da Integrazioni → Zapier o Integrazioni → Make. Ogni chiave appartiene a un solo account Whappy; ogni richiesta agisce solo su quell’account. Le due chiavi sono separate: revocarne una non ferma mai l’altra. Un’iscrizione fatta con la chiave Make viene registrata come di Make; Whappy invia a entrambe gli stessi eventi. Una chiave mancante, sbagliata o revocata risponde 401:

{ "status": "error", "message": "Invalid API key" }

Verificare la chiave

POST /zap Risponde 200 con corpo vuoto (null) se la chiave è valida, altrimenti 401.

curl -X POST https://api.whappy.ai/v1/zap \
  -H "X-API-Key: your_api_key"

Iscrizioni agli eventi

Iscriversi

POST /zap/triggers

{
  "targetUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
  "zap_type": "DEAD",
  "hours": 24
}

Campo	Tipo	Obbligatorio	Note
`targetUrl`	string	sì	Dove Whappy invia (POST) il payload dell’evento.
`zap_type`	string	sì	L’evento: vedi la tabella sotto.
`hours`	integer	per `DEAD`	Ore senza risposta prima che l’evento parta. Con più iscrizioni `DEAD`, vale per tutte l’attesa più breve. Un’iscrizione `DEAD` senza `hours` non parte mai.
`name`	string	per `SEND_DATA`	Il nome del trigger. Lo step Invia dati della campagna lo sceglie in Nome del trigger.
`campaignName`	string	no	Salvato, per ora non applicato: un’iscrizione `CLOSE` riceve le conversazioni chiuse di tutte le campagne.

`zap_type`	Parte quando
`CLOSE`	Una conversazione arriva al suo step di chiusura.
`APPOINTMENT`	Un lead prenota un appuntamento nella conversazione (lo step appuntamento del funnel).
`DEAD`	Una conversazione aspetta da `hours` ore la risposta del lead. Ogni lead lo fa partire una sola volta.
`SEND_DATA`	Una conversazione arriva a uno step Invia dati impostato su Zapier o Make con questo `name`.

Risposta 201:

{ "id": "484ab94b-c9aa-43de-a086-c8cba3976998", "status": "success", "message": "Webhook registered successfully" }

Conserva l’id per annullare l’iscrizione.

curl -X POST https://api.whappy.ai/v1/zap/triggers \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"targetUrl": "https://example.com/whappy/closed", "zap_type": "CLOSE"}'

Elencare le iscrizioni

GET /zap/triggers restituisce le iscrizioni attive dell’account (fino a 100), quelle di Zapier e di Make insieme. Ognuna ha _id, url, zap_type, name, campaign_id (il campaignName inviato), metadata (source: zapier o make, e hours), created_at e revoked.

Annullare l’iscrizione

DELETE /zap/triggers/{id}, con l’id ricevuto all’iscrizione.
DELETE /zap/triggers con il corpo { "targetUrl": "...", "zap_type": "CLOSE" }.

Entrambe rispondono 200 con {"status": "success", "message": "Trigger removed"}, oppure con {"status": "already_removed", ...} se non c’era nulla da rimuovere.

Payload di esempio

GET /zap/sample/{name} restituisce un elenco con un payload di esempio, per collegare i campi prima che arrivi un evento vero. Ogni name restituisce lo stesso esempio, e l’esempio non contiene campaign_name.

Indirizzi per evento (vecchio metodo)

POST /zap/url/{name} con { "targetUrl": "...", "hours": 24 } salva un indirizzo per close, appointment o dead (hours solo per dead), e DELETE /zap/url/{name} lo rimuove. Whappy invia ancora gli eventi a questi indirizzi, insieme alle iscrizioni. Per tutto ciò che è nuovo usa /zap/triggers: supporta più URL per evento e SEND_DATA.

Payload dell’evento

Quando l’evento succede, Whappy invia un POST con questo corpo JSON a ogni URL iscritto. Oltre a Content-Type: application/json non aggiunge altri header. Qualsiasi risposta 2xx vale come consegnata; un URL che fallisce resta iscritto.

{
  "lead_id": "f8e7d6c5-b4a3-9876-5432-1fedcba09876",
  "created_at": "2026-10-08T09:00:00+00:00",
  "campaign_name": "Offerta primavera",
  "phone": "+12025551234",
  "name": "John Doe",
  "lead_info_json": "{\"name\": \"John Doe\", \"budget\": \"5000\"}",
  "collected_info_json": "{\"Budget Range\": \"$5,000-$10,000\", \"Timeline\": \"3 months\"}",
  "appointment_json": "{\"datetime\": \"2026-10-09T14:30:00+00:00\", \"event_id\": \"sample_event_123\"}",
  "appointment": { "full_date": "2026-10-09T14:30:00+00:00" },
  "conversation_json": "[{\"sender\": \"ai\", \"message\": \"Ciao! Che budget hai in mente?\", \"datetime\": \"2026-10-08T09:00:00+00:00\"}, {\"sender\": \"lead\", \"message\": \"Circa 5.000 €.\", \"datetime\": \"2026-10-08T09:05:00+00:00\"}]"
}

Campo	Tipo	Descrizione
`lead_id`	string	L’id del lead in Whappy.
`created_at`	string	Quando è stato creato il lead (ISO 8601).
`campaign_name`	string	La campagna del lead.
`phone`	string	Il numero del lead in formato internazionale. Vuoto per un lead senza numero di telefono, ad esempio un lead Instagram.
`name`	string	Il nome del lead.
`lead_info_json`	string	I dati con cui è arrivato il lead (campi del modulo, dati extra), come oggetto JSON.
`collected_info_json`	string	Ciò che l’AI ha raccolto nella conversazione, per nome del campo, come oggetto JSON.
`appointment_json`	string	`datetime` ed `event_id` dell’appuntamento, come oggetto JSON. Valori vuoti se non c’è.
`appointment.full_date`	string	Data e ora prenotate (ISO 8601), oppure `""`.
`conversation_json`	string	I messaggi come elenco JSON. `sender` è `ai`, `lead`, oppure `user` per un messaggio inviato dal tuo team da Chat.

In un evento SEND_DATA inviato a un’iscrizione Zapier, i quattro campi *_json sono testo leggibile invece di JSON, ad esempio {'Budget Range': '$5,000-$10,000'}. Non interpretarli come JSON. Le iscrizioni Make e tutti gli altri eventi ricevono JSON.

Interpreta i campi *_json prima di usarli:

app.post('/whappy/closed', (req, res) => {
  const payload = req.body;
  const collected = JSON.parse(payload.collected_info_json || '{}');
  const messages = JSON.parse(payload.conversation_json || '[]');
  console.log(payload.name, payload.campaign_name, collected, messages.length);
  res.sendStatus(200);
});

Creare un lead

POST /lead

{
  "phone": "+393331234567",
  "name": "Anna",
  "email": "anna@example.com",
  "campaign_name": "Offerta primavera",
  "is_test": true,
  "lead_data": { "budget": "5000", "city": "Milano" }
}

Campo	Tipo	Note
`phone`	string	Formato internazionale. Un numero locale funziona se l’account ha un paese predefinito.
`name`	string	Il nome del lead.
`email`	string	Facoltativo.
`campaign_name`	string	Facoltativo. La campagna Whappy. Sconosciuta o vuota: decide l’instradamento predefinito dell’account.
`is_test`	boolean	Facoltativo. Segna il lead come lead di test.
`lead_data`	object	Facoltativo. Campi extra, salvati con il lead; l’AI e i template possono leggerli.

L’azione Create Lead su Zapier e Make invia questi campi. È lo stesso endpoint dell’integrazione Webhook, che elenca tutti i campi accettati. Risposta 200:

{ "status": "success", "message": "Lead created successfully", "data": { "_id": "...", "name": "Anna", "phone": "+393331234567", "...": "..." } }

message dice cosa è successo:

Lead created successfully: un lead nuovo.
Lead already exists; details merged: la stessa persona era già in quella campagna. Whappy tiene un solo lead e aggiunge i nuovi dati.
Lead already exists; details merged and campaign restart requested: come sopra, e la conversazione riparte da capo perché la campagna ha attivo Riavvia la campagna per un lead che torna.

Errori

Stato	Quando	Corpo
`400`	Il numero di telefono non è leggibile.	`{"detail": "Phone number '12' is not a valid number; add the international prefix (e.g. +48) or set a default country in Whappy settings"}`
`401`	Chiave API mancante, sbagliata o revocata.	`{"status": "error", "message": "Invalid API key"}`
`409`	Creare un lead: la campagna non parla su WhatsApp. I lead di test non vengono rifiutati.	`{"detail": {"code": "campaign_not_on_whatsapp", "message": "This campaign does not talk on WhatsApp, so it cannot take people by phone number. ..."}}`
`422`	Manca un campo obbligatorio o ha il tipo sbagliato.	`{"detail": [ ... ], "message": "zap_type: Field required"}`
`500`	Errore imprevisto lato Whappy; riprova più tardi.	`{"detail": "..."}`

Assistenza

Scrivi a team@whappy.ai con la richiesta, la risposta e l’ora in cui è successo. Non inviare mai la chiave API completa.

Conversazioni

E-commerce

Client AI

CRM

Lead

Appuntamenti

Pubblicità

URL di base e autenticazione

Verificare la chiave

Iscrizioni agli eventi

Iscriversi

Elencare le iscrizioni

Annullare l’iscrizione

Payload di esempio

Indirizzi per evento (vecchio metodo)

Payload dell’evento

Creare un lead

Errori

Assistenza

​URL di base e autenticazione

​Verificare la chiave

​Iscrizioni agli eventi

​Iscriversi

​Elencare le iscrizioni

​Annullare l’iscrizione

​Payload di esempio

​Indirizzi per evento (vecchio metodo)

​Payload dell’evento

​Creare un lead

​Errori

​Assistenza

URL di base e autenticazione

Verificare la chiave

Iscrizioni agli eventi

Iscriversi

Elencare le iscrizioni

Annullare l’iscrizione

Payload di esempio

Indirizzi per evento (vecchio metodo)

Payload dell’evento

Creare un lead

Errori

Assistenza