La guida definitiva alle API per sviluppatori

Tutti gli endpoint API richiedono una chiave API Chirps nell'intestazione "Authorization". Puoi generare una chiave API dal Gestore API nella sezione Sviluppatori della dashboard.

Authorization: Bearer <YOUR_CHIRPS_API_KEY>

Esempio di richiesta:

curl -X GET https://chirps.cc/api/billing/usage \
  -H "Authorization: Bearer <YOUR_CHIRPS_API_KEY>" \
  -H "Content-Type: application/json"

Gestione degli errori standard

Elenco Assistenti

Recupera un elenco di tutti gli assistenti associati all'area di lavoro della chiave API.

Crea un assistente

"POST" /api/assistenti

Crea un nuovo assistente con tutte le configurazioni di base.

{

  "businessName": "Acme Corp",
  "businessUrl": "https://acme.com",
  "knowledgeBaseType": "both",
  "knowledgeBaseUrl": "https://acme.com/help",
  "knowledgeBaseText": "Raw text content of a document...",
  "knowledgeBaseFileName": "company_handbook.pdf",
  "language": "en",
  "isMultiLanguage": false,
  "tonePersonality": "professional",
  "isCustomPersonality": false,
  "supportEmail": "[email protected]",
  "maxPages": 5,
  "maxDepth": 2,
  "welcomeMessageDelay": 2
}

Elimina assistente

DELETE /api/assistants/:id

Elimina in modo permanente l'assistente ed elimina a catena tutti i relativi nodi di conoscenza e la cronologia. Nessun carico utile richiesto.

GET /api/analytics/overview?assistantId=uuid&range=30

Recupera statistiche sull'utilizzo, messaggi totali, lead acquisiti e metriche generali sul coinvolgimento per l'assistente specificato. Il parametro "intervallo" è facoltativo (numero di giorni, minimo 7, massimo 365, predefinito 30).

Risposta prevista

{

  "totalConversations": 1245,
  "totalMessages": 8420,
  "totalLeads": 156,
  "totalBookings": 42,
  "satisfactionRate": 94,
  "avgMessagesPerSession": 6.7,
  "avgSessionsPerDay": 41.5,
  "liveNow": 3,
  "onlineNow": 12,
  "dailySeries": [
    {
      "date": "2026-07-15",
      "conversations": 45,
      "messages": 310,
      "leads": 5,
      "bookings": 2
    }
  ],
  "agentStats": [
    {
      "name": "Jane Doe",
      "messagesSent": 120,
      "csat": 98
    }
  ]
}

Gestione dei nodi di conoscenza

GET /api/assistants/:id/nodes - Elenca tutti i nodi di conoscenza per questo assistente.

POST /api/assistants/:id/nodes - Inserisce manualmente un nuovo blocco di conoscenza.

{

  "title": "Return Policy",
  "refined_content": "We offer a 30-day return policy for all unused items...",
  "type": "text",
  "metadata": {}
}

PATCH /api/assistants/:id/nodes/:nodeId - Modifica il contenuto di un nodo esistente o ne attiva lo stato attivo.

{

  "title": "Updated Return Policy",
  "refined_content": "We offer a 60-day return policy now...",
  "is_active": true
}

DELETE /api/assistants/:id/nodes/:nodeId - Elimina completamente un blocco di conoscenza.

POST /api/assistants/:id/nodes/:nodeId/re-crawl - Forza lo scraper a ripetere la scansione dell'URL associato a questo nodo e ad aggiornarne il contenuto. Carico utile: "{}".

Formazione sull'intelligenza artificiale

POST /api/assistants/:id/train - Compila tutti i nodi di conoscenza is_active e utilizza un orchestratore AI per sintetizzare dinamicamente un nuovo prompt del sistema principale. Carico utile: "{}".

Aggiorna l'aspetto del widget

PATCH /api/assistants/:id/widget-config

{

  "primaryColor": "#000000",
  "position": "bottom-right",
  "language": "en",
  "welcomeMessage": "Hi! How can I help you today?",
  "title": "Acme Support",
  "theme": "light",
  "fontFamily": "default",
  "bubbleStyle": "circle",
  "bubbleText": "Chat with us",
  "headerSubtitle": "We typically reply instantly",
  "inputPlaceholder": "Type your message...",
  "privacyPolicyUrl": "https://acme.com/privacy",
  "voiceEnabled": true,
  "voiceName": "Fenrir",
  "welcomeMessageDelay": 2,
  "fileUploadEnabled": true,
  "dictationEnabled": true,
  "copilotEnabled": true,
  "welcomeSuggestions": ["Pricing plans", "Contact sales"],
  "pageVisibility": {
    "mode": "all",
    "paths": []
  }
}

Nomi vocali disponibili

• Femmina: Zephyr, Aoede, Core, Leda, Callirrhoe, Despina, Erinome, Laomedeia, Achernar, Pulcherrima, Gacrux, Algenib, Sulfat
• Maschio: Puck, Caronte, Fenrir, Orus, Encelado, Giapeto, Umbriel, Algieba, Autonoe, Rasalgethi, Alnilam

Logo personalizzato

POST /api/assistants/:id/widget-logo

Formato: multipart/form-data con campo file.

Opzione A: incorporamento Web (frontend)

Il modo più semplice per integrare l'assistente in un sito web standard (WordPress, Shopify, React, ecc.). Il codice di incorporamento è puramente deterministico. Non è necessario un endpoint per recuperarlo. Inserisci semplicemente questo nel <head> del tuo sito:

