API per sviluppatori Zapier - Whappy Documentation

URL di base

https://api.whappy.ai/v1

Autenticazione

Tutte le richieste API richiedono autenticazione tramite API key. Includi la tua chiave negli header della richiesta:

X-API-Key: your_api_key_here

Ottenere la tua API key

Accedi al tuo account Whappy
Vai su Integrazioni → Zapier
Copia la tua API key dal pannello dell’integrazione

Custodisci la tua API key e non condividerla mai pubblicamente. Trattala come una password.

Endpoint

Configurare gli URL dei webhook

Configura gli URL a cui Whappy invierà i dati quando si verificano determinati eventi nelle conversazioni.

Impostare l’URL webhook per gli appuntamenti

Configura dove inviare i dati quando un lead fissa un appuntamento.

POST /zap/url/appointment

Corpo della richiesta:

{
  "targetUrl": "https://your-webhook-endpoint.com/appointment"
}

Header:

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

Codici di risposta:

200 OK: URL configurato correttamente
304 Not Modified: aggiornamento dell’URL non riuscito
400 Bad Request: dati della richiesta non validi
401 Unauthorized: API key mancante o non valida
500 Internal Server Error: errore del server

Esempio di richiesta:

curl -X POST https://api.whappy.ai/v1/zap/url/appointment \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"targetUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef/"}'

Impostare l’URL webhook per l’evento di chiusura

Configura dove inviare i dati quando un lead raggiunge un passaggio di “chiusura” nella conversazione.

POST /zap/url/close

Request Body:

{
  "targetUrl": "https://your-webhook-endpoint.com/close"
}

Example Request:

curl -X POST https://api.whappy.ai/v1/zap/url/close \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"targetUrl": "https://hooks.zapier.com/hooks/catch/123456/ghijkl/"}'

Rimuovere l’URL webhook degli appuntamenti

Rimuove l’URL webhook configurato per gli eventi di appuntamento.

DELETE /zap/url/appointment

Response Codes:

200 OK: URL rimosso correttamente
304 Not Modified: rimozione dell’URL non riuscita
401 Unauthorized: API key mancante o non valida
500 Internal Server Error: errore del server

Example Request:

curl -X DELETE https://api.whappy.ai/v1/zap/url/appointment \
  -H "X-API-Key: your_api_key_here"

Rimuovere l’URL webhook dell’evento di chiusura

Rimuove l’URL webhook configurato per gli eventi di chiusura.

DELETE /zap/url/close

Example Request:

curl -X DELETE https://api.whappy.ai/v1/zap/url/close \
  -H "X-API-Key: your_api_key_here"

Provare l’integrazione

Prova di connessione

Verifica connessione e autenticazione. Usa questo endpoint per controllare che l’integrazione funzioni.

POST /zap

Response Codes:

200 OK: connessione riuscita
401 Unauthorized: autenticazione fallita

Example Request:

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

Risposta positiva:

{
  "status": "success",
  "message": "Connection verified"
}

Ottenere dati di esempio

Recuperare dati di esempio

Ottieni un esempio della struttura dati che verrà inviata ai tuoi URL webhook. Indispensabile per configurare i flussi Zapier.

GET /zap/sample/{event_name}

Parametri:

event_name: appointment oppure close

Example Request:

curl -X GET https://api.whappy.ai/v1/zap/sample/appointment \
  -H "X-API-Key: your_api_key_here"

Esempio di risposta:

[
  {
    "lead_id": "lead_12345",
    "created_at": "2025-05-22T10:30:00Z",
    "phone": "+1234567890",
    "name": "John Doe",
    "lead_info_json": "{\"source\": \"website\", \"campaign\": \"spring_2025\"}",
    "collected_info_json": "{\"interests\": [\"product_a\", \"product_b\"], \"budget\": \"$5000\"}",
    "appointment": {
      "full_date": "2025-05-25T14:00:00Z"
    },
    "conversation_json": "{\"messages\": [...], \"duration\": 300}",
    "appointment_json": "{\"type\": \"consultation\", \"location\": \"online\"}"
  }
]

