---
title: "התחברות מ-Twilio"
description: "נתבו שיחות מ-Twilio לסוכן ThunderPhone דרך SIP עם ה-CallSid, והחזירו אותן דרך ה-referUrl שלכם כאשר ההעברה נמצאת בכתובת ההעברה."
---

ה-TwiML שלכם מחייג לכתובת ה-SIP של הסוכן עם ה-`CallSid` של השיחה בכותרת.
כשהמתקשר זקוק לאדם, הסוכן שולח `REFER` של SIP, Twilio מעבירה את כתובת
ההעברה עם פרטי מסירת השיחה אל מטפל ה-`referUrl` שלכם, וה-TwiML שהמטפל שלכם מחזיר
קובע לאן המתקשר יועבר, למשל לתור Flex.

## לפני שמתחילים

- סוכן ThunderPhone ומפתח [API](/he/guides/api-keys) של הארגון.
- Twilio Programmable Voice, ומקום לארח בו TwiML ומטפל `referUrl`:
  השרת שלכם, או TwiML Bin ופונקציית Twilio. Flex הוא אופציונלי.

## 1. צרו את נקודת הקצה של SIP

התגית `<Sip>` של Twilio מקבלת שם משתמש וסיסמה, לכן השתמשו בנקודת קצה רגילה:

```bash
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 מקור](/he/guides/sip-addresses).

## 2. שלחו שיחות עם הקשר

החזירו את ה-TwiML הזה עבור השיחה שברצונכם להעביר לסוכן:

```xml
<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` של הבקשה הנכנסת.
- הוסיפו הקשר נוסף באותה דרך, למשל `&amp;X-Account-Id=12345`. בתוך
  TwiML, כתבו `&` בתור `&amp;`, מכיוון ש-`&` ללא קידוד אינו XML תקין. כל כותרת מגיעה
  להנחיה כמשתנה, כאן `{{sip_x_account_id}}`. Twilio מאפשרת כותרות `x-`
  ו-`User-to-User`, בקידוד אחוזים, כאשר אורך ה-URI כולו הוא עד 255 תווים
  והכותרות הן עד 1,024.
- `referUrl` מאפשר ל-Twilio לקבל את ה-`REFER` של הסוכן; בלעדיו ההעברה
  נכשלת עם [שגיאה 13802](https://www.twilio.com/docs/api/errors/13802).
  `answerOnBridge="true"` משאיר את המתקשר מחובר עד שהיעד החדש עונה,
  כך שהעברה שנכשלה יכולה לעבור למסלול חלופי.

הווידג'ט **חיבור שיחה אל** של Studio אינו מתעד כותרות מותאמות אישית או
`referUrl`, לכן מ-Studio העבירו את השיחה ל-TwiML הזה, למשל באמצעות
ווידג'ט **הפניית TwiML**.

## 3. קבלו את השיחה בחזרה

הסוכן מבצע העברה באמצעות `REFER`, שכתובת ההעברה שלו כוללת את מזהה
המסירה ואת הכוונה. הוסיפו את מספר ההעברה הזה (ראו
[הוספת מספר ההעברה](/he/guides/contact-centers/overview)
ו[כותרות בתוך כתובת ההעברה](/he/guides/call-transfers)):

```json
{
  "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`:

```js
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 במשתני הסביבה של הפונקציה. ראו
[חיפוש שיחה שנמסרה](/api-reference/calls#look-up-a-handed-off-call)
לשדות האחרים.

## בדקו זאת

התקשרו למספר 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>` כפי שמוצג למעלה.
