Open in
התחברות מ-Twilio
נתבו שיחות מ-Twilio לסוכן ThunderPhone דרך SIP עם ה-CallSid, והחזירו אותן דרך ה-referUrl שלכם כאשר ההעברה נמצאת בכתובת ההעברה.
ה-TwiML שלכם מחייג לכתובת ה-SIP של הסוכן עם ה-CallSid של השיחה בכותרת.
כשהמתקשר זקוק לאדם, הסוכן שולח REFER של SIP, Twilio מעבירה את כתובת
ההעברה עם פרטי מסירת השיחה אל מטפל ה-referUrl שלכם, וה-TwiML שהמטפל שלכם מחזיר
קובע לאן המתקשר יועבר, למשל לתור Flex.
לפני שמתחילים
- סוכן ThunderPhone ומפתח API של הארגון.
- Twilio Programmable Voice, ומקום לארח בו TwiML ומטפל
referUrl: השרת שלכם, או TwiML Bin ופונקציית Twilio. Flex הוא אופציונלי.
1. צרו את נקודת הקצה של SIP
התגית <Sip> של Twilio מקבלת שם משתמש וסיסמה, לכן השתמשו בנקודת קצה רגילה:
curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"agent_id": 12, "name": "Twilio"}'שמרו מיד את ה-password מהתגובה; הוא מוצג פעם אחת בלבד. כדי
לקבל שיחות גם רק מ-Twilio, עיינו ב-הגבלת כתובות IP מקור.
2. שלחו שיחות עם הקשר
החזירו את ה-TwiML הזה עבור השיחה שברצונכם להעביר לסוכן:
<Response>
<Dial answerOnBridge="true" referUrl="https://YOUR_SERVER/thunderphone-refer">
<Sip username="tp409667538f83" password="YOUR_ENDPOINT_PASSWORD">sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tls?X-Call-ID={{CallSid}}</Sip>
</Dial>
</Response>;transport=tlsחשוב: Twilio משתמשת ב-UDP אלא אם מציינים אחרת.X-Call-IDנושא את ה-CallSid. Twilio אינה מתעדת כותרת מזהה שיחה משלה, לכן הוסיפו את זו: ThunderPhone שומרת אותה כ-external_call_idשל השיחה.{{CallSid}}פועל ב-TwiML Bin; מהשרת שלכם, הכניסו את ה-CallSidשל הבקשה הנכנסת.- הוסיפו הקשר נוסף באותה דרך, למשל
&X-Account-Id=12345. בתוך TwiML, כתבו&בתור&, מכיוון ש-&ללא קידוד אינו XML תקין. כל כותרת מגיעה להנחיה כמשתנה, כאן{{sip_x_account_id}}. Twilio מאפשרת כותרותx-ו-User-to-User, בקידוד אחוזים, כאשר אורך ה-URI כולו הוא עד 255 תווים והכותרות הן עד 1,024. referUrlמאפשר ל-Twilio לקבל את ה-REFERשל הסוכן; בלעדיו ההעברה נכשלת עם שגיאה 13802.answerOnBridge="true"משאיר את המתקשר מחובר עד שהיעד החדש עונה, כך שהעברה שנכשלה יכולה לעבור למסלול חלופי.
הווידג'ט חיבור שיחה אל של Studio אינו מתעד כותרות מותאמות אישית או
referUrl, לכן מ-Studio העבירו את השיחה ל-TwiML הזה, למשל באמצעות
ווידג'ט הפניית TwiML.
3. קבלו את השיחה בחזרה
הסוכן מבצע העברה באמצעות REFER, שכתובת ההעברה שלו כוללת את מזהה
המסירה ואת הכוונה. הוסיפו את מספר ההעברה הזה (ראו
הוספת מספר ההעברה
וכותרות בתוך כתובת ההעברה):
{
"name": "Twilio support",
"number": "sip:support@acme.sip.twilio.com",
"headers": {"X-Handoff-Id": "{{handoff_id}}", "X-Handoff-Intent": "{{handoff_intent}}"},
"headers_in_uri": true
}Twilio שולחת את הכתובת המלאה אל referUrl שלכם בתור ReferTransferTarget, לדוגמה
<sip:support@acme.sip.twilio.com?X-Handoff-Id=Zr3mY0b1Q9xWw2kPq4s7Tg&X-Handoff-Intent=billing_dispute>.
פונקציית הטיפול שלכם קוראת ממנה את הכותרות ומחזירה TwiML עבור היעד הבא של
המתקשר. חלק המשתמש של הכתובת (support) נתון לבחירתכם, כך שתוכלו
להוסיף מספר העברה אחד לכל יעד ולנתב לפיו.
פונקציית Twilio זו מכניסה את המתקשר לתור ב-Flex עם פרטי המסירה כמאפייני
משימה, ומחפשת את הסיכום לפי מזהה המסירה. החיפוש מתבצע בפונקציה משום
שווידג'ט בקשת ה-HTTP של Studio אינו יכול לשלוח את כותרת Authorization:
exports.handler = async (context, event, callback) => {
const target = (event.ReferTransferTarget || "").replace(/^<|>$/g, "");
const params = new URLSearchParams(target.split("?")[1] || "");
const handoffId = params.get("X-Handoff-Id") || "";
const attributes = { handoff_id: handoffId, intent: params.get("X-Handoff-Intent") || "" };
if (handoffId) {
const response = await fetch(
"https://api.thunderphone.com/v1/calls/handoff?handoff_id=" + encodeURIComponent(handoffId),
{ headers: { Authorization: "Bearer " + context.THUNDERPHONE_API_KEY } }
);
if (response.ok) {
const call = await response.json();
attributes.summary = (call.handoff && call.handoff.summary) || "";
}
}
const twiml = new Twilio.twiml.VoiceResponse();
twiml.enqueue({ workflowSid: context.FLEX_WORKFLOW_SID }).task({}, JSON.stringify(attributes));
callback(null, twiml);
};שמרו את מפתח ה-API במשתני הסביבה של הפונקציה. ראו חיפוש שיחה שנמסרה לשדות האחרים.
בדקו זאת
התקשרו למספר Twilio שמחזיר את ה-TwiML שלמעלה, בקשו מהסוכן להעביר אתכם לאדם,
וודאו שפונקציית הטיפול של referUrl מקבלת ReferTransferTarget עם שתי
הכותרות ושהמתקשר מגיע לתור. לאחר מכן פתחו את השיחה באמצעות
GET /v1/calls/{call_id}: הערך של external_call_id אמור להיות ה-CallSid.
מגבלות
- Twilio מגבילה את
Refer-Toל-256 תווים. ThunderPhone שומרת על אורך כתובת של 254 תווים ומשמיטה כותרת שאינה נכנסת, לכן הקפידו ששמות הכותרות והערכים יהיו קצרים. - Twilio אינה מתעדת קריאת כותרות ב-
BYE, לכן העברה חוזרת אינה יכולה לשאת את פרטי המסירה בחזרה אל Twilio. השתמשו ב-REFERכפי שמוצג למעלה. - Twilio אינה מקבלת
REFERבשיחה המחוברת באמצעות<Conference>או<Queue>, לכן חייגו אל הסוכן באמצעות<Dial><Sip>כפי שמוצג למעלה.