Modelli di dati

DataPayload

La struttura dati principale inviata ai tuoi URL webhook quando si verifica un evento:

Campo	Tipo	Obbligatorio	Descrizione
`lead_id`	string	Sì	Identificatore univoco del lead
`created_at`	string	Sì	Data e ora ISO 8601 di creazione del lead
`phone`	string	Sì	Numero di telefono del lead con prefisso internazionale
`name`	string	Sì	Nome completo del lead
`lead_info_json`	string	No	Stringa JSON con origine del lead e informazioni sulla campagna
`collected_info_json`	string	No	Stringa JSON con le informazioni raccolte durante la conversazione
`appointment`	AppointmentPayload	No	Dettagli dell’appuntamento (solo per gli eventi di appuntamento)
`conversation_json`	string	No	Stringa JSON con lo storico completo della conversazione
`appointment_json`	string	No	Stringa JSON con i dettagli dell’appuntamento

AppointmentPayload

Informazioni specifiche incluse negli eventi di appuntamento:

Field	Type	Required	Description
`full_date`	string	Sì	Data e ora ISO 8601 dell’appuntamento fissato

Campi JSON da interpretare

I campi stringa JSON contengono dati strutturati che puoi interpretare:

lead_info_json

{
  "source": "website",
  "campaign": "spring_2025",
  "utm_source": "google",
  "utm_medium": "cpc"
}

collected_info_json

{
  "budget": "$5000",
  "timeline": "Q2 2025",
  "interests": ["product_a", "product_b"],
  "company_size": "50-100",
  "decision_maker": true
}

conversation_json

{
  "messages": [
    {
      "timestamp": "2025-05-22T10:30:00Z",
      "sender": "ai",
      "content": "Ciao! Come posso aiutarti oggi?"
    },
    {
      "timestamp": "2025-05-22T10:31:00Z",
      "sender": "lead",
      "content": "Mi interessano i vostri servizi di web design"
    }
  ],
  "duration": 300,
  "steps_completed": 5
}

appointment_json

{
  "type": "consultation",
  "location": "online",
  "duration": "30 minutes",
  "calendar_event_id": "cal_12345",
  "meeting_link": "https://zoom.us/j/123456789"
}

Esempi di payload webhook

Evento Lead Closed

Quando un lead completa il funnel di conversazione:

{
  "lead_id": "lead_67890",
  "created_at": "2025-05-22T14:15:30Z",
  "phone": "+1987654321",
  "name": "Jane Smith",
  "lead_info_json": "{\"source\": \"facebook_ads\", \"campaign\": \"summer_promo\"}",
  "collected_info_json": "{\"budget\": \"$10000\", \"timeline\": \"Immediate\", \"service_type\": \"ecommerce\"}",
  "conversation_json": "{\"messages\": [...], \"duration\": 420, \"steps_completed\": 7}",
  "appointment_json": null
}

Evento Appointment Scheduled

Quando un lead fissa un appuntamento:

{
  "lead_id": "lead_54321",
  "created_at": "2025-05-22T16:45:00Z",
  "phone": "+1555123456",
  "name": "Mike Johnson",
  "lead_info_json": "{\"source\": \"website\", \"campaign\": \"consultation_page\"}",
  "collected_info_json": "{\"budget\": \"$7500\", \"timeline\": \"Q3 2025\", \"current_solution\": \"none\"}",
  "appointment": {
    "full_date": "2025-05-24T10:00:00Z"
  },
  "conversation_json": "{\"messages\": [...], \"duration\": 380}",
  "appointment_json": "{\"type\": \"discovery_call\", \"location\": \"zoom\", \"duration\": \"45 minutes\"}"
}

Flusso di integrazione

1. Configura gli endpoint webhook

Indica dove Whappy deve inviare i dati degli eventi:

