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

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.

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

Mettre à jour l'apparence du 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": []
  }
}

Noms de voix disponibles

• Femelle : Zephyr, Aoede, Core, Leda, Callirrhoe, Despina, Erinome, Laomedeia, Achernar, Pulcherrima, Gacrux, Algenib, Sulfat
• Mâle : Puck, Charon, Fenrir, Orus, Encelade, Iapetus, Umbriel, Algieba, Autonoe, Rasalgethi, Alnilam

Logo personnalisé

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

Format : multipart/form-data avec le champ file.

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 src="https://chirps.cc/widget.js" data-assistant-id="YOUR_ASSISTANT_ID_HERE"></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

Remarque : Ce point de terminaison est public et ne nécessite *pas* l'en-tête de clé API « Autorisation : Bearer ». L'authentification est gérée implicitement via assistantId.

{

  "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": "Recherche dans la base de connaissances..."}. 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": "Message d'erreur"}. 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": "..." }

POST /api/chat/agent-message

Envoyez un message humain. Charge utile : { "sessionId": "...", "message": "..." }

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/:id/assign - Provisionner un numéro. Charge utile : {}

POST /api/assistants/:id/outbound - Déclenche un appel sortant. Charge utile : { "à": "+123...", "message": "..." }

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

GET /api/bookings?id=bookingId - Récupère les détails d'une seule réservation, y compris la transcription de la conversation.

POST /api/bookings/cancel - Annuler une réservation active. Charge utile : { "bookingId": "uuid" }

POST /api/bookings/reschedule - Ajustez une réservation. Charge utile : { "bookingId": "uuid", "newTime": "ISO-8601" }

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