Le guide ultime de l'API du développeur

Tous les points de terminaison de l'API nécessitent une clé API Chirps dans l'en-tête « Autorisation ». Vous pouvez générer une clé API à partir du gestionnaire d'API dans la section Développeur de votre tableau de bord.

Authorization: Bearer <YOUR_CHIRPS_API_KEY>

Exemple de demande :

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

Gestion des erreurs standard

Portées et moindre privilège

Chaque clé est limitée aux portées sélectionnées. Utilisez des clés en lecture seule lorsque cela suffit et une clé distincte pour chaque intégration. Une portée d’écriture n’accorde pas automatiquement la portée de lecture correspondante.

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

Limite des clés API

Chaque clé développeur est limitée par défaut à 300 requêtes par minute glissante, de façon atomique sur toutes les instances. Un refus renvoie 429 ; attendez la réinitialisation avant de relancer.

Liste des assistants

Récupère une liste de tous les assistants associés à l'espace de travail de la clé API.

Créer un assistant

POST /api/assistants

Crée un nouvel assistant avec toutes les configurations de 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
}

Supprimer l'assistant

DELETE /api/assistants/:id

Supprime définitivement l'assistant et supprime en cascade tous ses nœuds de connaissances et son historique. Aucune charge utile requise.

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

Récupérez les statistiques d'utilisation, le nombre total de messages, les prospects capturés et les mesures d'engagement générales pour l'assistant spécifié. Le paramètre range est facultatif (nombre de jours, min 7, max 365, par défaut 30).

Réponse attendue

{

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

Gestion des nœuds de connaissances

GET /api/assistants/:id/nodes - Répertorie tous les nœuds de connaissances pour cet assistant.

POST /api/assistants/:id/nodes - Injectez manuellement un nouveau bloc de connaissances.

{

  "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 - Modifie le contenu d'un nœud existant ou bascule son état actif.

{

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

DELETE /api/assistants/:id/nodes/:nodeId - Supprime entièrement un bloc de connaissances.

POST /api/assistants/:id/nodes/:nodeId/re-crawl - Force le scraper à réexplorer l'URL associée à ce nœud et à mettre à jour son contenu. Charge utile : {}.

Formation IA

POST /api/assistants/:id/train - Compilez tous les nœuds de connaissances is_active et utilisez un orchestrateur d'IA pour synthétiser dynamiquement une nouvelle invite système maître. Charge utile : {}.

Upload, crawl, and index consistency

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

Envoyez uniquement les champs à modifier. L’API refuse les clés inconnues et les structures invalides au lieu d’enregistrer une configuration inutilisable.

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

Correspondance des pages

Utilisez un chemin exact comme /pricing ou /* pour les descendants comme /docs/*. include affiche uniquement les correspondances, exclude les masque et all ignore les chemins.

Voix disponibles

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

Les artefacts sont pilotés par des outils. Le modèle appelle l’outil activé et Chirps rend l’interface ; n’envoyez jamais de chaînes {{ARTIFACT: ...}}.

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

Option A : intégration Web (frontend)

Le moyen le plus simple d'intégrer l'assistant dans un site Web standard (WordPress, Shopify, React, etc.). Le code intégré est purement déterministe. Vous n'avez pas besoin d'un point de terminaison pour le récupérer. Déposez simplement ceci dans le <head> de votre site :

<script>
  window.chirpsConfig = { assistantId: "YOUR_ASSISTANT_ID" };
</script>
<script src="https://chirps.cc/embed.js" async></script>

Option B : intégrations sans tête (Backend / CRM / Bots)

Si vous créez un client personnalisé (comme un bot Discord, une intégration Telegram ou une application iOS native), vous n'utiliserez PAS Web Embed. Au lieu de cela, vous interagirez directement avec le point de terminaison /api/chat.

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

Important : les appels headless et serveur-à-serveur doivent inclure Authorization: Bearer <YOUR_CHIRPS_API_KEY>. Seul le widget installé dans le navigateur utilise le flux public lié à l’origine. Ne placez jamais une clé API dans du JavaScript côté client.

{

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

*(Prend également en charge multipart/form-data avec un champ file pour les pièces jointes si fileUploadEnabled est vrai).*

Mode 1 : réponse JSON standard (par défaut)

En envoyant une requête POST à ​​/api/chat (sans le paramètre stream), vous attendez la réponse complète de l'IA et recevez un objet JSON standard.

{

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

*(Si is_active_agent: true est renvoyé, un humain a repris le chat et message sera null.)*

Mode 2 : diffusion en continu des événements envoyés par le serveur (?stream=true)

En ajoutant « ?stream=true » à l'URL, vous recevez un flux d'événements envoyés par le serveur (SSE) en temps réel. Votre code doit écouter ces types d'événements spécifiques :

• `event: token` : contient {"text": "chunk"}. Déclenché pour chaque morceau du texte de réponse de l'IA.
• `event: status` : contient {"text": "Searching knowledge base..."}. Représente les états d’exécution de l’outil backend.
• `event: done` : contient {"messageId": "uuid", "conversationId": "uuid", "message": "full text"}. Lancé lorsque la génération est complètement terminée.
• `event: error` : contient {"error": "Error message"}. Lancé si des limites de débit ou des erreurs se produisent.

Points de terminaison de reprise en direct

GET /api/chat/sessions

Récupérez les sessions historiques.

POST /api/chat/toggle-agent

Suspendez l’IA pour la prise de contrôle humaine. Charge utile : { "sessionId": "...", "isActive": true }

POST /api/chat/agent-message

Envoyez un message humain. Charge 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

Mettre à jour la configuration principale

Modifiez les paramètres de base, la personnalité et les limites de grattage de l'assistant.

{

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

*Remarque : Tous les champs sont facultatifs. Envoyez uniquement les champs que vous souhaitez mettre à jour.*

Supprimer l'assistant

DELETE /api/assistants/:id

Supprime définitivement l’assistant et répercute la suppression sur tous les nœuds de connaissances, conversations et messages. Si l'assistant n'a jamais été complètement configuré, cela rembourse le quota de création mensuel.

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 - Déclenche un appel sortant. Charge utile : { "phoneNumber": "+123...", "callReason": "Confirm the requested appointment", "conversationId": "optional-uuid" }

GET /api/leads?id=leadId - Récupère les détails d'un seul prospect, y compris la transcription complète de la conversation.

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 - Récupère les détails d'une seule réservation, y compris la transcription de la conversation.

DELETE /api/bookings/cancel?id=bookingId - Annule une réservation active. Ajoutez &silent=true uniquement si votre intégration doit volontairement supprimer l’e-mail d’annulation de secours de Chirps.

POST /api/bookings/reschedule - Ajustez une réservation. Charge 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.

Récupérez l’utilisation du cycle de facturation de l’espace de travail, les limites du plan d’abonnement et le nombre total d’assistants. Remarque : Lors de l'utilisation d'une clé API, la requête est automatiquement étendue à l'espace de travail de la clé API ; vous n'avez pas besoin de fournir un teamId.

Réponse (`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"
}

Ce qui appartient à l’API développeur publique

Ces routes acceptent une clé API Chirps à portée limitée et appliquent la frontière de son espace de travail. Les routes de facturation/OAuth du tableau de bord, callbacks du widget, webhooks fournisseurs, tâches cron et routes MCP internes sont volontairement exclues.

Assistants

Connaissances et entraînement

Widget, artefacts et connecteurs

Conversations, prospects et réservations

Téléphonie et compte