Wixzel Voice로 WebSocket 기반 Flutter 음성 에이전트 추가하기

시작하기 전에 무엇이 필요한가요?

• 크레딧이 있는 Wixzel Voice API 키(서버에 보관).
• 세션을 발급할, 직접 관리하는 서버. 예제는 Node.js와 Express를 쓰지만 HTTPS 요청을 보낼 수 있는 언어라면 무엇이든 됩니다.
• 16비트 PCM을 스트리밍하는 녹음 플러그인(가능하면 8 kHz 모노, 에코 제거 지원)과 raw PCM을 재생할 수 있는 플레이어를 갖춘 Flutter 앱.

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

   응답에는 소켓 url, 이 에이전트에 대해 1분 동안 한 번만 쓸 수 있는 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 웹훅이 발생합니다. 웹 세션은 녹음되지 않습니다.

Wixzel Voice에서 이 빌드의 비용은 얼마인가요?

이 빌드에는 Wixzel Voice의 어떤 한도가 적용되나요?

• 전화 수준의 음질: 양방향 모두 8 kHz G.711 µ-law이며 광대역이 아닙니다.
• Dart SDK는 오디오를 녹음하거나 재생하지 않습니다. 마이크와 스피커는 앱이 직접 고른 플러그인으로 처리합니다.
• 세션은 전화 통화와 함께 계정의 동시 통화 한도(기본 5건)에 포함됩니다. 요청하면 한도를 늘려 드립니다.
• 세션은 기본 10분, 최대 1시간까지 이어지며, 2분 동안 아무 소리가 없으면 종료됩니다.
• 웹 세션은 녹음되지 않으며, 사용자를 상담원에게 넘길 두 번째 회선이 없습니다.