Webhook

Il webhook aggiunge lead dai tuoi sistemi: un modulo sul tuo sito, il tuo CRM, un’app che hai costruito. Invii una richiesta HTTP per ogni lead, il lead entra in una campagna e la campagna avvia la conversazione su WhatsApp. Il webhook è disponibile per ogni tipo di account.

Apri la pagina del webhook

Vai su Integrazioni. Il webhook è nel gruppo Automazioni.
Attiva il suo interruttore. Il webhook compare nella barra laterale e la sua scheda apre la sua pagina.
Apri Integrazioni → Webhook.

La sezione Connessione mostra l’Endpoint e la tua Chiave API. Il pulsante con l’occhio mostra la chiave, quello di copia la copia.

Chiunque abbia la tua chiave API può aggiungere lead al tuo account. Tienila sul tuo server, mai nel codice di una pagina web.

Invia un lead

POST https://api.whappy.ai/v1/lead

Intestazioni

Content-Type: application/json
X-API-Key: LA_TUA_API_KEY

Corpo

{
  "name": "Mario Rossi",
  "phone": "+393331234567",
  "email": "mario@example.com",
  "campaign": "Spring promo",
  "tags": ["website"],
  "budget": "5000"
}

Campo	Cosa fa
`name`	Il nome del lead.
`phone`	Il numero WhatsApp. Scrivilo con il prefisso internazionale (`+39…`), oppure imposta un paese predefinito (vedi sotto).
`email`	Facoltativo.
`campaign` o `campaign_id`	Facoltativo. Il nome della campagna, o il suo id. Se li ometti entrambi, si usa la campagna predefinita.
`tags`	Facoltativo. Una lista, o un testo separato da virgole. I tag vengono salvati sul lead.
`language`	Facoltativo. La lingua del lead, come codice (`es`, `es-ES`) o nome inglese (`Spanish`). Si usa quando Lingua del modulo o della pagina è attiva in Lingua dei nuovi lead (nel Profilo). Un valore sconosciuto viene ignorato.
ogni altro campo	Viene salvato sul lead, come `budget` qui sopra. L’AI lo legge, e i template WhatsApp possono usarlo come `{{budget}}`.

name e phone sono ciò che serve a una conversazione. I campi dentro un oggetto lead_data vengono letti come se fossero al primo livello.

Quale campagna riceve il lead

campaign_id, se lo invii.
Altrimenti la campagna il cui nome corrisponde a campaign.
Altrimenti la campagna predefinita. La scegli nella pagina Campagne: apri il menu di una campagna e scegli Imposta come predefinita.

La campagna deve parlare su WhatsApp. Una campagna che parla solo su Instagram non può ricevere un lead tramite numero di telefono, e la richiesta viene rifiutata (vedi Errori).

Numeri senza prefisso

Apri il Profilo e cerca Numeri di telefono dei lead. Con un Paese predefinito impostato, a un numero che arriva senza prefisso si aggiunge il prefisso di quel paese. Un numero che Whappy non riesce a leggere come numero di telefono viene rifiutato.

Esempi di codice

cURL
JavaScript
Python

curl -X POST https://api.whappy.ai/v1/lead \
  -H "Content-Type: application/json" \
  -H "X-API-Key: LA_TUA_API_KEY" \
  -d '{
    "name": "Mario Rossi",
    "phone": "+393331234567",
    "email": "mario@example.com",
    "campaign": "Spring promo",
    "tags": ["website"],
    "budget": "5000"
  }'

const response = await fetch("https://api.whappy.ai/v1/lead", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "LA_TUA_API_KEY",
  },
  body: JSON.stringify({
    name: "Mario Rossi",
    phone: "+393331234567",
    email: "mario@example.com",
    campaign: "Spring promo",
    tags: ["website"],
    budget: "5000",
  }),
});
console.log(await response.json());

import requests

response = requests.post(
    "https://api.whappy.ai/v1/lead",
    headers={"X-API-Key": "LA_TUA_API_KEY"},
    json={
        "name": "Mario Rossi",
        "phone": "+393331234567",
        "email": "mario@example.com",
        "campaign": "Spring promo",
        "tags": ["website"],
        "budget": "5000",
    },
)
print(response.json())

Risposta

Una risposta 200 vuol dire che il lead è entrato. data è il lead come Whappy lo ha salvato (qui accorciato):

{
  "status": "success",
  "message": "Lead created successfully",
  "data": {
    "name": "Mario Rossi",
    "phone": "+393331234567",
    "email": "mario@example.com",
    "tags": ["website"],
    "lead_info": {"budget": "5000"}
  }
}

La stessa persona inviata di nuovo alla stessa campagna (stesso telefono) non viene duplicata: i dati del lead vengono aggiornati e la risposta è sempre 200. message dice cosa è successo:

`message`	Significato
`Lead created successfully`	Un nuovo lead.
`Lead already exists; details merged`	Il lead c’era già; i suoi dati sono stati aggiornati.
`Lead already exists; details merged and campaign restart requested`	Come sopra, e la campagna riparte da capo con questo lead. Succede solo quando l’opzione Riavvia la campagna per un lead che torna della campagna è attiva e la conversazione era già iniziata.

Errori

Stato	Corpo	Causa
`401`	`{"status": "error", "message": "Invalid API key"}`	L’intestazione `X-API-Key` contiene una chiave che Whappy non conosce.
`401`	`{"status": "error", "message": "Authentication required. Provide a valid API key (X-API-Key header) or Bearer token."}`	Manca l’intestazione `X-API-Key`.
`400`	`{"detail": "Phone number '…' is not a valid number…"}`	Il telefono non si può leggere come numero. Aggiungi il prefisso internazionale, oppure imposta un paese predefinito.
`409`	`{"detail": {"code": "campaign_not_on_whatsapp", "message": "…"}}`	La campagna non parla su WhatsApp. Attiva WhatsApp nelle opzioni della campagna, oppure invia il lead a un’altra campagna.
`422`	`{"detail": [...]}`	Il corpo non è un oggetto JSON.
`500`	`{"detail": "…"}`	Whappy non è riuscito a salvare il lead. Riprova.

Provalo

Invia una richiesta con solo name e il tuo phone.
Controlla che la risposta sia 200.
Apri la scheda Lead della campagna e trova il nuovo lead.

Risoluzione dei problemi

Il lead è finito nella campagna sbagliata. Il valore di campaign deve essere il nome della campagna, scritto uguale (maiuscole e minuscole non contano). Se nessuna campagna corrisponde, il lead va nella campagna predefinita. Il lead è entrato, ma non arriva nessun messaggio. La campagna deve essere attiva e il tuo account deve avere un numero WhatsApp collegato. Vedi WhatsApp. Serve aiuto? Consulta le FAQ o contatta l’assistenza.

Conversazioni

E-commerce

Client AI

CRM

Lead

Appuntamenti

Pubblicità

Apri la pagina del webhook

Invia un lead

Intestazioni

Corpo

Quale campagna riceve il lead

Numeri senza prefisso

Esempi di codice

Risposta

Errori

Provalo

Risoluzione dei problemi

​Apri la pagina del webhook

​Invia un lead

​Intestazioni

​Corpo

​Quale campagna riceve il lead

​Numeri senza prefisso

​Esempi di codice

​Risposta

​Errori

​Provalo

​Risoluzione dei problemi

Apri la pagina del webhook

Invia un lead

Intestazioni

Corpo

Quale campagna riceve il lead

Numeri senza prefisso

Esempi di codice

Risposta

Errori

Provalo

Risoluzione dei problemi