---
title: "הפעילו שיחות מ-Slack או מאפליקציית צ׳אט"
description: "בנו בוט משלכם עבור Slack, Teams או צ׳אט אינטרנטי שמתחיל שיחות, עוקב אחריהן בזמן אמת, מכוון את הסוכן ועונה על שאלותיו, באמצעות ה-API הציבורי."
---

באפשרותכם להפעיל סוכן מאפליקציית הצ'אט שהצוות שלכם כבר משתמש בה. הודעה
מתחילה שיחה. השיחה מתנהלת בזמן אמת בשרשור. תגובה בשרשור
מנחה את הסוכן. כשהסוכן זקוק להחלטה, הוא שואל אתכם שם
וממתין לתשובתכם.

ThunderPhone לא מארחת את הבוט הזה עבורכם. אתם (או סוכן הקוד שלכם) בונים
שרת קטן שמחבר את אפליקציית הצ'אט שלכם ל-API הציבורי. דף זה מציג
את הרכיבים. הם זהים עבור Slack, Microsoft Teams, Discord או דף צ'אט פרטי
באינטרנט; הדוגמאות משתמשות ב-Slack.

## איך הכול משתלב

| מה אתם עושים בצ'אט | מה הבוט שלכם קורא | מה קורה |
|---|---|---|
| שולחים "התקשרו ל-Comcast ובררו את זמן ההגעה המשוער לתיקון התקלה" | [`POST /v1/call`](/api-reference/outbound-calls) עם ההודעה בתור `context` | הסוכן מחייג. הבוט שלכם פותח שרשור עבור השיחה |
| עוקבים אחר השרשור | מקבל webhooks מסוג [`telephony.turn`](/he/webhooks/events) | כל שורה שהסוכן או האדם השני אומרים מופיעה בשרשור |
| מגיבים בשרשור במהלך השיחה | [`POST /v1/calls/{call_id}/whisper`](/api-reference/calls#whisper-to-the-agent) | הסוכן מקבל את ההערה שלכם באופן פרטי ופועל לפיה. האדם השני לעולם לא שומע אותה |
| עונים על שאלת הסוכן | [נקודת הקצה של הכלי](/he/guides/build-tool-integration) שלכם מחזירה את תשובתכם, או שולחת אותה מאוחר יותר באמצעות [`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result) | הסוכן ממשיך את השיחה עם התשובה; במצב המתנה האדם השני שומע מוזיקת המתנה בינתיים |
| קוראים את התוצאה | מקבל webhooks מסוג [`telephony.complete`](/he/webhooks/events) | הבוט שלכם מפרסם את הסיכום והתוצאה |

הבוט שלכם שומר מיפוי אחד: איזה שרשור צ'אט שייך לאיזה `call_id`.

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

- **מפתח API**, שנשמר בשרת שלכם ולעולם לא בדפדפן או בצ'אט.
  צרו אחד תחת **אינטגרציות → מפתחות API** (ראו
  [יצירת מפתח API לשרת](/he/guides/api-keys)).
- **מספר שמאפשר שיחות יוצאות וסוכן** עבור השיחות. ההודעה
  הופכת ל-`context` לכל שיחה, כך שסוכן כללי אחד מטפל בכל משימה.
- **שרת** שיכול לקבל webhooks, כגון Railway, Fly.io, Render או
  מארח משלכם.
- **נקודת קצה של webhook** שמפנה לשרת זה ומנויה ל-
  `telephony.turn` ול-`telephony.complete`. אירועי סבב נשלחים רק אל
  נקודות קצה שמציינות אותם. ראו [Webhooks](/he/webhooks/endpoints).
  אירועי סבב דורשים שהקלטת השיחות של הסוכן תהיה מופעלת, והשדה
  `summary` בסיום השיחה דורש את הגדרת **יצירת סיכום שיחה** של הסוכן; בלעדיהם
  שדות אלה נשארים ריקים.
- **אפליקציית צ'אט משלכם.** עבור Slack, צרו אפליקציה במרחב העבודה שלכם ב-
  [api.slack.com/apps](https://api.slack.com/apps).

<Tip>
  השתמשו באפליקציית Slack שאתם יוצרים עבור מרחב העבודה שלכם, וקבלו הודעות
  דרך API האירועים של Slack במקום לקרוא את היסטוריית הערוץ. Slack
  מגבילה באופן נוקשה קריאות של אפליקציות שמופצות למרחבי עבודה אחרים מחוץ
  ל-Marketplace שלה; אפליקציה שאתם בונים עבור מרחב העבודה שלכם אינה כפופה
  להגבלות אלה, ואירועים מגיעים אליכם בזמן התרחשותם ללא קריאות. היקפי
  הרשאה טיפוסיים לבוט: `chat:write`, `app_mentions:read`, `im:history` (הודעות
  ישירות), `channels:history` ו-`groups:history` (תגובות בשרשור בערוצים
  ציבוריים ופרטיים שהבוט נמצא בהם). הירשמו לאירועי הבוט
  `app_mention`, `message.im`, `message.channels` ו-`message.groups`, והפעילו
  את לשונית ההודעות תחת דף הבית של האפליקציה כדי שאנשים יוכלו לשלוח
  הודעות ישירות לבוט.
</Tip>

## 1. התחלת שיחה מהודעה

כאשר הבוט שלכם מקבל הודעה (הודעה ישירה או אזכור @),
אשרו מיד את הבקשה של Slack‏ (Slack מנסה שוב כל בקשה שלא
אושרה בתוך 3 שניות) ובצעו את השאר ברקע. בדקו
שהשולח מורשה לבצע שיחות, ואז התחילו את השיחה עם ההודעה בתור `context`:

```bash
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+18005550100",
    "agent_id":    12,
    "context":     "Matthew asked: get the outage ETA for account 4471. Wait on hold if needed.",
    "idempotency_key": "slack-D012AB3CD-1731000000.000100"
  }'
```

שמרו את `call_id` שהוחזר מול שרשור ה-Slack‏ (`channel` בתוספת
ה-`ts` של ההודעה) והשיבו בשרשור ("מחייגים…"). בנו את
`idempotency_key` מהערוץ ומה-`ts` של ההודעה (`ts` ייחודי
רק בתוך הערוץ שלו), כדי שאירוע Slack שמנוסה מחדש לא יבצע שיחה
שנייה. אם הבקשה מציינת אדם במקום מספר, הבוט שלכם
מאתר תחילה את המספר. ThunderPhone מחייגת רק אל ה-`to_number` שאתם שולחים.

## 2. מעקב אחר השיחה בשרשור

כל webhook מסוג `telephony.turn` כולל את `call_id`, את הדובר (`role`:
`assistant` עבור הסוכן, `user` עבור האדם האחר), את `text` ואת
ה-`position` של התור. אתרו את השרשור לפי `call_id` ופרסמו
את השורה.

- **אמתו כל webhook** לפני שתפעלו לפיו. ראו
  [אימות חתימות webhook](/he/guides/verify-webhook-signatures).
- **בצעו ביטול כפילויות לפי `event_id` של המעטפת וסדרו לפי `position`.**
  המסירה מתבצעת לפחות פעם אחת, ותורים עשויים להגיע בסדר שגוי.
- **אחדו שורות לאצווה** אם שיחה עמוסה עלולה להציף את השרשור; פרסום כל כמה
  שניות קריא יותר מהודעה אחת לכל שורה.

כאשר מגיע `telephony.complete`, פרסמו כיצד השיחה הסתיימה (ה-`status`
וה-`end_reason` שלה), את ה-`summary`, וכל נתון שחולץ, וסגרו את
השרשור. ראו [השלמת שיחה](/he/webhooks/call-complete) עבור השדות.

## 3. הכוונת השיחה מהשרשור

כאשר מישהו משיב בשרשור של שיחה פעילה, שלחו את התשובה כלחישה,
אלא אם הסוכן ממתין לתשובה על שאלה (שלב 4), ובמקרה זה התשובה
משמשת כמענה:

```bash
curl -X POST https://api.thunderphone.com/v1/calls/987654321/whisper \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ask whether they can waive the late fee."}'
```

הסוכן שומע אותה באופן פרטי ומשלב אותה בתור הבא שלו; האדם האחר
לעולם אינו שומע את הלחישה עצמה. לחישה היא באורך של 1 עד 1000 תווים. קוד
`409` פירושו שהשיחה כבר אינה פעילה: עדכנו את השרשור שהשיחה הסתיימה.

## 4. אפשרו לסוכן לשאול אתכם

תנו לסוכן כלי, לדוגמה `ask_owner` עם פרמטר `question`
אחד, שמפעיל קריאה לשרת שלכם. צרו אותו בתור
[חיבור API](/he/guides/build-tool-integration) וקשרו אותו לסוכן.
מזהה השיחה מועבר בכל בקשת כלי בכותרת `X-ThunderPhone-Call-ID` שלה.

יש שלוש דרכים לקבל את התשובה בחזרה.

**החזיקו את השיחה (עד 10 דקות).** הגדירו את הכלי למצב החזקה: `spec.wait_mode`
`"hold"` ואת `spec.timeout` לעד 600 שניות (ללא זמן קצוב, החזקה
נמשכת 20 שניות), באמצעות ה-
[API](/api-reference/integrations#timeout-and-wait-mode), או בקשו מ-Zeus
להגדיר אותם (לעורכי האפליקציה עדיין אין אף אחד מהשדות האלה). נקודת הקצה שלכם מפרסמת את השאלה לשרשור השיחה ומשיבה מיד
עם תוצאה בהמתנה:

```json
{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}
```

הצד השני שומע משפט אחד מהסוכן, ולאחר מכן מוזיקת המתנה. בתפריט
טלפוני או בתא קולי, הסוכן משתמש במקום זאת בעדכונים מדוברים, וסוכן בתקשורת
דו-כיוונית מלאה אינו משהה: הוא מקבל את התגובה הממתינה כתוצאה. כשהתשובה
מגיעה לשרשור, העבירו אותה באמצעות
[`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result):

