ET360

User Tools

Site Tools

Trace: • fonio
fonio

Fonio API Dokumentation

Willkommen bei der Fonio API für ET360. Diese Dokumentation beschreibt, wie Sie als Kunde über Fonio mit unserem Server kommunizieren können.

Einführung

Die Fonio API ermöglicht es Ihnen, als KI-Sprachassistent mit unserem ET360-System zu interagieren. Sie können:

* Fallinformationen abfragen - Holen Sie sich Details zu Fahrzeugen über das Kennzeichen * Anrufdaten übermitteln - Senden Sie Transkripte und Kontextdaten von Telefonkonversationen * Fallzuordnung durchführen - Verknüpfen Sie Anrufe mit bestehenden Fällen im System

Authentifizierung

Alle API-Endpunkte verwenden Basic Authentication. Sie benötigen einen API-Hash, der Ihnen von ET360 bereitgestellt wurde.

Header-Informationen

Fügen Sie diesen Header zu allen Ihren API-Anfragen hinzu: 

Authorization: Basic <Ihr-API-Hash>
Content-Type: application/json

Der Parametername für die Authentifizierung ist: PHONE_FONIO_INCOMING_REQUEST_HASH

API-Endpunkte

1. Fallinformationen nach Kennzeichen abfragen

Endpunkt: GET /ai/fonio/case-information-by-license-plate/{kennzeichen}

Beschreibung: Rufen Sie Informationen zu einem Fall ab, indem Sie das Fahrzeugkennzeichen angeben.

URL-Parameter:

Parameter Typ Beschreibung Beispiel
kennzeichen String Das deutsche Kfz-Kennzeichen (mit oder ohne Sonderzeichen) MTK-C-72, MTK C 72, MTK:C:72

Beispielanfrage: <url>GET https://your-server.com/ai/fonio/case-information-by-license-plate/MTK-C-72</url>

Beispielantwort: <json> { 

"type": "object",
"properties": {
  "LicensePlate": {
    "type": "string",
    "description": "Nummernschild des Fahrzeuges",
    "value": "MTK C 72"
  },
  "Location": {
    "type": "string",
    "description": "Standort des Fahrzeugs",
    "value": "Frankfurt am Main"
  },
  "OpeningHours": {
    "type": "string",
    "description": "Öffnungszeiten der Filiale",
    "value": "Mo-Fr 08:00-18:00"
  },
  "Price": {
    "type": "string",
    "description": "Preis für den Service",
    "value": "€150,00"
  },
  "DriverName": {
    "type": "string",
    "description": "Name des zugewiesenen Fahrers",
    "value": "Max Mustermann"
  },
  "DriverETA": {
    "type": "string",
    "description": "Geschätzte Ankunftszeit des Fahrers",
    "value": "15 Minuten"
  },
  "DriverDistance": {
    "type": "string",
    "description": "Entfernung des Fahrers zum Fahrzeug",
    "value": "5 km"
  }
}

} </json>

Hinweise: * Das Kennzeichen kann mit oder ohne Sonderzeichen (-, :, Leerzeichen) übermittelt werden * Die API normalisiert das Kennzeichen automatisch * Wenn kein Fall gefunden wird, wird null zurückgegeben

2. Anrufdaten übermitteln

Endpunkt: PATCH /ai/fonio/cases-by-phonenumber

Beschreibung: Senden Sie Transkripte und Metadaten von Telefonkonversationen. Das System versucht automatisch, den Anruf mit einem bestehenden Fall über die Telefonnummer zu verknüpfen.

HTTP-Methode: PATCH

Content-Type: application/json

Anfrage-Body:

<json> { 

"summary": "Kurze Zusammenfassung des Anrufs",
"fromNumber": "+491234567890",
"toNumber": "+499876543210",
"direction": "inbound",
"duration": 120,
"startTimestamp": "2024-01-15T10:30:00Z",
"endTimestamp": "2024-01-15T10:32:00Z",
"audioLink": "https://example.com/audio-recording.mp3",
"transcript": [
  {
    "id": "msg-001",
    "index": 0,
    "role": "user",
    "content": "Guten Tag, ich benötige Hilfe mit meinem Fahrzeug",
    "createdAt": "2024-01-15T10:30:15Z"
  },
  {
    "id": "msg-002",
    "index": 1,
    "role": "assistant",
    "content": "Gerne helfe ich Ihnen. Was ist Ihr Fahrzeugkennzeichen?",
    "createdAt": "2024-01-15T10:30:20Z"
  },
  {
    "id": "msg-003",
    "index": 2,
    "role": "user",
    "content": "Das Kennzeichen ist MTK C 72",
    "createdAt": "2024-01-15T10:30:35Z"
  }
],
"context": {
  "Name": "Max Mustermann",
  "LicensePlate": "MTK C 72",
  "Summary": "Kunde fordert Abschleppservice für beschädigtes Fahrzeug"
},
"disconnectReason": "Call completed successfully"

} </json>

