تعمل مكالمة التطبيق مثل مكالمة الويب: يسمع الوكيل المتصل، ويمكنه عرض البطاقات واستدعاء دوال التطبيق نفسه، وتُدرج المكالمة وتُحلَّل وتُحتسب مثل أي مكالمة أخرى. يحتفظ خادمك بمفتاح API ويمنح التطبيق عنوانًا أو رمزًا لمرة واحدة للمستخدم المسجّل الدخول.
| التطبيق | طريقة الاتصال |
|---|---|
| iOS | الصوت عبر WebSocket، مع إلغاء الصدى في iOS |
| Android | الصوت عبر WebSocket، مع إلغاء الصدى في Android |
| React Native | رمز مكالمة ويب وعميل React Native من Pipecat |
في 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: اتصل باستخدام ناقل SmallWebRTC لـ React Native من Pipecat (@pipecat-ai/react-native-small-webrtc-transport مع @pipecat-ai/client-js)، على أن يتبع إعداد الاتصال فيه إشارات EvaSay أدناه. وعندما تحتوي الاستجابة على offerUrl، يتصل الناقل دون تعديل به.
// 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 });
قبل العرض، أضف مُرسِلًا-مستقبِلًا صوتيًا واحدًا (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). تعمل هذه الدوال بجلسة المستخدم: اطلب تأكيدًا في التطبيق قبل أي شيء يكلّف مالًا أو لا يمكن التراجع عنه.