<script src="https://chirps.cc/widget.js" data-assistant-id="YOUR_ASSISTANT_ID_HERE"></script>

Opzione B: integrazioni headless (backend/CRM/bot)

Se stai creando un client personalizzato (come un bot Discord, un'integrazione di Telegram o un'app iOS nativa), NON utilizzerai il Web Embed. Interagirai invece direttamente con l'endpoint /api/chat.

POST /api/chat o /api/chat?stream=true

Nota: questo endpoint è pubblico e *non* richiede l'intestazione della chiave API Authorization: Bearer. L'autenticazione viene gestita implicitamente tramite "assistantId".

{

  "assistantId": "123e4567-e89b-12d3-a456-426614174000",
  "sessionId": "unique-session-id-for-user",
  "conversationId": "optional-uuid",
  "message": "Hello, I need help with my billing."
}

*(Supporta anche multipart/form-data con un campo file per gli allegati se fileUploadEnabled è true).*

Modalità 1: risposta JSON standard (impostazione predefinita)

Inviando una richiesta POST a "/api/chat" (senza il parametro stream), attendi la risposta AI completa e ricevi un oggetto JSON standard.

{

  "message": "Here is the information you requested...",
  "conversationId": "uuid-of-conversation",
  "messageId": "uuid-of-message"
}

*(Se viene restituito is_active_agent: true, un essere umano ha preso il controllo della chat e message sarà null.)*

Modalità 2: streaming di eventi inviati dal server (?stream=true)

Aggiungendo ?stream=true all'URL, riceverai un flusso SSE (Server-Sent Events) in tempo reale. Il tuo codice dovrebbe essere in ascolto di questi tipi di eventi specifici:

• `event: token`: contiene {"text": "chunk"}. Attivato per ogni porzione del testo di risposta dell'IA.
• `event: status`: contiene {"text": "Ricerca nella knowledge base..."}. Rappresenta gli stati di esecuzione dello strumento backend.
• `event: done`: contiene {"messageId": "uuid", "conversationId": "uuid", "message": "testo completo"}. Licenziato quando la generazione è completamente terminata.
• `event: error`: contiene {"error": "Messaggio di errore"}. Attivato se si verificano limiti di velocità o errori.

Endpoint di acquisizione in tempo reale

GET /api/chat/sessions

Recupera sessioni storiche.

POST /api/chat/toggle-agent

Metti in pausa l'IA per consentire l'acquisizione da parte degli esseri umani. Carico utile: { "sessionId": "..." }

POST /api/chat/messaggio-agente

Invia un messaggio umano. Carico utile: { "sessionId": "...", "message": "..." }

Aggiorna la configurazione principale

Modifica le impostazioni principali, la personalità e i limiti dell'assistente.

{

  "business_name": "Acme Corp",
  "business_url": "acme.com",
  "business_description": "We sell anvils.",
  "system_prompt": "You are a helpful assistant.",
  "language": "en",
  "tone_personality": "Friendly",
  "support_email": "[email protected]",
  "additional_instructions": "Never mention the Roadrunner.",
  "is_multi_language": true,
  "is_dev_mode": false,
  "is_active": true,
  "max_pages": 15,
  "max_depth": 2,
  "widget_config_merge": {
    "rateLimitEnabled": true
  }
}

*Nota: tutti i campi sono facoltativi. Invia solo i campi che desideri aggiornare.*

Elimina assistente

DELETE /api/assistants/:id

Elimina in modo permanente l'assistente e l'eliminazione a cascata si estende a tutti i nodi di conoscenza, conversazioni e messaggi. Se l'assistente non è mai stato completamente configurato, rimborsa la quota di creazione mensile.

POST /api/phone-numbers/:id/assign - Fornisci un numero. Carico utile: "{}".

POST /api/assistants/:id/outbound - Attiva la chiamata in uscita. Carico utile: { "a": "+123...", "messaggio": "..." }

GET /api/leads?id=leadId: recupera i dettagli di un singolo lead, inclusa la trascrizione completa della conversazione.

GET /api/bookings?id=bookingId - Recupera i dettagli di una singola prenotazione, inclusa la trascrizione della conversazione.

POST /api/bookings/cancel - Annulla una prenotazione attiva. Carico utile: { "bookingId": "uuid" }

POST /api/bookings/reschedule - Modifica una prenotazione. Carico utile: { "bookingId": "uuid", "newTime": "ISO-8601" }

Recupera l'utilizzo del ciclo di fatturazione dell'area di lavoro, i limiti del piano di abbonamento e il conteggio totale degli assistenti. Nota: quando si utilizza una chiave API, l'ambito della richiesta viene automaticamente limitato all'area di lavoro della chiave API; non è necessario fornire un teamId.

Risposta (`200 OK`):

{

  "planName": "Pro",
  "periodStr": "2023-10-01",
  "assistantCount": 3,
  "usage": {
    "message_count": 1450,
    "harvest_count": 12,
    "recrawl_count": 5,
    "train_count": 2,
    "assistants_created_count": 1,
    "voice_minutes_used": 0,
    "sms_count": 0,
    "email_count": 0,
    "whatsapp_count": 0
  },
  "limits": {
    "messages": 5000,
    "assistants": 5,
    "training": 50,
    "recrawls": 20
  },
  "workspaceOwnerId": "uuid"
}