# Configura il webhook degli appuntamenti
curl -X POST https://api.whappy.ai/v1/zap/url/appointment \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"targetUrl": "https://hooks.zapier.com/hooks/catch/123456/appointment/"}'

# Configura il webhook dell'evento di chiusura
curl -X POST https://api.whappy.ai/v1/zap/url/close \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"targetUrl": "https://hooks.zapier.com/hooks/catch/123456/close/"}'

2. Prova l’integrazione

Verifica la connessione API:

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

3. Ottieni dati di esempio

Capisci la struttura dati che riceverai:

# Esempio di evento appuntamento
curl -X GET https://api.whappy.ai/v1/zap/sample/appointment \
  -H "X-API-Key: your_api_key"

# Esempio di evento di chiusura
curl -X GET https://api.whappy.ai/v1/zap/sample/close \
  -H "X-API-Key: your_api_key"

4. Gestisci i dati del webhook

Nel gestore webhook riceverai la struttura DataPayload. Interpreta i campi JSON secondo necessità:

// Esempio di gestore webhook (Node.js)
app.post('/webhook/whappy-appointment', (req, res) => {
  const payload = req.body;

  // Interpreta i campi JSON
  const leadInfo = JSON.parse(payload.lead_info_json || '{}');
  const collectedInfo = JSON.parse(payload.collected_info_json || '{}');
  const appointmentInfo = JSON.parse(payload.appointment_json || '{}');

  // Elabora i dati
  console.log('New appointment scheduled:', {
    leadName: payload.name,
    phone: payload.phone,
    appointmentDate: payload.appointment.full_date,
    budget: collectedInfo.budget,
    source: leadInfo.source
  });

  res.status(200).send('OK');
});

Casi d’uso comuni

Integrazione CRM

Crea o aggiorna automaticamente i contatti nel tuo CRM:

// Esempio: invio a HubSpot
const hubspotContact = {
  properties: {
    firstname: payload.name.split(' ')[0],
    lastname: payload.name.split(' ')[1],
    phone: payload.phone,
    lead_source: JSON.parse(payload.lead_info_json).source,
    budget: JSON.parse(payload.collected_info_json).budget
  }
};

Integrazione con il calendario

Aggiungi gli appuntamenti ai sistemi di pianificazione:

// Esempio: creazione di un evento su Google Calendar
const calendarEvent = {
  summary: `Consultation with ${payload.name}`,
  start: {
    dateTime: payload.appointment.full_date,
    timeZone: 'America/New_York'
  },
  description: `Phone: ${payload.phone}\nBudget: ${JSON.parse(payload.collected_info_json).budget}`
};

Email marketing

Aggiungi i lead alle sequenze email:

// Esempio: aggiunta a una lista Mailchimp
const subscriber = {
  email_address: JSON.parse(payload.collected_info_json).email,
  status: 'subscribed',
  merge_fields: {
    FNAME: payload.name.split(' ')[0],
    PHONE: payload.phone,
    BUDGET: JSON.parse(payload.collected_info_json).budget
  }
};

Gestione degli errori

Codici di stato HTTP standard

Codice	Descrizione	Cosa fare
`200`	Successo	Richiesta completata correttamente
`304`	Not Modified	La risorsa non è stata modificata (negli aggiornamenti)
`400`	Bad Request	Controlla parametri e formato del corpo della richiesta
`401`	Unauthorized	Verifica che la tua API key sia corretta
`500`	Internal Server Error	Contatta l’assistenza se persiste

Formato della risposta di errore

{
  "detail": "Description of the error"
}

Errori frequenti

API key non valida

Risposta di errore:

{
    "detail": "Invalid authentication credentials"
}

Soluzione: verifica di aver copiato correttamente la API key dalla dashboard di Whappy.

URL webhook non valido

Error Response:

{
    "detail": "Invalid URL format"
}

Soluzione: assicurati che l’URL sia formattato correttamente e raggiungibile.