Feldbeschreibungen:

Feld Typ Erforderlich Beschreibung
summary String Nein KI-generierte Zusammenfassung des Anrufs
fromNumber String Ja Telefonnummer des Anrufers (E.164-Format)
toNumber String Ja Telefonnummer des Empfängers (E.164-Format)
direction String Ja “inbound” (eingehend) oder “outbound” (ausgehend)
duration Integer Ja Anrufdauer in Sekunden
startTimestamp String Ja Anrufstartzeit (ISO 8601 Format)
endTimestamp String Ja Anrufendzeit (ISO 8601 Format)
audioLink String Nein URL zur Audioaufnahme
transcript Array Ja Zeitgestempelte Konversationstranskripte
transcript[].id String Ja Eindeutige Nachrichten-ID
transcript[].index Integer Ja Nachrichten-Sequenznummer
transcript[].role String Ja “user” oder “assistant”
transcript[].content String Ja Nachrichtentext
transcript[].createdAt String Ja Zeitstempel (ISO 8601)
context Object Nein Extrahierte strukturierte Daten
context.Name String Nein Kundenname
context.LicensePlate String Nein Fahrzeugkennzeichen
context.Summary String Nein Zusammenfassung
disconnectReason String Nein Grund für Anrufbeendigung

Beispielantwort:

Bei erfolgreicher Verarbeitung wird die Anfrage akzeptiert (HTTP 200). Das System: 1. Sucht nach einem passenden Fall basierend auf der Telefonnummer 2. Verknüpft die Anrufdaten mit dem gefundenen Fall 3. Speichert Transkript und Kontextinformationen

Fehlerantworten:

HTTP-Status Beschreibung
401 Authentifizierung fehlgeschlagen - Überprüfen Sie Ihren API-Hash
400 Ungültiges Anfrageformat - Überprüfen Sie die JSON-Struktur
404 Kein passender Fall gefunden - Die Telefonnummer ist nicht im System
500 Serverfehler - Bitte kontaktieren Sie den Support
Telefonnummern-Formatierung

Alle Telefonnummern sollten im E.164-Format übermittelt werden: 

+491234567890
+49 123 4567890

Das System akzeptiert verschiedene Formate und normalisiert sie automatisch: * +491234567890 ✓ * +49 123 4567890 ✓ * 0123 4567890 ✓ (wird automatisch konvertiert)

Beispiel-Implementierung

cURL Beispiel

# Fallinformationen abfragen
curl -X GET \
  https://your-server.com/ai/fonio/case-information-by-license-plate/MTK-C-72 \
  -H "Authorization: Basic your-api-hash" \
  -H "Content-Type: application/json"

# Anrufdaten übermitteln
curl -X PATCH \
  https://your-server.com/ai/fonio/cases-by-phonenumber \
  -H "Authorization: Basic your-api-hash" \
  -H "Content-Type: application/json" \
  -d '{
    "fromNumber": "+491234567890",
    "toNumber": "+499876543210",
    "direction": "inbound",
    "duration": 120,
    "startTimestamp": "2024-01-15T10:30:00Z",
    "endTimestamp": "2024-01-15T10:32:00Z",
    "transcript": [
      {
        "id": "msg-001",
        "index": 0,
        "role": "user",
        "content": "Ich brauche Hilfe",
        "createdAt": "2024-01-15T10:30:15Z"
      }
    ],
    "context": {
      "Name": "Max Mustermann",
      "LicensePlate": "MTK C 72"
    }
  }'

Python Beispiel

<python> import requests import json

# Konfiguration BASE_URL = “https://your-server.com” API_HASH = “your-api-hash”

headers = { 

  "Authorization": f"Basic {API_HASH}",
  "Content-Type": "application/json"

}

# Fallinformationen abfragen def get_case_by_license_plate(license_plate): 

  url = f"{BASE_URL}/ai/fonio/case-information-by-license-plate/{license_plate}"
  response = requests.get(url, headers=headers)
  return response.json()

