Añade un agente de voz a Flutter por WebSocket con Wixzel Voice

¿Qué necesitas antes de empezar?

• Una clave de API de Wixzel Voice con crédito, guardada en tu servidor.
• Un servidor que controles para crear sesiones. El ejemplo usa Node.js y Express; sirve cualquier lenguaje que pueda hacer una petición HTTPS.
• Una app Flutter con un plugin de grabación que transmita PCM de 16 bits, idealmente a 8 kHz mono con cancelación de eco, y un reproductor que acepte PCM sin procesar.

¿Cómo construyes esto en Wixzel Voice, paso a paso?

1. 01Crea el agente una vez

   Este agente usa Gemini Live, un solo modelo en tiempo real que escucha, razona y habla:

   shellCopiar

   curl https://api.voice.wixzel.com/v1/agents \
     -H "Authorization: Bearer $WIXZEL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "In-app assistant",
       "system_prompt": "You are the voice assistant inside the Acme app. Answer in one or two short sentences.",
       "opening_message": "Hi, what can I help you with?",
       "voice": {
         "realtime": { "model": "google/gemini-live", "voice": "Kore" }
       }
     }'

   Nada de este agente es específico de la app: el mismo agente podría atender un número de teléfono. Guarda su id en tu servidor como AGENT_ID.

2. 02Crea una sesión en tu servidor

   La app nunca tiene tu clave de API. Pide la sesión a tu servidor, y tu servidor se la pide a la API con POST /v1/realtime/sessions, aquí mediante el SDK de TypeScript:

   server.mjsCopiar

   import express from 'express';
   import { WixzelVoice } from 'wixzel-voice';
   
   const wixzel = new WixzelVoice({ apiKey: process.env.WIXZEL_API_KEY });
   const app = express();
   
   // Replace with your own authentication. It must set req.userId.
   function requireUser(req, res, next) {
     req.userId = 'demo-user';
     next();
   }
   
   app.post('/voice/session', requireUser, async (req, res) => {
     const session = await wixzel.realtime.createSession({
       agent_id: process.env.AGENT_ID,
       max_duration_seconds: 300,
       metadata: { user_id: req.userId },
     });
     res.json(session);
   });
   
   app.listen(3000);

   La respuesta incluye la url del socket, un client_secret que funciona una sola vez, durante un minuto, para este agente, y audio_format: "mulaw_8000". Crear la sesión no cuesta nada; la facturación empieza cuando la app se conecta. max_duration_seconds limita la conversación, entre 10 y 3600 segundos, 600 por defecto. metadata se devuelve en el registro de la llamada y nunca se envía al modelo. allowed_origins solo importa en navegadores, así que una app nativa lo omite.

3. 03Conéctate desde la app

   Añade el SDK con flutter pub add wixzel_voice http y abre la sesión que devolvió tu servidor:

   voice_call.dartCopiar

   import 'dart:async';
   import 'dart:convert';
   import 'dart:typed_data';
   
   import 'package:http/http.dart' as http;
   import 'package:wixzel_voice/wixzel_voice.dart';
   
   /// Whatever your playback plugin offers, behind a small interface.
   abstract class PcmPlayer {
     void add(Int16List samples);
     void clear();
   }
   
   class VoiceCall {
     VoiceCall({required this.player, required this.onLine});
   
     final PcmPlayer player;
     final void Function(String role, String text) onLine;
   
     RealtimeConnection? _conn;
     StreamSubscription<Uint8List>? _mic;
     final List<int> _pending = [];
   
     /// [micBytes] is 16-bit little-endian PCM, 8 kHz mono, from your recording plugin.
     Future<void> start(Stream<Uint8List> micBytes) async {
       final res = await http.post(Uri.parse('https://api.example.com/voice/session'));
       final status = res.statusCode;
       if (status != 200) throw Exception('Could not start a voice session: HTTP $status');
       final session = RealtimeSession.fromJson(jsonDecode(res.body) as Map<String, dynamic>);
   
       final conn = RealtimeConnection.forSession(session);
       _conn = conn;
       conn.events.listen((event) {
         switch (event) {
           case RealtimeAudio(:final mulaw):
             player.add(mulawToPcm16(mulaw));
           case RealtimeAudioClear():
             player.clear(); // the user interrupted: drop queued audio
           case RealtimeTranscript(:final role, :final text):
             onLine(role, text);
           case RealtimeError(:final code, :final message):
             onLine('error', '$code: $message');
           case RealtimeEnded(:final reason):
             onLine('system', 'ended: $reason');
             _mic?.cancel();
           default:
         }
       });
       await conn.ready;
       _mic = micBytes.listen(_send);
     }
   
     void _send(Uint8List bytes) {
       final data = ByteData.sublistView(bytes);
       for (var i = 0; i + 1 < bytes.length; i += 2) {
         _pending.add(data.getInt16(i, Endian.little));
       }
       // 160 samples is 20 ms at 8 kHz, the frame size the server expects.
       while (_pending.length >= 160) {
         final frame = Int16List.fromList(_pending.sublist(0, 160));
         _pending.removeRange(0, 160);
         _conn?.sendAudio(pcm16ToMulaw(frame));
       }
     }
   
     Future<void> end() async {
       await _mic?.cancel();
       await _conn?.end();
     }
   }

   RealtimeConnection habla el protocolo y nada más: no abre el micrófono ni el altavoz, lo que mantiene el SDK libre de dependencias de plugins y te deja usar los plugins de audio que ya tienes. pcm16ToMulaw y mulawToPcm16 convierten entre PCM de 16 bits y lo que viaja por la red.

   Pide primero permiso para el micrófono: RECORD_AUDIO en Android y NSMicrophoneUsageDescription en iOS.

4. 04Activa la cancelación de eco y cuenta con audio de calidad telefónica

   Activa la cancelación de eco de la plataforma en el plugin de grabación. Sin ella, el agente se oye a sí mismo por el altavoz y se interrumpe.

   El audio es G.711 µ-law a 8 kHz en ambas direcciones, igual que una línea telefónica, porque las sesiones pasan por la misma ruta de medios que las llamadas. Es suficiente para voz, pero más limitado que el audio de banda ancha. Graba a 8 kHz si tu plugin lo permite, o vuelve a muestrear antes de pcm16ToMulaw, y reproduce el audio del agente a 8 kHz mono.

5. 05Consulta la sesión después

   Cada sesión es un registro de llamada con channel: "web":

   shellCopiar

   curl "https://api.voice.wixzel.com/v1/calls?channel=web&limit=5" \
     -H "Authorization: Bearer $WIXZEL_API_KEY"

   Una sesión web es entrante, no tiene from ni to, e incluye su duración, cost_micros y tu metadata; GET /v1/calls/{id} añade la transcripción. Termina con el mismo webhook callCompleted que envía una llamada telefónica. Las sesiones web no se graban.

¿Cuánto cuesta esto en Wixzel Voice?

¿Qué límites de Wixzel Voice se aplican a esto?

• Audio de calidad telefónica: G.711 µ-law a 8 kHz en ambas direcciones, no banda ancha.
• El SDK de Dart no captura ni reproduce audio. Tu app aporta el micrófono y el altavoz mediante los plugins que elija.
• Las sesiones cuentan para el límite de llamadas simultáneas de la cuenta, cinco por defecto, junto con las llamadas telefónicas. El límite se amplía a petición.
• Una sesión dura 10 minutos por defecto y como máximo una hora, y dos minutos de silencio la terminan.
• Las sesiones web no se graban, y no hay una segunda línea para pasar al usuario con una persona.