URL webhook irraggiungibile

Error Response:

{
    "detail": "Unable to reach webhook URL"
}

Soluzione: verifica che l’endpoint sia online e accetti richieste POST.

Limiti di frequenza

Limite generale: 100 richieste al minuto per API key
Configurazione webhook: 10 richieste al minuto
Dati di esempio: 50 richieste al minuto

Se ti servono limiti più alti per l’uso in produzione, contatta l’assistenza descrivendo il tuo caso d’uso.

Buone pratiche di sicurezza

Gestione delle API key

Conserva le chiavi in modo sicuro usando variabili d’ambiente
Non inserire mai una chiave nel controllo di versione
Ruota le chiavi periodicamente
Usa chiavi diverse per sviluppo e produzione

Sicurezza dei webhook

Valida i payload prima di elaborarli
Usa endpoint HTTPS
Implementa una gestione degli errori e un logging adeguati
Monitora i fallimenti dei webhook

Trattamento dei dati

Interpreta i campi JSON in sicurezza con blocchi try-catch
Valida i tipi di dato prima di elaborarli
Ripulisci i dati prima di archiviarli o inoltrarli
Rispetta le normative sulla privacy (GDPR)

Provare l’integrazione

1. Prova la connessione API

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

2. Configura webhook di prova

# Usa strumenti come ngrok per i test in locale
ngrok http 3000

# Configura il webhook con l'URL ngrok
curl -X POST https://api.whappy.ai/v1/zap/url/close \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_test_api_key" \
  -d '{"targetUrl": "https://abc123.ngrok.io/webhook/close"}'

3. Verifica i dati di esempio

# Recupera e verifica la struttura dei dati di esempio
curl -X GET https://api.whappy.ai/v1/zap/sample/close \
  -H "X-API-Key: your_test_api_key" | jq .

4. Monitora le chiamate webhook

Attiva il logging nel gestore webhook per monitorare i dati in arrivo:

app.post('/webhook/test', (req, res) => {
  console.log('Webhook received:', JSON.stringify(req.body, null, 2));
  res.status(200).send('OK');
});

Assistenza

Per supporto tecnico o domande sull’API:

Documentazione: parti dalla home della documentazione
Assistenza dalla dashboard: contatta il supporto dalla tua dashboard Whappy
Email: team@whappy.ai

Quando contatti l’assistenza

Includi queste informazioni:

La tua API key (solo i primi 8 caratteri)
Esempi di richiesta e risposta
Messaggi di errore e codici di stato HTTP
Data e ora del problema
Comportamento atteso e comportamento effettivo

Cronologia delle versioni

Versione 1.0

Prima release
Supporto per i webhook di appuntamento e chiusura
Endpoint per i dati di esempio
Autenticazione di base tramite API key
Configurazione e gestione degli URL webhook

SDK e librerie

Librerie ufficiali

Stiamo lavorando a SDK ufficiali per i linguaggi più diffusi. Nel frattempo, ecco alcuni esempi:

Node.js
Python
PHP

const axios = require('axios');

class WhappyAPI {
constructor(apiKey) {
this.apiKey = apiKey;
this.baseURL = 'https://api.whappy.ai/v1';
}

async setAppointmentWebhook(targetUrl) {
return axios.post(`${this.baseURL}/zap/url/appointment`,
{ targetUrl },
{ headers: { 'X-API-Key': this.apiKey } }
);
}

async testConnection() {
return axios.post(`${this.baseURL}/zap`, {},
{ headers: { 'X-API-Key': this.apiKey } }
);
}
}

import requests

class WhappyAPI:
def __init__(self, api_key):
self.api_key = api_key
self.base_url = 'https://api.whappy.ai/v1'
self.headers = {'X-API-Key': api_key}

def set_appointment_webhook(self, target_url):
return requests.post(
f'{self.base_url}/zap/url/appointment',
json={'targetUrl': target_url},
headers=self.headers
)

