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

Ambiti e privilegio minimo

Ogni chiave è limitata agli ambiti selezionati. Usa chiavi di sola lettura quando possibile e una chiave separata per ogni integrazione. Un ambito di scrittura non concede automaticamente il corrispondente ambito di lettura.

assistants:read
assistants:write
analytics:read
artifacts:read
artifacts:write
billing:read
bookings:read
bookings:write
chat:write
connectors:read
connectors:write
conversations:read
conversations:write
knowledge:read
knowledge:write
leads:read
leads:write
telephony:read
telephony:write
widget:write

API-key rate limit

Each developer key is limited to 300 requests per rolling minute by default. The limit is atomic across all application instances and can be changed by the platform with API_KEY_RATE_LIMIT_PER_MINUTE. A rejected request returns 429; retry only after the window resets.

Elenco Assistenti

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

Crea un assistente

"POST" /api/assistants

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.

Creation validation and quota safety

Creation allowance is reserved atomically before insertion, so concurrent requests cannot exceed the monthly quota. Database insertion failures refund that reservation. A created assistant starts inactive in developer mode; call the setup endpoint and wait for its successful terminal event before publishing it.

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: "{}".

Upload, crawl, and index consistency

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

Send only the fields you want to change. The API rejects unknown keys and invalid nested data instead of silently storing configuration the widget cannot use.

{
  "designPreset": "corporate-soft",
  "primaryColor": "#1972F5",
  "theme": "dark",
  "bubbleStyle": "branded-drawer",
  "bubbleText": "Talk to our team",
  "welcomeMessages": [
    {
      "text": "Hello! How can I help?",
      "delay": 1.5
    }
  ],
  "welcomeSuggestions": [
    "View pricing",
    "Book a demo"
  ],
  "pageVisibility": {
    "mode": "exclude",
    "paths": [
      "/checkout/*"
    ]
  },
  "voiceEnabled": true,
  "voiceName": "Aoede",
  "copilotEnabled": true,
  "gdprConsentEnabled": true,
  "privacyPolicyUrl": "https://example.com/privacy"
}

Page visibility matching