```bash
curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "q-C012AB3CD-1731000042.000300", "result": {"answer": "Yes, book Tuesday at 10."}}'
```

מוזיקת ההמתנה נחלשת והסוכן ממשיך עם התשובה שלכם. אם אף אחד לא
עונה לפני ה-`timeout`, הסוכן מקבל הודעה שלא התקבלה תשובה ומציע
לצד השני את הצעדים הבאים. בזמן ששאלה ממתינה עבור שיחה, התשובה
הבאה בשרשור עונה עליה: העבירו אותה כתוצאת הכלי ואל תשלחו אותה גם
כלחישה (לחישה מגיעה לסוכן רק לאחר שהכלי מחזיר תוצאה). ראו
[המתנות ארוכות](/he/tools/overview).

**המתינו בתוך הבקשה (עד 3 דקות).** נקודת הקצה שלכם שולחת את השאלה,
ממתינה לתשובה ומחזירה אותה, למשל `{"answer": "Yes, book Tuesday at 10."}`.
הגדירו את `spec.timeout` של הכלי באמצעות ה-API, לעד 180 שניות (ברירת
המחדל היא 20). הגדירו לנקודת הקצה שלכם מועד אחרון משלה, מוקדם בכמה שניות
(לדוגמה 170 שניות), כך שכאשר אף אחד לא עונה היא עדיין תחזיר
משהו שהסוכן יכול לפעול לפיו, למשל
`{"answer": null, "note": "No reply yet. Offer to take a message."}`. כלי
שמגיע ל-`timeout` שלו מגיע לסוכן כשגיאה, והשרת המארח שלכם חייב
להשאיר בקשה פתוחה למשך זמן זה. בזמן ההמתנה, הסוכן אומר לצד השני
שהוא בודק, מציין שהוא עדיין מטפל בכך לאחר כ-12 שניות, ולאחר מכן
נותן עדכון קצר בערך כל 15 שניות. גם כאן אפשר להשתמש במצב השהיה:
הגדירו את `spec.wait_mode` ל-`"hold"` והצד השני ישמע מוזיקה
במקום העדכונים.

