用 Wixzel Voice 透過 WebSocket 在 Flutter 中加入語音代理

開始之前需要準備什麼？

• 一把有點數的 Wixzel Voice API 金鑰，保存在您的伺服器上。
• 一台您能控制、用來建立工作階段的伺服器。範例使用 Node.js 和 Express；任何能發出 HTTPS 請求的語言都可以。
• 一個 Flutter 應用程式，搭配能串流 16 位元 PCM 的錄音外掛（最好是 8 kHz 單聲道並開啟回音消除），以及能接受原始 PCM 的播放器。

如何在 Wixzel Voice 上逐步打造？

1. 01先建立一次代理

   這個代理使用 Gemini Live，一個同時負責聆聽、推理和說話的即時模型：

   shell複製

   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" }
       }
     }'

   這個代理沒有任何專屬於應用程式的設定：同一個代理也可以接聽電話號碼。請將它的 id 以 AGENT_ID 保存在您的伺服器上。

2. 02在您的伺服器上建立工作階段

   應用程式絕不持有您的 API 金鑰。它向您的伺服器請求，您的伺服器再以 POST /v1/realtime/sessions 向 API 請求工作階段，這裡透過 TypeScript SDK 進行：

   server.mjs複製

   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);

   回應包含 socket 的 url、一個只能使用一次、有效一分鐘且僅適用此代理的 client_secret，以及 audio_format: "mulaw_8000"。建立工作階段不收費；計費從應用程式連線時開始。max_duration_seconds 限制對話長度，可設為 10 到 3600 秒，預設 600 秒。metadata 會原樣回傳在通話紀錄上，絕不會傳給模型。allowed_origins 只對瀏覽器有意義，因此原生應用程式不需要設定。

3. 03從應用程式連線

   用 flutter pub add wixzel_voice http 加入 SDK，然後開啟伺服器回傳的工作階段：

   voice_call.dart複製

   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 只處理通訊協定：它不會開啟麥克風或喇叭，讓 SDK 不必依賴任何外掛，您也可以沿用已有的音訊外掛。pcm16ToMulaw 和 mulawToPcm16 負責在 16 位元 PCM 與線路傳輸格式之間轉換。

   請先取得麥克風權限：Android 為 RECORD_AUDIO，iOS 為 NSMicrophoneUsageDescription。

4. 04開啟回音消除，並預期電話等級的音質

   在錄音外掛中開啟平台的回音消除。少了它，代理會透過喇叭聽到自己的聲音並打斷自己。

   雙向音訊都是 8 kHz 的 G.711 µ-law，與電話線路相同，因為工作階段與通話走同一條媒體路徑。這對語音來說足夠，但頻寬比寬頻音訊窄。如果外掛允許，請以 8 kHz 錄音，否則在 pcm16ToMulaw 之前重新取樣，並以 8 kHz 單聲道播放代理的音訊。

5. 05事後讀取工作階段

   每個工作階段都是一筆 channel: "web" 的通話紀錄：

   shell複製

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

   網頁工作階段屬於來電，沒有 from 或 to，並帶有時長、cost_micros 和您的 metadata；GET /v1/calls/{id} 會再加上逐字稿。它結束時會送出與電話通話相同的 callCompleted webhook。網頁工作階段不會錄音。

在 Wixzel Voice 上打造這個要花多少錢？

這個實作適用哪些 Wixzel Voice 限制？

• 電話等級音質：雙向皆為 8 kHz 的 G.711 µ-law，不是寬頻。
• Dart SDK 不會擷取或播放音訊。麥克風和喇叭由您的應用程式透過自選的外掛提供。
• 工作階段與電話通話一起計入帳號的同時通話上限，預設為五通。可申請提高上限。
• 工作階段預設持續 10 分鐘，最長一小時，靜默兩分鐘即會結束。
• 網頁工作階段不會錄音，也沒有第二條線路可以將使用者轉接給真人。