def test_connection(self):
return requests.post(
f'{self.base_url}/zap',
headers=self.headers
)

<?php
class WhappyAPI {
    private $apiKey;
    private $baseURL = 'https://api.whappy.ai/v1';

    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }

    public function setAppointmentWebhook($targetUrl) {
        $curl = curl_init();
        curl_setopt_array($curl, [
            CURLOPT_URL => $this->baseURL . '/zap/url/appointment',
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => json_encode(['targetUrl' => $targetUrl]),
            CURLOPT_HTTPHEADER => [
                'Content-Type: application/json',
                'X-API-Key: ' . $this->apiKey
            ],
        ]);
        return curl_exec($curl);
    }
}
?>

Tutto pronto per costruire la tua integrazione Zapier? Comincia provando la connessione API ed esplorando gli endpoint dei dati di esempio.

​URL di base

​Autenticazione

​Ottenere la tua API key

​Endpoint

​Configurare gli URL dei webhook

​Impostare l’URL webhook per gli appuntamenti

​Impostare l’URL webhook per l’evento di chiusura

​Rimuovere l’URL webhook degli appuntamenti

​Rimuovere l’URL webhook dell’evento di chiusura

​Provare l’integrazione

​Prova di connessione

​Ottenere dati di esempio

​Recuperare dati di esempio

​Modelli di dati

​DataPayload

​AppointmentPayload

​Campi JSON da interpretare

​lead_info_json

​collected_info_json

​conversation_json

​appointment_json

​Esempi di payload webhook

​Evento Lead Closed

​Evento Appointment Scheduled

​Flusso di integrazione

​1. Configura gli endpoint webhook

​2. Prova l’integrazione

​3. Ottieni dati di esempio

​4. Gestisci i dati del webhook

​Casi d’uso comuni

​Integrazione CRM

​Integrazione con il calendario

​Email marketing

​Gestione degli errori

​Codici di stato HTTP standard

​Formato della risposta di errore

​Errori frequenti

​Limiti di frequenza

​Buone pratiche di sicurezza

​Gestione delle API key

​Sicurezza dei webhook

​Trattamento dei dati

​Provare l’integrazione

​1. Prova la connessione API

​2. Configura webhook di prova

​3. Verifica i dati di esempio

​4. Monitora le chiamate webhook

​Assistenza

​Quando contatti l’assistenza

​Cronologia delle versioni

​Versione 1.0

​SDK e librerie

​Librerie ufficiali

URL di base

Autenticazione

Ottenere la tua API key

Endpoint

Configurare gli URL dei webhook

Impostare l’URL webhook per gli appuntamenti

Impostare l’URL webhook per l’evento di chiusura

Rimuovere l’URL webhook degli appuntamenti

Rimuovere l’URL webhook dell’evento di chiusura

Provare l’integrazione

Prova di connessione

Ottenere dati di esempio

Recuperare dati di esempio

Modelli di dati

DataPayload

AppointmentPayload

Campi JSON da interpretare

lead_info_json

collected_info_json

conversation_json

appointment_json

Esempi di payload webhook

Evento Lead Closed

Evento Appointment Scheduled

Flusso di integrazione

1. Configura gli endpoint webhook

2. Prova l’integrazione

3. Ottieni dati di esempio

4. Gestisci i dati del webhook

Casi d’uso comuni

Integrazione CRM

Integrazione con il calendario

Email marketing

Gestione degli errori

Codici di stato HTTP standard

Formato della risposta di errore

Errori frequenti

Limiti di frequenza

Buone pratiche di sicurezza

Gestione delle API key

Sicurezza dei webhook

Trattamento dei dati

Provare l’integrazione

1. Prova la connessione API

2. Configura webhook di prova

3. Verifica i dati di esempio

4. Monitora le chiamate webhook

Assistenza

Quando contatti l’assistenza

Cronologia delle versioni

Versione 1.0

SDK e librerie

Librerie ufficiali