Use exact paths such as /pricing, or append /* to include descendants such as /docs/*. include shows only matches; exclude hides matches; all ignores paths. Full URLs are normalized to their pathname by the widget.

Available voice names

Zephyr, Aoede, Kore, Leda, Callirrhoe, Despina, Erinome, Laomedeia, Achernar, Pulcherrima, Gacrux, Algenib, Sulafat, Puck, Charon, Fenrir, Orus, Enceladus, Iapetus, Umbriel, Algieba, Autonoe, Rasalgethi, Alnilam, Schedar, Sadachbia, Achird, Zubenelgenubi, Sadaltager

GET /api/assistants/:id/artifacts · PUT /api/assistants/:id/artifacts · PATCH /api/assistants/:id/artifacts

Artifacts are tool-driven UI. The model calls the enabled tool and Chirps renders it; integrations must send configuration JSON, never {{ARTIFACT: ...}} strings.

{
  "form": {
    "enabled": true,
    "title": "Request a quote",
    "description": "Collect the details needed for a quote.",
    "triggerRules": "When a visitor explicitly asks for a quote.",
    "fields": [
      {
        "key": "name",
        "label": "Full name",
        "type": "text",
        "required": true,
        "placeholder": "Jane Doe"
      },
      {
        "key": "email",
        "label": "Work email",
        "type": "email",
        "required": true
      }
    ],
    "submitLabel": "Request quote"
  },
  "booking": {
    "enabled": true,
    "title": "Book a consultation",
    "description": "Choose an available time.",
    "triggerRules": "When a visitor asks to book a meeting.",
    "services_enabled": false,
    "meetings_enabled": true,
    "requiresScheduling": true,
    "timezone": "Europe/Paris",
    "slotDuration": 30,
    "bufferMinutes": 10,
    "workingHours": {
      "monday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "tuesday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "wednesday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "thursday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "friday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "saturday": {
        "enabled": false,
        "start": "10:00",
        "end": "14:00"
      },
      "sunday": {
        "enabled": false,
        "start": "10:00",
        "end": "14:00"
      }
    },
    "blockedDates": [
      "2026-12-25"
    ],
    "meeting_intake_fields": [
      {
        "key": "email",
        "label": "Email",
        "type": "email",
        "required": true
      }
    ],
    "submitLabel": "Book meeting"
  },
  "card": {
    "enabled": false,
    "ctaLabel": "View details",
    "ctaUrl": "",
    "description": "",
    "triggerRules": ""
  },
  "csat_survey": {
    "enabled": true,
    "title": "How was your experience?",
    "description": "One-click feedback.",
    "triggerRules": "Only after the request is resolved."
  },
  "custom": []
}

Field schema

Booking service schema

Validation limits and scheduling rules

Tool-call prefill behavior

Start with GET /api/marketplace/connectors. Its provider definitions are the source of truth for credential fields, configuration fields, available tools, defaults, and required values; this keeps custom and future providers discoverable without a documentation release.

{
  "provider": "shopify",
  "name": "Shopify",
  "credentials": {}
}

1. Install the workspace connector record with POST /api/assistants/:id/connectors; credentials must be omitted or {}.
2. Read its exact field schema from GET /api/marketplace/connectors and activate it with POST /api/assistants/:id/connectors/:connectorId/activate.
3. Send configValues, optional enabledTools, and optional instructions. Chirps verifies non-custom connectors and discovers the tools before saving the integration.
4. Rotate secrets by calling the activation endpoint again. PUT only renames a named Custom API.
5. Use DELETE /api/assistants/:id/connectors with { connectorId } to disable it for one assistant. Use the nested DELETE .../:connectorId only to permanently remove it from the workspace and every assistant.

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>
  window.chirpsConfig = { assistantId: "YOUR_ASSISTANT_ID" };
</script>
<script src="https://chirps.cc/embed.js" async></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

Importante: le chiamate headless e server-to-server devono includere Authorization: Bearer <YOUR_CHIRPS_API_KEY>. Solo il widget installato nel browser usa il flusso pubblico vincolato all’origine. Non inserire mai una chiave API nel JavaScript frontend.

{

  "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": "Searching knowledge base..."}. Rappresenta gli stati di esecuzione dello strumento backend.
• `event: done`: contiene {"messageId": "uuid", "conversationId": "uuid", "message": "full text"}. Licenziato quando la generazione è completamente terminata.
• `event: error`: contiene {"error": "Error message"}. 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": "...", "isActive": true }

POST /api/chat/agent-message

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

Complete chat response contract

{
  "message": "I've opened the booking calendar for you.",
  "messageId": "uuid",
  "conversationId": "uuid",
  "artifacts": [
    {
      "type": "booking",
      "title": "Book a consultation"
    }
  ],
  "sources": []
}

A human takeover returns { message: null, conversationId, is_active_agent: true }. A streaming request can therefore return JSON before an SSE stream begins; check the response Content-Type.

Complete SSE event reference

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/:subscriptionId/assign assigns an already-purchased Chirps phone subscription to an assistant. Send { "assistantId": "uuid" }; send { "assistantId": null } to unassign it. This endpoint does not purchase or provision a new number.

POST /api/assistants/:id/outbound - Attiva la chiamata in uscita. Carico utile: { "phoneNumber": "+123...", "callReason": "Confirm the requested appointment", "conversationId": "optional-uuid" }

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

Public lead response

Lead objects contain id, assistant_id, conversation_id, session_id, name, email, phone, status, notes, artifact_id, ai_score, ai_summary, form_data, created_at, and the assistant business name. Internal voice-confirmation/idempotency identifiers are never returned.

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

DELETE /api/bookings/cancel?id=bookingId - Annulla una prenotazione attiva. Aggiungi &silent=true solo se l’integrazione deve sopprimere intenzionalmente l’e-mail di annullamento di riserva di Chirps.

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

Public booking response and time zones

Booking objects contain the public appointment, guest, status, notes, and timestamp fields plus business_timezone. Times are ISO-8601 instants; format them in the viewer's time zone while preserving the returned business zone for schedule context. Internal confirmation IDs, provider calendar-event IDs, and database range columns are omitted.

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"
}

What belongs in the public developer API

These routes accept a scoped Chirps API key and enforce its workspace boundary. Dashboard-only billing/OAuth routes, browser widget callbacks, provider webhooks, cron jobs, and internal MCP routes are intentionally excluded.

Assistants

Knowledge and training

Widget, artifacts and connectors

Conversations, leads and bookings

Telephony and account