לקוח React#

גרסת בטא

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

examples/react במאגר הקוד של הספרייה הוא טלפון תוכנה פעיל ומימוש הייחוס של הספרייה: כל מה שמתואר בתיעוד מיושם בו בצורה עובדת. מדוגמה זו כדאי להתחיל. ניתן לנסות אותה בלי להתקין דבר בכתובת voip.green-api.com.

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

מה הדוגמה יודעת לעשות#

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

1. הורדת הדוגמה#

כדי להתקין את הדוגמה, יש להוריד את הקוד ממאגר הקוד ב-GitHub.

הורידו את הארכיון או השתמשו בשורת הפקודה:

git clone https://github.com/green-api/whatsapp-api-calls-client-js.git

2. הפעלת הלקוח#

בשורת הפקודה עברו לתיקיית הדוגמה והתקינו את התלויות:

cd whatsapp-api-calls-client-js/examples/react  
npm install  
npm run dev

מספיק להריץ את npm install פעם אחת, בהתקנה הראשונה.

Vite ידפיס את הכתובת שבה הופעל שרת הפיתוח — פתחו אותה בדפדפן.

כדי לעצור את השרת, הקישו Ctrl + C ולאחר מכן הקישו Y.

3. מילוי נתוני ההרשאה#

בהפעלה הראשונה, הדוגמה נפתחת עם טופס הכניסה Sign in.

הנתונים הדרושים נמצאים בקונסולת GREEN-API שלכם:

API URL — כתובת ה-API של המופע שלכם, לדוגמה https://1234.api.green-api.com
Instance ID — מזהה המופע (idInstance)
API token — הטוקן של המופע (apiTokenInstance)

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

כדי לצאת מהמופע, פתחו את הפרופיל — הסמל בפינה הימנית העליונה של הדף.

בחלון הפרופיל מוצגים מצב המופע (authorized), המספר שלו, המכשיר והכפתור Log out ליציאה.

4. קבלת שיחות נכנסות#

לאחר הכניסה, האפליקציה מתחילה לקבל שיחות נכנסות.

על שיחה נכנסת מדווח הפס Incoming call עם השם או המספר של המתקשר: הכפתור הירוק מקבל את השיחה, והאדום — דוחה אותה.

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

לאחר קבלת השיחה נפתח מסך השיחה: המצב In call, טיימר השיחה, מחווני עוצמת שמע — שלכם (YOU) ושל הצד השני (PEER), כפתור השתקת המיקרופון וכפתור הניתוק האדום.

בעיות ידועות ודרכים לפתרונן

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

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

5. ביצוע שיחות יוצאות#

חייגו את מספר הנמען במקלדת שמשמאל — קידומת המדינה נבחרת ברשימה שליד השדה Phone number — או מצאו את איש הקשר ברשימת אנשי הקשר שמימין והתקשרו ישירות מהשורה. לאחר מכן לחצו על כפתור החיוג הירוק.

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

אם השיחה לא התקיימה, ודאו שהחיבור נוצר — לשם כך יש בראש הדף את המחוון Connected — ושאין שגיאות במסוף המפתחים (developer console).

בחלק מהטלפונים, כדי לקבל שיחות נכנסות, WhatsApp חייב לפעול ברקע.

כיצד בנויה הדוגמה#

במה כדאי להתבונן קודם, לפי סדר מהלך השיחה:

קובץ	מה הוא מכיל
`src/voip/index.ts`	הלקוח והחיבור היחידים לכל האפליקציה, וכן הזרמים האחרונים ומצב החיבור — כדי שרכיב שנטען מאוחר יותר עדיין ימצא אותם
`src/hooks/useCallsConnection.ts`	אותו חיבור בתור state של React
`src/components/softphone.tsx`	חיוג: מדינה או `@lid`, עיצוב המספר, מקלדת
`src/common/address.ts`	מודל הכתובת — מספר ו-`@lid` הם חלופות, ומחייגים בדיוק אחת מהן
`src/components/incoming-call.tsx`	חלון השיחה הנכנסת
`src/pages/call.tsx`	מסך השיחה: הצד השני, טיימר, מחוונים, השתקת מיקרופון, ניתוק
`src/hooks/useVoip.ts`	הזרמים ורכיבי השמע שמנגנים אותם, מקושרים בשני הכיוונים
`src/voip/ringing.ts`	צלילי חיוג ורינגטון

שלושה דברים שקל לעשות לא נכון#

הם אינם ברורים מה-API, וכל טעות היא שקטה — שום דבר לא קורס, פשוט לא עובד.

קודם איתות, אחר כך שמע. dial() או accept() חייבים להסתיים לפני startAudioBridge(): השרת דוחה הצעה להעברת שמע שאינה שייכת לאף שיחה.
השמע מופעל לפני שמסך השיחה מופיע. עד שרכיבי השמע מוצגים, האירועים local-stream-ready ו-remote-stream-ready כבר התרחשו. לכן הדוגמה שומרת את הזרמים, ולא רק נרשמת לאירועים — אחרת השיחה תהיה ללא קול. כך גם לגבי מצב החיבור: הרשמה לאחר ש-connect כבר התרחש הייתה משאירה את האפליקציה עם הכיתוב "אין חיבור" בזמן שהחיבור פעיל לחלוטין.
השתקת המיקרופון היא מקומית, ויש לשחזר אותה. הטראק מ-local-stream-ready הוא אותו טראק שמועבר לצד השני, ולכן track.enabled = false הוא בדיוק מה שגורם לו להפסיק לשמוע אתכם. לאחר ניתוק החיבור באמצע שיחה, הספרייה מפעילה את השמע מחדש עם מיקרופון חדש ואינה מסיימת את השיחה עצמה, ולכן יש להעביר את ההשתקה לטראק החדש — אחרת המסך ימשיך להציג מצב שכבר אינו קיים.

פרטים נוספים — בסעיפים העברת שמע וכיצד ליצור שיחה יוצאת.

ספריות צד שלישי#

לספרייה עצמה אין תלויות בזמן ריצה. לקוח ה-React משתמש ב-React, Redux Toolkit, React Router, Ant Design, אייקוני MUI ו-libphonenumber-js.