שיחה מאפליקציה פועלת כמו שיחת אינטרנט: הסוכן שומע את המתקשר, יכול להציג כרטיסים ולקרוא לפונקציות של האפליקציה עצמה, והשיחה מופיעה ברשימה, מנותחת ומחויבת כמו כל שיחה אחרת. השרת שלכם שומר את מפתח ה-API ונותן לאפליקציה כתובת או אסימון חד־פעמיים עבור המשתמש המחובר.
| אפליקציה | איך היא מתחברת |
|---|---|
| iOS | שמע דרך WebSocket, עם ביטול ההד של iOS |
| Android | שמע דרך WebSocket, עם ביטול ההד של Android |
| React Native | אסימון שיחת אינטרנט והלקוח של Pipecat ל-React Native |
ב-iOS וב-Android, השרת שלכם מתחיל את השיחה ומשיב לאפליקציה עם ה-websocket_url שלה, שאפשר לפתוח פעם אחת תוך 15 דקות:
curl https://evasay.com/api/v1/voice/calls/websocket \
-X POST \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{ "agent_id": "AGENT_ID", "encoding": "pcm_s16le", "sample_rate": 16000, "user_id": "u_42", "page_tools": ["open_order"] }'
ב-React Native, הוא יוצר אסימון שיחת אינטרנט עם POST /api/v1/voice/web-calls ומשיב לאפליקציה עם token ו-web_call_url.
פתחו את websocket_url עם URLSessionWebSocketTask. הקליטו עם AVAudioEngine כשעיבוד הקול מופעל (כך הסוכן לא שומע את עצמו מהרמקול), המירו את המיקרופון ל-PCM של 16 ביט בקצב הדגימה של השיחה ושלחו אותו במסגרות בינאריות של 20 ms. המסגרות הבינאריות מ-EvaSay הן קול הסוכן באותו פורמט; נגנו אותן עם AVAudioPlayerNode.
let session = AVAudioSession.sharedInstance()
try session.setCategory(.playAndRecord, mode: .voiceChat, options: [.defaultToSpeaker])
try engine.inputNode.setVoiceProcessingEnabled(true)
let socket = URLSession.shared.webSocketTask(with: websocketURL)
socket.resume()
// microphone tap → 16 kHz Int16 mono → socket.send(.data(frame))
// socket.receive: .data → player.scheduleBuffer, .string → the call's events
מסגרות הטקסט הן אירועי השיחה ב-JSON. ב-clear (המתקשר קטע) עצרו את הנגן וזרקו את מה שבתור שלו; ב-ended סגרו את השקע. הוסיפו NSMicrophoneUsageDescription ל-Info.plist של האפליקציה.
פתחו את websocket_url עם OkHttp. הקליטו עם AudioRecord מ-VOICE_COMMUNICATION, שמפעיל את ביטול ההד של הטלפון, ונגנו עם AudioTrack עבור USAGE_VOICE_COMMUNICATION, שניהם 16 ביט מונו בקצב הדגימה של השיחה.
val record = AudioRecord(
MediaRecorder.AudioSource.VOICE_COMMUNICATION, 16000,
AudioFormat.CHANNEL_IN_MONO, AudioFormat.ENCODING_PCM_16BIT, bufferBytes)
val socket = OkHttpClient().newWebSocket(Request.Builder().url(websocketUrl).build(), listener)
// a thread reads 640 bytes (20 ms) at a time → socket.send(frame.toByteString())
// listener.onMessage(bytes) → track.write(...); onMessage(text) → the call's events
ב-clear השהו ורוקנו את ה-AudioTrack; ב-ended סגרו את השקע. האפליקציה צריכה את ההרשאות RECORD_AUDIO ו-INTERNET.
שלחו ב-POST את { "token": "…", "pageTools": ["open_order"] } אל https://evasay.com + web_call_url. ה-data בתגובה הוא החיבור של השיחה. כשה-transport שלו הוא cf, השיחה עוברת דרך Cloudflare Realtime ב-cfUrl: התחברו עם ה-transport של Pipecat מסוג SmallWebRTC ל-React Native (@pipecat-ai/react-native-small-webrtc-transport, עם @pipecat-ai/client-js), שהקמת החיבור שלו עוקבת אחרי האיתות של EvaSay שלמטה. כשבתגובה יש offerUrl, ה-transport ללא שינוי מתחבר אליו.
// Offer to cfUrl, then answer each offer Cloudflare makes at /api/cf/answer
// until the reply names the two data channels.
await pc.setLocalDescription(await pc.createOffer());
let reply = await post(cfUrl, { sdp: pc.localDescription.sdp, type: 'offer', requestData });
const pcId = reply.pc_id;
for (;;) {
if (reply.answer) await pc.setRemoteDescription({ type: 'answer', sdp: reply.answer });
if (reply.offer) {
await pc.setRemoteDescription({ type: 'offer', sdp: reply.offer });
await pc.setLocalDescription(await pc.createAnswer());
reply = await post(answerUrl, { pc_id: pcId, sdp: pc.localDescription.sdp });
} else if (reply.next) reply = await post(answerUrl, { pc_id: pcId });
else break;
}
// "to-agent" is the channel RTVI messages are sent on, "to-caller" the agent's.
dc = pc.createDataChannel('to-agent', { negotiated: true, id: reply.channels.toAgent });
pc.createDataChannel('to-caller', { negotiated: true, id: reply.channels.toCaller });
לפני ההצעה, הוסיפו transceiver שמע אחד (sendonly) עם המיקרופון; הרצועה של הסוכן מגיעה בהצעה של Cloudflare. Cloudflare לא צריכה מועמדי ICE מהאפליקציה, וחיבור שנותק מסיים את השיחה.
כרטיסים, פונקציות דף והודעות מגיעים כ-server-message של RTVI (evasay.cards, evasay.tool, evasay.notice). שלחו מילים מוקלדות עם send-text, ודיווחי דף ותשובות פונקציות כ-client-message מסוג evasay.context ו-evasay.tool_result ({ id, result } או { id, error }).
הוסיפו לסוכן פונקציה מסוג רצה בדף האינטרנט שלכם ("kind": "page") וענו לה באפליקציה: דרך ה-WebSocket השיחה שולחת {"type":"tool","id","name","arguments"} והאפליקציה משיבה {"type":"tool_result","id","result"}. הסוכן יכול לקרוא רק לפונקציות שהאפליקציה ציינה (page_tools או pageTools). הן רצות כשהמשתמש מחובר: בקשו אישור באפליקציה לפני כל דבר שעולה כסף או שאי אפשר לבטל.