# Anrufdaten übermitteln def submit_call_data(call_data): 

  url = f"{BASE_URL}/ai/fonio/cases-by-phonenumber"
  response = requests.patch(url, headers=headers, json=call_data)
  return response.status_code

# Beispielverwendung if name == “main”: 

  # Fall abfragen
  result = get_case_by_license_plate("MTK-C-72")
  print(json.dumps(result, indent=2))
  
  # Anrufdaten senden
  call_data = {
      "fromNumber": "+491234567890",
      "toNumber": "+499876543210",
      "direction": "inbound",
      "duration": 120,
      "startTimestamp": "2024-01-15T10:30:00Z",
      "endTimestamp": "2024-01-15T10:32:00Z",
      "transcript": [
          {
              "id": "msg-001",
              "index": 0,
              "role": "user",
              "content": "Guten Tag",
              "createdAt": "2024-01-15T10:30:15Z"
          }
      ],
      "context": {
          "Name": "Max Mustermann",
          "LicensePlate": "MTK C 72"
      }
  }
  
  status = submit_call_data(call_data)
  print(f"Status: {status}")

</python>

JavaScript/Node.js Beispiel

<javascript> const axios = require('axios');

const BASE_URL = 'https://your-server.com'; const API_HASH = 'your-api-hash';

const headers = { 

  'Authorization': `Basic ${API_HASH}`,
  'Content-Type': 'application/json'

};

Fallinformationen abfragen async function getCaseByLicensePlate(licensePlate) { const response = await axios.get( `${BASE_URL}/ai/fonio/case-information-by-license-plate/${licensePlate}`, { headers } ); return response.data; } Anrufdaten übermitteln async function submitCallData(callData) { 

  const response = await axios.patch(
      `${BASE_URL}/ai/fonio/cases-by-phonenumber`,
      callData,
      { headers }
  );
  return response.status;

}

Beispielverwendung (async () ⇒ { try { Fall abfragen 

      const result = await getCaseByLicensePlate('MTK-C-72');
      console.log(JSON.stringify(result, null, 2));
      
      // Anrufdaten senden
      const callData = {
          fromNumber: '+491234567890',
          toNumber: '+499876543210',
          direction: 'inbound',
          duration: 120,
          startTimestamp: '2024-01-15T10:30:00Z',
          endTimestamp: '2024-01-15T10:32:00Z',
          transcript: [
              {
                  id: 'msg-001',
                  index: 0,
                  role: 'user',
                  content: 'Guten Tag',
                  createdAt: '2024-01-15T10:30:15Z'
              }
          ],
          context: {
              Name: 'Max Mustermann',
              LicensePlate: 'MTK C 72'
          }
      };
      
      const status = await submitCallData(callData);
      console.log(`Status: ${status}`);
  } catch (error) {
      console.error('Fehler:', error.response?.data || error.message);
  }

})(); </javascript>

Best Practices

Datenqualität

* Transkripte: Senden Sie Transkripte so schnell wie möglich nach Anrufende * Zeitstempel: Verwenden Sie immer UTC-Zeit im ISO 8601 Format * Telefonnummern: Formatieren Sie Nummern im E.164-Standard * Kontextdaten: Extrahieren Sie relevante Informationen (Name, Kennzeichen) für bessere Fallzuordnung

Fehlerbehandlung

* Implementieren Sie Retry-Logik bei HTTP 500 Fehlern * Protokollieren Sie alle API-Antworten zur Fehleranalyse * Validieren Sie Ihre Anfragen vor dem Senden

Sicherheit

* Bewahren Sie Ihren API-Hash sicher auf * Verwenden Sie HTTPS für alle API-Anfragen * Rotieren Sie API-Hashes regelmäßig

Fehlerbehebung

Häufige Probleme

401 Unauthorized * Überprüfen Sie, ob der API-Hash korrekt ist * Stellen Sie sicher, dass Sie “Basic ” vor dem Hash verwenden

400 Bad Request * Validieren Sie Ihre JSON-Struktur * Stellen Sie sicher, dass alle erforderlichen Felder vorhanden sind * Überprüfen Sie das Datentypen (Strings, Integers, Arrays)

404 Not Found * Die Telefonnummer existiert nicht im System * Überprüfen Sie das Telefonnummernformat * Kontaktieren Sie den Kunden, um die richtige Nummer zu bestätigen

500 Internal Server Error * Temporärer Serverfehler * Versuchen Sie es später erneut * Bei anhaltenden Problemen: Kontaktieren Sie den ET360-Support

fonio.txt · Last modified: by admin
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki