Panoramica

Barby offre tre modalita' di integrazione per aggiungere un assistente AI al tuo sito web o applicazione:

Ogni integrazione richiede una API Key fornita dal pannello di amministrazione. La key e' legata al dominio del tuo sito e al tipo di servizio.

Voice Widget Vocale — barby.js

Il widget vocale aggiunge un bottone flottante al tuo sito. L'utente clicca, si apre un pannello con chat testuale e comunicazione vocale in tempo reale.

Integrazione

Aggiungi queste due righe prima della chiusura </body>:

<script src="https://barby.beyond-ai.me/livekit-client.umd.min.js"></script>
<script src="https://barby.beyond-ai.me/barby.js"
        data-key="LA_TUA_API_KEY"></script>

Parametri

Attributo	Obbligatorio	Descrizione
data-key	Si	API Key fornita dall'amministrazione
data-endpoint	No	URL dell'auth server (default: derivato dall'URL dello script)
data-voice	No	Nome della voce TTS da utilizzare
data-title	No	Titolo visualizzato nell'header del widget
data-name	No	Nome visualizzato dell'utente nella chat
data-position	No	bottom-right (default) o bottom-left

API JavaScript

// Aprire il widget
BarbyWidget.open();

// Chiudere il widget
BarbyWidget.close();

// Rimuovere completamente il widget
BarbyWidget.destroy();

Requisiti

• API Key di tipo Voice
• Browser moderno (Chrome, Firefox, Safari, Edge)

Chat Widget Chat — barby-chat.js

Il widget chat aggiunge un assistente testuale al tuo sito. Leggero e senza dipendenze esterne, risponde alle domande dei tuoi utenti basandosi sulla documentazione del tuo prodotto.

La chiave API resta sul tuo server — non viene mai esposta nel browser.

Integrazione in 2 passaggi

1. Proxy server-side

Copia il file barby-proxy.php (fornito con le credenziali) nella root del tuo sito web e configura le variabili:

<?php
// barby-proxy.php — da posizionare nella root del sito
define('BARBY_API_KEY', 'la-chiave-fornita');
define('BARBY_ORIGIN', 'https://tuosito.it');

// --- Non modificare sotto questa riga ---
header('Content-Type: application/json; charset=utf-8');

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    echo json_encode(['error' => 'Method not allowed']);
    exit;
}

$input = json_decode(file_get_contents('php://input'), true);
$messages = $input['messages'] ?? [];

if (empty($messages)) {
    http_response_code(400);
    echo json_encode(['error' => 'Nessun messaggio']);
    exit;
}

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => 'https://barby.beyond-ai.me/api/chat',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 120,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode(['messages' => $messages]),
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-API-Key: ' . BARBY_API_KEY,
        'Origin: ' . BARBY_ORIGIN,
    ],
]);
$response = curl_exec($ch);
$code = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

http_response_code($code ?: 502);
echo $response ?: json_encode(['error' => 'Servizio non raggiungibile']);

Per altri linguaggi (Node.js, Python, ecc.) il principio e' lo stesso: un endpoint POST che proxa la richiesta a https://barby.beyond-ai.me/api/chat con gli header X-API-Key e Origin.

2. Snippet nella pagina

Aggiungi questa riga prima della chiusura </body>:

<script src="https://barby.beyond-ai.me/barby-chat.js"
        data-title="Nome Assistente"
        data-agent-name="Nome Assistente"></script>

Il widget chiama automaticamente /barby-proxy.php sullo stesso dominio del sito. Se il proxy ha un percorso diverso, specificalo con data-proxy:

<script src="https://barby.beyond-ai.me/barby-chat.js"
        data-proxy="/api/chat-proxy.php"
        data-title="Nome Assistente"></script>

Parametri

Attributo	Obbligatorio	Descrizione
data-proxy	No	URL del proxy (default: /barby-proxy.php)
data-title	No	Titolo del widget (default: "Assistente")
data-agent-name	No	Nome dell'agente nella chat (default: "Barby")
data-position	No	bottom-right (default) o bottom-left

API JavaScript

// Aprire il widget
BarbyChatWidget.open();

// Chiudere il widget
BarbyChatWidget.close();

// Rimuovere completamente il widget
BarbyChatWidget.destroy();

Requisiti

• API Key di tipo Chat
• Server web con supporto PHP (o equivalente per il proxy)
• Qualsiasi browser moderno

Formato risposta del proxy

Il proxy deve restituire JSON. Il widget riconosce automaticamente questi formati:

// Formato OpenAI (restituito da barby)
{"choices": [{"message": {"content": "risposta..."}}]}

// Formato semplice (se il proxy elabora la risposta)
{"reply": "risposta..."}

// Oppure
{"message": "risposta..."}
{"content": "risposta..."}

Solo API

Per integrazioni personalizzate puoi utilizzare le nostre API direttamente, senza i widget predefiniti. Ideale per app mobile, applicazioni desktop o integrazioni con sistemi esistenti.

Con le key di tipo API Chat e API Voice puoi costruire la tua interfaccia personalizzata e comunicare direttamente con i nostri servizi. La documentazione tecnica completa delle API viene fornita insieme alle credenziali.

Requisiti

• API Key di tipo API Chat o API Voice (a seconda del servizio)

Piani e Limiti

Ogni API Key e' associata a un piano che definisce i limiti di utilizzo:

Piano	Richieste/min	Sessioni max	Sessioni/giorno	Durata max	Token TTL
Testing	120	5	50	5 min	5 min
Basic	30	∞	∞	∞	10 min
Pro	60	∞	∞	∞	15 min
Advanced	120	∞	∞	∞	20 min
Expert	240	∞	∞	∞	30 min
Max	∞	∞	∞	∞	60 min

Piani personalizzati disponibili su richiesta.

Dashboard

Accedi alla dashboard con le credenziali fornite per:

• Monitorare l'utilizzo delle API (oggi, mese, totale)
• Visualizzare il piano attivo e i limiti
• Consultare le API Key associate al tuo account

Per richiedere nuove API Key, modifiche al piano o supporto tecnico, contatta info@beyond-ai.me.