Bravin AI

Einleitung

Die Bravin AI API ermöglicht es Ihnen, Chatbot-Funktionen in Ihre eigenen Anwendungen zu integrieren, benutzerdefinierte Workflows auszulösen und Daten bidirektional zu synchronisieren.

Was Sie erstellen können:

Benutzerdefinierte Dashboards
CRM-Integrationen
Automatisierte Workflows
Multi-Plattform-Bots
Analyse-Pipelines
E-Commerce-Automatisierungen

Der API-Zugang ist in den Pro- und Enterprise-Plänen verfügbar. Der kostenlose Plan bietet nur begrenzten Webhook-Support.

Authentifizierung

API-Schlüssel-Authentifizierung: Alle API-Anfragen erfordern einen API-Schlüssel im Authorization-Header.

Geben Sie API-Schlüssel niemals im Frontend-Code preis. Verwenden Sie sie ausschließlich auf Ihrem Backend-Server.

Authentifizierungsbeispiel

curl https://api.bravin.ai/v1/conversations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Authentifizierung (Fortsetzung)

API-Schlüssel generieren:

Melden Sie sich bei Bravin AI an
Gehen Sie zu Einstellungen → API-Schlüssel
Klicken Sie auf Neuen Schlüssel erstellen
Benennen Sie ihn aussagekräftig
Kopieren und sicher speichern

Schlüsseltypen:

Produktion – Für Live-Umgebung
Entwicklung – Zum Testen
Eingeschränkt – Begrenzte Berechtigungen

Schlüsselrotation: Best Practice: Schlüssel alle 90 Tage rotieren.

Einrichtung von Umgebungsvariablen

# .env file
BRAVIN_API_KEY=sk_live_abc123xyz789
BRAVIN_API_URL=https://api.bravin.ai/v1

REST-API-Endpunkte

Basis-URL: https://api.bravin.ai/v1

Hauptendpunkte:

Wichtige Endpunkte

# Unterhaltungen
GET    /conversations           # Unterhaltungen auflisten
GET    /conversations/:id       # Spezifische Unterhaltung abrufen
POST   /conversations           # Neue Unterhaltung erstellen
DELETE /conversations/:id       # Unterhaltung löschen

# Nachrichten
GET    /conversations/:id/messages  # Nachrichten abrufen
POST   /conversations/:id/messages  # Nachricht senden

# Wissensdatenbank
GET    /knowledge/documents     # Dokumente auflisten
POST   /knowledge/documents     # Dokument hochladen
DELETE /knowledge/documents/:id # Dokument löschen

# Analysen
GET    /analytics/summary       # Metriken abrufen
GET    /analytics/conversations # Unterhaltungsanalysen

REST-API-Beispiele

Nachricht senden:

POST /conversations/:id/messages

const axios = require('axios');

const response = await axios.post(
  'https://api.bravin.ai/v1/conversations/conv_123/messages',
  {
    content: 'What are your business hours?',
    userId: 'user_456',
    metadata: {
      source: 'mobile_app',
      channel: 'in-app-chat'
    }
  },
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.data);
// Ausgabe:
// {
//   "id": "msg_789",
//   "conversationId": "conv_123",
//   "content": "We're open Monday-Friday 9 AM - 6 PM EST.",
//   "role": "assistant",
//   "timestamp": "2024-03-14T10:30:00Z"
// }

Webhook-Einrichtung

Was sind Webhooks? Webhooks ermöglichen es Bravin AI, Echtzeit-Benachrichtigungen an Ihren Server zu senden, wenn Ereignisse auftreten.

Einrichtung:

Erstellen Sie einen Endpunkt auf Ihrem Server (z.B. https://yoursite.com/webhooks/bravin)
Gehen Sie zu Einstellungen → Webhooks
Klicken Sie auf Webhook hinzufügen
Geben Sie Ihre URL ein
Wählen Sie die Ereignisse aus, die Sie abonnieren möchten
Speichern

Ihr Endpunkt muss:

POST-Anfragen akzeptieren
Innerhalb von 5 Sekunden 200 OK zurückgeben
Webhook-Signatur überprüfen (Sicherheit)

Express.js Webhook-Handler

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

app.post('/webhooks/bravin', (req, res) => {
  // Signatur überprüfen
  const signature = req.headers['x-bravin-signature'];
  const payload = JSON.stringify(req.body);
  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  
  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }
  
  // Webhook verarbeiten
  const event = req.body;
  console.log('Received event:', event.type);
  
  switch (event.type) {
    case 'conversation.created':
      handleNewConversation(event.data);
      break;
    case 'message.received':
      handleNewMessage(event.data);
      break;
    // ... andere Ereignistypen
  }
  
  res.status(200).send('OK');
});

app.listen(3000);

Webhook-Ereignistypen

Verfügbare Ereignisse:

Konversationsereignisse:

conversation.created – Neue Konversation gestartet
conversation.updated – Konversationsmetadaten geändert
conversation.closed – Konversation als gelöst markiert
conversation.reopened – Geschlossene Konversation wiedereröffnet

Nachrichtenereignisse:

message.received – Benutzer hat eine Nachricht gesendet
message.sent – Agent hat geantwortet
message.failed – Nachrichtenzustellung fehlgeschlagen

Agentenereignisse:

agent.handoff.requested – KI hat die Übernahme durch einen Menschen angefordert
agent.confidence.low – Antwortsicherheit unter Schwellenwert

