> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whappy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook

> Aggiungi lead a una campagna Whappy dai tuoi sistemi con una richiesta HTTP

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

1. Vai su **Integrazioni**. Il webhook è nel gruppo **Automazioni**.
2. Attiva il suo interruttore. Il webhook compare nella barra laterale e la sua scheda apre la sua pagina.
3. 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.

> [!WARNING]
>
> 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

```json theme={null}
{
  "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

1. `campaign_id`, se lo invii.
2. Altrimenti la campagna il cui nome corrisponde a `campaign`.
3. 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](#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

> [tab] cURL
>
> ```bash theme={null}
> 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"
>   }'
> ```

> [tab] JavaScript
>
> ```javascript theme={null}
> 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());
> ```

> [tab] Python
>
> ```python theme={null}
> 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):

```json theme={null}
{
  "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

1. Invia una richiesta con solo `name` e il tuo `phone`.
2. Controlla che la risposta sia `200`.
3. 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](https://docs.whappy.ai/it/integrations/whatsapp.md).

Serve aiuto? Consulta le [FAQ](https://docs.whappy.ai/it/support/faq.md) o [contatta l'assistenza](https://docs.whappy.ai/it/support/contact-support.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.