עבודה נכונה עם API שיחות

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

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

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

המדריך עובר עליהן אחת אחת: איך לדעת שהייתה שיחה, איך למשוך הקלטה, מתי לבקש אותה, ומה עדיף לא לשמור אצלכם.

אל תדגמו את רשימת השיחות. הירשמו לאירוע

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

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

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

האירועים כוללים שיחה שהתחילה ושיחה שהסתיימה. כל האירועים, והנתונים שכל אחד מהם מביא איתו, מרוכזים בעמוד אחד.

"ומה אם אפספס אירוע?"

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

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

ויש גם גבול, וגם בקשות שמצליחות נספרות בו. הגבול נקבע כך שאינטגרציה סבירה לא מתקרבת אליו, אבל הוא כן מביא בחשבון את גודל החשבון: קו אחד עם 700 שיחות בחודש לא מייצר עשרות אלפי בקשות ל-API. חריגה תחסום את מפתח ה-API ותמנע בקשות נוספות.

שמרו את מזהה השיחה, לא את ההקלטה

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

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

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

בקשו את ההקלטה כשלוחצים עליה

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

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

// ברשימה: שום בקשה להקלטה
<button data-call-id="dg5hMcklT6">Play</button>

// רק בלחיצה:
btn.onclick = async () => {
  const url = await getRecordingUrl(btn.dataset.callId); // ttl: 10
  player.src = url;
  player.play();
};

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

שמרו על הפרטיות שלכם

הדרך השלישית, get-recording-urls, מחזירה קישור להקלטה. הפרמטר ttl קובע לכמה דקות הקישור תקף, והוא הדבר היחיד שמגן על ההקלטה.

POST /api/v1/calls/get-recording-urls/
{
  "config": { "ttl": 10 },
  "filter": { "call_ids": ["dg5hMcklT6"] }
}

ttl: 0 פותח את קובץ ההקלטה לגישה ציבורית, לצמיתות. כל מי שמגיע לכתובת שומע את השיחה, גם בעוד שנה, גם אם הקישור התגלגל למקום אחר. אין דרך לבטל אותו בדיעבד מלבד מחיקת ההקלטה עצמה.

ttl בין 1 ל-10 מחזיר קישור חתום שמפסיק לעבוד מעצמו. עשר דקות הן המקסימום, וזה בכוונה: קישור נוצר כדי שמישהו ילחץ עליו עכשיו, לא כדי שיישמר.

מה לא כדאי לנסות שוב

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

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

"אין הקלטה לשיחה" היא תשובה תקינה. השיחה קיימת, היא פשוט לא הוקלטה. סמנו אצלכם ואל תבקשו אותה שוב.

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

לסיכום

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

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

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

שאלות על עבודה מול ה-API