Feedback-Ereignisse:

feedback.received – Benutzer hat die Konversation bewertet
feedback.comment – Benutzer hat detailliertes Feedback hinterlassen

Beispiel-Ereignis-Payload

{
  "id": "evt_abc123",
  "type": "message.received",
  "timestamp": "2024-03-14T10:30:00Z",
  "data": {
    "conversationId": "conv_123",
    "messageId": "msg_456",
    "userId": "user_789",
    "content": "I need help with my order",
    "sentiment": "neutral",
    "intent": "order_inquiry",
    "confidence": 0.89
  }
}

Integrationsbeispiele

Beispiel 1: Synchronisierung mit CRM (HubSpot) Automatische Erstellung von CRM-Kontakten, wenn neue Konversationen beginnen:

CRM-Synchronisierung

async function handleNewConversation(eventData) {
  const { userId, email, name, conversationId } = eventData;
  
  // Kontakt in HubSpot erstellen oder aktualisieren
  await hubspot.contacts.create({
    email: email,
    properties: {
      firstname: name,
      lastname: '',
      chatbot_conversation_id: conversationId,
      lead_source: 'AI Chatbot',
      lifecycle_stage: 'lead'
    }
  });
  
  console.log(`Erstellter HubSpot-Kontakt für ${email}`);
}

Integrationsbeispiele (Fortsetzung)

Beispiel 2: E-Commerce-Bestellstatus Kunden können den Bestellstatus per Chatbot überprüfen:

Bestellstatus-Abfrage

app.post('/webhooks/bravin', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'message.received') {
    const message = event.data.content.toLowerCase();
    
    // Prüfen, ob nach Bestellstatus gefragt wird
    if (message.includes('order') && message.includes('status')) {
      // Bestellnummer aus Nachricht extrahieren
      const orderMatch = message.match(/#?(\d{5,})/);
      
      if (orderMatch) {
        const orderNumber = orderMatch[1];
        
        // Bestellung im System nachschlagen
        const order = await getOrderStatus(orderNumber);
        
        // Antwort über Bravin API senden
        await axios.post(
          `https://api.bravin.ai/v1/conversations/${event.data.conversationId}/messages`,
          {
            content: `Your order #${orderNumber} is ${order.status}. Estimated delivery: ${order.estimatedDelivery}`,
            role: 'assistant'
          },
          {
            headers: { 'Authorization': `Bearer ${process.env.BRAVIN_API_KEY}` }
          }
        );
      }
    }
  }
  
  res.status(200).send('OK');
});

Ratenbegrenzungen und Best Practices

Ratenbegrenzungen:

Kostenloser Plan: 100 Anfragen/Stunde
Pro-Plan: 1.000 Anfragen/Stunde
Enterprise-Plan: 10.000 Anfragen/Stunde

Best Practices:

Exponentielles Backoff implementieren
- Fehlgeschlagene Anfragen mit zunehmenden Verzögerungen wiederholen
- Max. 3 Wiederholungen
Antworten cachen
- Häufig aufgerufene Daten cachen (z.B. Wissensdatenbank)
- TTL: 5-15 Minuten
Anfragen stapeln
- Batch-Endpunkte verwenden, wenn verfügbar
- Beispiel: /conversations/batch für mehrere Konversationen
Nutzung überwachen
- X-RateLimit-Remaining-Header prüfen
- Warnungen einrichten, bevor Grenzwerte erreicht werden
Webhooks verwenden
- Nicht auf Updates pollen
- Webhooks sind Echtzeit und werden nicht auf Ratenbegrenzungen angerechnet

Kontaktieren Sie den Vertrieb für benutzerdefinierte Ratenbegrenzungen, wenn Sie einen höheren Durchsatz benötigen.

Fehlerbehebung

Häufige Probleme:

1. 401 Nicht autorisiert

Überprüfen Sie, ob der API-Schlüssel korrekt ist
Überprüfen Sie, ob der Schlüssel nicht abgelaufen ist
Stellen Sie sicher, dass das Präfix Bearer im Authorization-Header vorhanden ist

2. 429 Ratenbegrenzung überschritten

Exponentielles Backoff implementieren
Plan für höhere Grenzwerte aktualisieren
Anfragen wenn möglich stapeln

3. Webhook empfängt keine Ereignisse

Überprüfen Sie, ob die URL öffentlich zugänglich ist (nicht localhost)
Überprüfen Sie, ob die Firewall Bravin AI IPs zulässt
Stellen Sie sicher, dass der Endpunkt 200 OK zurückgibt
Signaturvalidierungslogik überprüfen

4. 500 Serverfehler

Statusseite prüfen: status.bravin.ai
Anfrage-Payload auf Gültigkeit prüfen
Bei anhaltenden Problemen den Support kontaktieren

Debug-Modus: Aktivieren Sie die ausführliche Protokollierung in Ihrem API-Client:

Protokollieren Sie niemals API-Schlüssel oder sensible Daten in der Produktion!

Debug-Protokollierung

axios.interceptors.request.use(request => {
  console.log('Anfrage starten', JSON.stringify(request, null, 2));
  return request;
});

axios.interceptors.response.use(response => {
  console.log('Antwort:', JSON.stringify(response.data, null, 2));
  return response;
});

API & Webhooks für kundenspezifische Automatisierung