Porta Kibo nel tuo prodotto

Autenticazione

Ogni richiesta deve includere la chiave API partner come Bearer token. Le chiavi sono emesse per partner, con scope di prodotto (kibo.chat, kibo.call) e mostrate una sola volta alla creazione — conservale in un secret manager e tienile lato server.

Authorization: Bearer nott_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

URL base: https://noonetotalk.com/api/v1 · JSON in entrata e in uscita · limiti di frequenza e quote mensili per piano (429 con Retry-After in caso di superamento).

Kibo Chat — POST /chat

Invia un messaggio dell'utente finale e ricevi una risposta testuale o vocale (MP3 in base64). Le conversazioni sono stateful per user_id: Kibo ricorda il contesto tra le richieste. I tuoi user ID sono isolati per partner e non collidono con quelli di altri partner.

curl https://noonetotalk.com/api/v1/chat \
  -H "Authorization: Bearer $NOTT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "usr_842", "message": "I had a rough day...", "audio": false }'

{
  "type": "text",
  "response": "I'm here for you. Want to tell me what happened?",
  "session_key": "..."
}

{
  "type": "audio",
  "response": "<base64 MP3>",
  "text": "I'm here for you. Want to tell me what happened?",
  "mime_type": "audio/mpeg",
  "session_key": "..."
}

Le risposte possono richiedere diversi secondi (LLM + TTS opzionale) — usa un timeout di almeno 120s.

Kibo Call — POST /call/tokens

Conversazione vocale in tempo reale con latenza sub-secondo e turn-taking naturale, via WebRTC con l'SDK ElevenLabs (web, iOS, Android, React Native). Il tuo server richiede un token a breve durata; il client si connette direttamente — nessun media passa dai tuoi server.

curl -X POST https://noonetotalk.com/api/v1/call/tokens \
  -H "Authorization: Bearer $NOTT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "usr_842" }'

Risposta:

{
  "token": "<ephemeral WebRTC token>",
  "agent_id": "...",
  "expires_in": 300,
  "nott_ref": "ptn_12__usr_842"
}

Client (esempio web — SDK anche per React Native, Swift, Kotlin):

import { Conversation } from "@elevenlabs/client";

// 1. Get a token from YOUR backend (never expose your NOTT API key client-side)
const { token, nott_ref } = await fetch("/your-backend/kibo-call-token")
  .then((r) => r.json());

// 2. Start the real-time voice session (WebRTC)
const conversation = await Conversation.startSession({
  conversationToken: token,
  connectionType: "webrtc",
  overrides: { dynamicVariables: { nott_ref } }, // required for billing attribution
});

// ... conversation.endSession() when done

I token sono monouso e scadono in pochi minuti — richiedine uno per chiamata. Le call sono fatturate per minuti connessi. Nessun WebRTC dalla tua parte? Usa Kibo Chat con "audio": true come fallback vocale request–response.

Consumo — GET /usage

Consultazione self-service del mese corrente (?month=YYYY-MM per lo storico).

{
  "month": "2026-07",
  "chat": { "messages": 12480, "audio_replies": 3120, "quota": 50000 },
  "call": { "tokens_issued": 950, "minutes": 1830.5, "quota_minutes": 5000 }
}

Errori

Gli errori seguono il formato { "error": { "code", "message" } }. Ripeti solo 502/timeout, con backoff esponenziale.

Buone pratiche

Tieni la chiave API solo lato server — i client devono parlare con il tuo backend. Usa user_id stabili e pseudonimi (niente email o PII): definiscono la memoria della conversazione. Kibo è un compagno di supporto emotivo, non un dispositivo medico — offri la tua UX di escalation in crisi dove richiesto dalla tua giurisdizione.