HTTP API
API לוואטסאפ, למספר האישי שלכם
Circles נותן לסקריפטים, לתהליכי n8n ולסוכנים שבניתם את השיחות שתבחרו בוואטסאפ, כ-JSON ב-HTTP עם מפתח. זה עובד עם המספר האישי הקיים, ו-Circles מריץ את החיבור בענן. ברירת המחדל היא קריאה, וכתיבה רק איפה שהרשיתם.
Circles הוא API ב-HTTP למספר וואטסאפ אישי: מקשרים את המספר כמכשיר מקושר, יוצרים מפתח, ופונים ל-https://app.usecircles.app/api/v1/agent עם Authorization: Bearer circ_..., לפי OpenAPI 3.1 ב-https://app.usecircles.app/api/openapi.json. ה-API קורא את השיחות שפתחתם, כולל הודעות קוליות כטקסט, ושולח, עונה עם ציטוט ומגיב באימוג'י ב-Pro, רק איפה שהרשיתם שליחה. יש מסלול Free ל-2 שיחות, ו-Pro ב-₪99 לחודש עם 14 ימים בחינם, נכון לאוקטובר 2026.
עודכן
ה-API במבט אחד
| ה-API של Circles | |
|---|---|
| כתובת בסיס | https://app.usecircles.app/api/v1/agent |
| הרשאה | Authorization: Bearer <key>: מפתח שנוצר בעמוד הסוכנים (circ_...) או טוקן OAuth של לקוח MCP. בלי עוגיות. |
| מפרט | OpenAPI 3.1 ב-https://app.usecircles.app/api/openapi.json, ותיעוד קריא ב-https://app.usecircles.app/api |
| פורמט | JSON. זמנים ב-UTC, במילישניות (at) וב-ISO 8601 (at_iso) |
| דפדוף | ממשיכים לפי pagination.next_url עד שהוא null, ו-has_more אומר אם יש עוד. כל עמוד בודק מחדש למה המפתח רשאי להגיע. |
| כמו ב-MCP | אותן תשע פעולות, אותן שיחות, אותן הרשאות ואותה תקרה |
| רק ב-API | תגובה עם ציטוט, תגובת אימוג'י, קבלות על כתיבה, ומציאה או פתיחה של שיחה לפי מספר |
| המספר שלכם | הוואטסאפ האישי שלכם, כמכשיר מקושר. בלי WhatsApp Business ובלי מספר נוסף. |
מההרשמה ועד הקריאה הראשונה
מקשרים את הוואטסאפ ב-Circles
מתחילים את תקופת הניסיון ומקשרים את המספר כמכשיר מקושר: קוד שמקלידים בטלפון, או QR שסורקים במחשב. אותו מספר, ואותו וואטסאפ בטלפון. ההיסטוריה מגיעה תוך 5 עד 15 דקות בערך, ואפשר לחבר את הסוכן בינתיים.
יוצרים מפתח
בעמוד הסוכנים של Circles בוחרים מפתח חדש, בוחרים את הסוכן (או ״אחר״), בוחרים API עם מפתח, מה המפתח מאפשר, וכמה זמן הוא עובד: בלי הגבלה, 90 יום או שנה.
מעבירים אותו בשתי הודעות
Circles נותן קודם הוראות בלי המפתח, ואחר כך את המפתח לבד, כך שהסוכן שומר אותו בסודות שלו, מחוץ לזיכרון ולצ'אט. לסקריפט או ל-n8n, מדביקים את המפתח ישר בהגדרות ההרשאות (credentials).
הקריאה הראשונה
GET https://app.usecircles.app/api/v1/agent/allowed_chatsעםAuthorization: Bearer circ_.... הרשימה הזאת היא כל העולם שהמפתח יכול להגיע אליו.
שתי קריאות, עם המפתח במשתנה סביבה:
curl -s "https://app.usecircles.app/api/v1/agent/allowed_chats" \
-H "Authorization: Bearer $CIRCLES_KEY"
curl -s "https://app.usecircles.app/api/v1/agent/catch_up?since=2026-10-26T00:00:00Z" \
-H "Authorization: Bearer $CIRCLES_KEY"Endpoints
הכול תחת /api/v1/agent, אלא אם כתוב אחרת. במסמך ה-OpenAPI יש כל פרמטר וכל תשובה.
| Endpoint | מה הוא עושה |
|---|---|
GET allowed_chats | השיחות שפתוחות לסוכנים, ומה המפתח הזה רשאי לעשות בכל אחת. זה כל העולם שלו. |
GET activity | באילו שיחות היה משהו חדש מאז זמן מסוים: ספירה, זמן אחרון, שולח אחרון, בלי טקסט |
GET catch_up | הודעות מאז זמן מסוים, בשיחה אחת או בכולן, שולחים לפי שם, הודעות קוליות עם התמלול שלהן. kind=voice|audio|recording מסנן. |
GET search | חיפוש טקסט בשיחה אחת או בכולן, כולל מה שנאמר בהודעות קוליות |
GET people | עם מי אתם מדברים בשיחות הפתוחות, ואיפה |
GET group_members | חברי קבוצה פתוחה אחת, לפי שם, עם סימון למנהלים, אף פעם לא מספרים |
GET documents | כל PDF, קובץ Word וגיליון שנשלחו בשיחות הפתוחות, עם המצב שלהם |
POST get_media | קובץ מצורף אחד. אם צריך, מבקש מהטלפון להעלות מחדש קובץ ישן יותר |
GET media/{ref}/status, content, view | המצב של קובץ מצורף, התוכן שלו, או הקובץ להצגה בדפדפן |
GET chats/{chat_ref}, messages/{message_ref} | פרטים, עם רשימת ה-actions המלאה שמותר לבצע שם |
POST chats/{chat_ref}/messages | שליחת טקסט, קובץ, או קובץ עם כיתוב |
POST messages/{message_ref}/replies | תגובה עם ציטוט, כמו בוואטסאפ. רק ב-API. |
POST messages/{message_ref}/reactions | תגובת אימוג'י. רק ב-API. |
GET writes/{submission_ref} | הקבלה על כתיבה, לקריאה בלבד |
GET recipients?to= | מציאת שיחה לפי מספר או לפי שם שמור מדויק, או פתיחת שיחה חדשה, כשהמספר שלכם מאפשר לפתוח שיחות |
POST /api/v1/connect/exchange | מחליף קוד חיבור חד-פעמי במפתח (כך Instinct מתחבר). הקריאה היחידה בלי Authorization. |
שליחה, ציטוטים ותגובות
בקשות כתיבה מגיעות מוכנות. בפרטים של שיחה או של הודעה יש actions: בקשות מלאות, עם method, כתובת, כותרות וגוף. מבצעים אחת כמו שהיא, מוסיפים את כותרת ה-Authorization, וממלאים רק את הטקסט, הקובץ או האימוג'י.
- אידמפוטנטי. כל כתיבה נושאת מזהה הגשה ש-Circles הנפיק, שקשור ליעד שלה. שימוש חוזר בו תוך 24 שעות לא יכול לשלוח שוב או לתפוס עוד מקום בתקרה היומית.
- אף פעם לא נשלח שוב. אם התשובה היא
delivery_unknown, בודקים את הקבלה ב-writes/{submission_ref}ואת השיחה לפני שמחליטים לשלוח שוב. Circles אף פעם לא שולח פעמיים הודעה שאולי כבר יצאה. - רק איפה שמותר. שליחות, ציטוטים ותגובות דורשים כולם הרשאת שליחה במפתח ושיחה שפתוחה לשליחה, וכולם נספרים באותה תקרה יומית. סירוב אומר מה חסר ומה עדיין מותר.
- ציטוט נכשל בבטחה. תגובה שאי אפשר לצטט בה נדחית, ולא נשלחת בלי ציטוט.
- לא נתמך: הצבעה בסקרים, הסרת תגובה, ציטוט של הודעה שאינה טקסט.
שליחת קובץ: מוסיפים אותו לגוף שפעולת השליחה נותנת. JPEG, PNG או WebP מגיעים כתמונה, MP4 כסרטון, וכל השאר כמסמך עם שם הקובץ.
"text": "Signed copy attached",
"file": {
"mime": "application/pdf",
"data_base64": "<the file, base64, up to about 3 MB>",
"filename": "nda.pdf"
}הודעות קוליות וקבצים
הודעה קולית (kind: voice) או קובץ שמע (kind: audio) מגיעים עם transcript, שתומלל אוטומטית בעברית ובאנגלית, כך שקוראים מה נאמר בלי להוריד את השמע. transcript_state הוא pending כל עוד התמלול בדרך.
קבצים מצורפים אחרים מגיעים כרשומה עם הפרטים שלהם: שם קובץ, סוג, גודל ו-status_url, ועוד content_url ברגע ש-Circles מחזיק את הקובץ. Circles מגיש את הקובץ, וקריאה של PDF או של תמונה היא העבודה של הקוד שלכם. קבצים שהיו בני יותר מ-25 יום בערך בזמן הקישור מגיעים מהטלפון לפי בקשה: שולחים POST ל-acquire_url, והטלפון, אם הוא מחובר, מעלה את הקובץ מחדש.
מגבלות
| מגבלה | ערך |
|---|---|
| הודעת טקסט | עד 65,536 תווים |
| כיתוב | עד 4,096 תווים |
| קובץ לשליחה | בערך 3 MB |
| קובץ להורדה | עד 50 MB לקובץ |
| תקרת שליחה יומית | למספר, לכל הסוכנים יחד: ברירת מחדל 5; אפשר 5, 10, 20 או בלי תקרה; נספר לפי יום UTC |
| אידמפוטנטיות של כתיבה | 24 שעות לכל מזהה הגשה |
| תוקף מפתח | בלי הגבלה (ברירת מחדל), 90 יום או שנה; אפשר לבטל מיד |
| קוד חיבור חד-פעמי | שימוש אחד, שעה אחת, עשרה ניסיונות בדקה לכל כתובת |
עוד על מגבלות ושגיאות: בתיעוד ה-API וה-MCP (באנגלית).
n8n, סקריפטים וסוכנים שבניתם
- n8n: צומת HTTP Request עם credential של כותרת,
Authorization: Bearer circ_.... צומת הוואטסאפ של n8n עצמו עובד עם חשבונות WhatsApp Business, וזה מגיע לשיחות האישיות שלכם. - סקריפטים: סיכום בוקר של שלוש קבוצות, ייצוא של כל מסמך שנשלח בקבוצת פרויקט, ספירה שבועית של מי ביקש מכם מה. בקשות GET פשוטות, JSON בחזרה.
- סוכן משלכם: כל דבר שיודע לפנות ב-HTTP. ההוראות ש-Circles נותן עם המפתח מסבירות לסוכן איך לקרוא, לדפדף ולפעול, ושאף שליחה לא נשלחת שוב.
- Dots מתחבר ככה גם: קודם ההוראות, ואחר כך המפתח בהודעה נפרדת.
מעדיפים MCP? אותן שיחות ואותן הרשאות נמצאות ב-https://app.usecircles.app/api/mcp: העמוד של WhatsApp MCP.
שאלות ותשובות
יש API לוואטסאפ האישי?
וואטסאפ מציע API רשמי רק ל-WhatsApp Business. Circles נותן למספר האישי שלכם API ב-HTTP: הוא מקשר אותו כמכשיר מקושר, ומגיש עם מפתח רק את השיחות שפתחתם.
זה ה-WhatsApp Business API?
לא. ה-Business API הוא הדרך הרשמית של Meta לעסקים לכתוב ללקוחות, ממספר עסקי. Circles עובד עם המספר האישי שלכם ועם השיחות הקיימות. ההבדל בפירוט.
אפשר להשתמש בזה עם n8n?
כן. משתמשים בצומת HTTP Request עם הכותרת Authorization: Bearer circ_... וכתובת הבסיס https://app.usecircles.app/api/v1/agent. צומת הווצאפ המובנה של n8n מיועד לחשבונות Business.
ניסיון חוזר ישלח את אותה הודעה פעמיים?
לא. כל כתיבה נושאת מזהה הגשה, ושימוש חוזר בו תוך 24 שעות לא יכול לשלוח שוב או לתפוס עוד מקום בתקרה. אם לא ברור אם ההודעה נמסרה, Circles אומר את זה ולא מנסה שוב מעצמו.
וואטסאפ יכול לנתק את המספר שלי בגלל זה?
חיבור כמכשיר מקושר דרך לקוח לא רשמי הוא מחוץ לתנאים של וואטסאפ, ואף אחד לא יכול להבטיח שמכשיר מקושר לא ינותק אף פעם. Circles קורא כברירת מחדל, מגביל שליחות, לא שולח הודעות תפוצה, ומחבר כל לקוח דרך כתובת IP ייעודית, שאף לקוח אחר לא משתמש בה.
כמה זה עולה?
ה-API כלול בכל המסלולים של Circles: Free, Starter ב-₪29 לחודש, ו-Pro ב-₪99 לחודש עם 14 ימים בחינם. שליחה דרך ה-API היא ב-Pro.
מחברים את הוואטסאפ לסוכן שלכם, היום.
14 ימים בחינם. מקשרים את המספר, בוחרים שיחות, ומחברים את Instinct בנגיעה אחת או את Claude, ChatGPT ו-Codex עם כתובת אחת.