Der ultimative Entwickler-API-Leitfaden

Alle API-Endpunkte erfordern einen Chirps-API-Schlüssel im „Authorization“-Header. Sie können einen API-Schlüssel vom API Manager im Entwicklerbereich Ihres Dashboards generieren.

Authorization: Bearer <YOUR_CHIRPS_API_KEY>

Beispielanfrage:

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

Standardfehlerbehandlung

Assistenten auflisten

Ruft eine Liste aller Assistenten ab, die dem Arbeitsbereich des API-Schlüssels zugeordnet sind.

Erstellen Sie einen Assistenten

POST /api/assistants

Erstellt einen neuen Assistenten mit allen Basiskonfigurationen.

{

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

Assistent löschen

DELETE /api/assistants/:id

Löscht den Assistenten dauerhaft und löscht nach und nach alle seine Wissensknoten und seinen Verlauf. Keine Nutzlast erforderlich.

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

Rufen Sie Nutzungsstatistiken, Gesamtnachrichten, erfasste Leads und allgemeine Engagement-Metriken für den angegebenen Assistenten ab. Der Parameter „Bereich“ ist optional (Anzahl der Tage, min. 7, max. 365, Standard 30).

Erwartete Antwort

{

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

Wissensknoten verwalten

GET /api/assistants/:id/nodes – Alle Wissensknoten für diesen Assistenten auflisten.

POST /api/assistants/:id/nodes – Manuelles Einfügen eines neuen Wissensblocks.

{

  "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 – Ändern Sie den Inhalt eines vorhandenen Knotens oder schalten Sie seinen aktiven Status um.

{

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

DELETE /api/assistants/:id/nodes/:nodeId – Einen Wissensblock vollständig löschen.

POST /api/assistants/:id/nodes/:nodeId/re-crawl – Zwingt den Scraper, die mit diesem Knoten verknüpfte URL erneut zu crawlen und ihren Inhalt zu aktualisieren. Nutzlast: „{}“.

KI-Training

„POST“ /api/assistants/:id/train – Kompilieren Sie alle „is_active“-Wissensknoten und verwenden Sie einen KI-Orchestrator, um dynamisch eine neue Master-System-Eingabeaufforderung zu synthetisieren. Nutzlast: „{}“.

Widget-Erscheinungsbild aktualisieren

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

Verfügbare Sprachnamen

• Weiblich: Zephyr, Aoede, Core, Leda, Callirrhoe, Despina, Erinome, Laomedeia, Achernar, Pulcherrima, Gacrux, Algenib, Sulfat
• Männlich: „Puck“, „Charon“, „Fenrir“, „Orus“, „Enceladus“, „Iapetus“, „Umbriel“, „Algieba“, „Autonoe“, „Rasalgethi“, „Alnilam“.

Benutzerdefiniertes Logo

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

Format: multipart/form-data mit file-Feld.

Option A: Web-Einbettung (Frontend)

Der einfachste Weg, den Assistenten in eine Standard-Website (WordPress, Shopify, React usw.) zu integrieren. Der Einbettungscode ist rein deterministisch. Sie benötigen keinen Endpunkt, um es abzurufen. Fügen Sie dies einfach in den „<head>“ Ihrer Website ein:

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

Option B: Headless-Integrationen (Backend / CRMs / Bots)

Wenn Sie einen benutzerdefinierten Client erstellen (wie einen Discord-Bot, eine Telegram-Integration oder eine native iOS-App), werden Sie die Web-Einbettung NICHT verwenden. Stattdessen interagieren Sie direkt mit dem Endpunkt „/api/chat“.

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

Hinweis: Dieser Endpunkt ist öffentlich und erfordert *nicht* den API-Schlüsselheader „Authorization: Bearer“. Die Authentifizierung erfolgt implizit über die „assistantId“.

{

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

*(Unterstützt auch „multipart/form-data“ mit einem „file“-Feld für Anhänge, wenn „fileUploadEnabled“ wahr ist.*

Modus 1: Standard-JSON-Antwort (Standard)

Indem Sie eine POST-Anfrage an „/api/chat“ senden (ohne den Stream-Parameter), warten Sie auf die vollständige KI-Antwort und erhalten ein Standard-JSON-Objekt.

{

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

*(Wenn „is_active_agent: true“ zurückgegeben wird, hat ein Mensch den Chat übernommen und „message“ ist „null“.)*

Modus 2: Streaming von vom Server gesendeten Ereignissen (?stream=true)

Durch Anhängen von „?stream=true“ an die URL erhalten Sie einen Server-Sent Events (SSE)-Stream in Echtzeit. Ihr Code sollte auf diese spezifischen Ereignistypen warten:

• `event: token`: Enthält {"text": "chunk"}. Wird für jeden Teil des Antworttextes der KI ausgelöst.
• `event: status`: Enthält {"text": "Suche in der Wissensdatenbank..."}. Stellt den Ausführungsstatus des Backend-Tools dar.
• `event: done`: Enthält {"messageId": "uuid", "conversationId": "uuid", "message": "full text"}. Wird ausgelöst, wenn die Generierung vollständig abgeschlossen ist.
• `event: error`: Enthält {"error": "Fehlermeldung"}. Wird ausgelöst, wenn Ratenbegrenzungen oder Fehler auftreten.

Live-Übernahme-Endpunkte

GET /api/chat/sessions

Rufen Sie historische Sitzungen ab.

POST /api/chat/toggle-agent

Unterbrechen Sie die KI, damit der Mensch sie übernimmt. Nutzlast: { "sessionId": "..." }

POST /api/chat/agent-message

Senden Sie eine menschliche Nachricht. Nutzlast: { "sessionId": "...", "message": "..." }

Kernkonfiguration aktualisieren

Ändern Sie die Kerneinstellungen, die Persona und die Scraping-Grenzen des Assistenten.

{

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

*Hinweis: Alle Felder sind optional. Senden Sie nur die Felder, die Sie aktualisieren möchten.*

Assistent löschen

DELETE /api/assistants/:id

Löscht den Assistenten dauerhaft und leitet die Löschung auf alle Wissensknoten, Konversationen und Nachrichten weiter. Wenn der Assistent nie vollständig eingerichtet wurde, wird das monatliche Erstellungskontingent zurückerstattet.

POST /api/phone-numbers/:id/assign – Geben Sie eine Nummer an. Nutzlast: „{}“.

POST /api/assistants/:id/outbound – Ausgehenden Anruf auslösen. Nutzlast: { "to": "+123...", "message": "..." }

GET /api/leads?id=leadId – Details eines einzelnen Leads abrufen, einschließlich des vollständigen Gesprächsprotokolls.

GET /api/bookings?id=bookingId – Details einer einzelnen Buchung abrufen, einschließlich des Konversationsprotokolls.

„POST“ /api/bookings/cancel – Eine aktive Buchung stornieren. Nutzlast: { "bookingId": "uuid" }

POST /api/bookings/reschedule – Passen Sie eine Buchung an. Nutzlast: „{ „bookingId“: „uuid“, „newTime“: „ISO-8601“ }`

Rufen Sie die Abrechnungszyklusnutzung des Arbeitsbereichs, die Abonnementlimits und die Gesamtzahl der Assistenten ab. Hinweis: Bei Verwendung eines API-Schlüssels wird die Anfrage automatisch auf den Arbeitsbereich des API-Schlüssels beschränkt; Sie müssen keine „teamId“ angeben.

Antwort („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"
}