**ענו באמצעות לחישה.** נקודת הקצה שלכם שולחת את השאלה ומחזירה מיד,
למשל `{"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}`.
כשהתשובה מגיעה, שלחו אותה כלחישה (שלב 3), והסוכן
מגיב אליה מיד. השתמשו בכך עבור תשובות שעשויות להימשך יותר
מ-10 דקות. השיחה אינה מושהית: בהנחיה שלכם יש לציין לסוכן
מה לעשות בינתיים, למשל לשוחח עם האדם או להציע
להתקשר אליו בחזרה.

בכל מקרה, ציינו בהנחיה לסוכן מתי להשתמש בכלי ומה לומר
לצד השני בזמן ההמתנה:

```text
When you need Matthew's decision, use ask_owner with a short question.
Tell the person you're checking with Matthew and it may take a minute.
If there's no answer, offer to take a message or have Matthew call back.
```

## מגבלות שכדאי לתכנן לפיהן

- נקודת הקצה שלכם חייבת להשיב בתוך ה־`timeout` של הכלי, לכל היותר בתוך **180 שניות**. כלי במצב המתנה יכול
  להשאיר את השיחה בהמתנה עד **600 שניות** עם תוצאה ממתינה.
- בזמן שכלי ממתין, הסוכן אינו משיב לאדם השני. במצב המתנה
  הם שומעים מוזיקה; אחרת, עדכונים קוליים קצרים.
- לחישה מוגבלת לכל היותר ל־**1000 תווים**.
- המסירה של `telephony.turn` מתבצעת לפחות פעם אחת ועשויה להגיע שלא לפי הסדר.

## רשימת בדיקות אבטחה

- שמרו את מפתח ה־API בשרת שלכם.
- אמתו את החתימות של ThunderPhone בוובהוקים ובבקשות לכלים, ואת
  סוד החתימה של Slack בבקשות של Slack. שתי החתימות של ThunderPhone
  משתמשות בסודות שונים: מסירות וובהוק משתמשות בסוד של נקודת הקצה
  של הוובהוק עצמו, ובקשות לכלים משתמשות בסוד הוובהוק של הארגון שלכם
  מתוך [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook).
- החליטו מי רשאי להתחיל שיחות: בדקו את מזהה המשתמש ב־Slack לפני ביצוע שיחה.
- שיחות יוצאות כפופות לאותם כללים כמו כל שיחה אחרת. ראו
  [חוקי שיחות יוצאות](/he/guides/outbound-calling-laws).

## בנו זאת עם סוכן תכנות

הפנו את סוכן התכנות שלכם אל [שרת ה־MCP של התיעוד](/he/guides/docs-mcp) ואל
דף זה, ובקשו ממנו "בוט Slack עבור סוכן ThunderPhone שלי שפועל לפי
מדריך זה". Zeus, העוזר באפליקציית ThunderPhone, יכול להגדיר את
הצד של הסוכן (נקודת הקצה של הוובהוק, הכלי ושורות ההנחיה) ולכתוב
קוד התחלתי עבור הבוט בצ'אט.
