API — שליחת הודעות ואוטומציה

שליחת תבנית מאושרת

שולח תמיד תבנית, בלי לבדוק את מצב החלון. מתאים כשאתם יודעים בוודאות שאתם פונים ללקוח קר. אם אתם בונים תרחיש חדש — עדיף /api/v1/send.

שדות ב-body

• phonestringחובה

  מספר הנמען.

• namestringחובה

  שם התבנית בדיוק כפי שאושרה ב-WABA.

• languagestring

  קוד שפה, ברירת מחדל "he".

• variablesstring[]

  ערכים ל-{{1}}, {{2}}… לפי הסדר. עד 10.

• buttonsobject[]

  ערכים לכפתורים דינמיים: [{ index, subType: "url" | "quick_reply", value }]. עד 3.

• idempotencyKeystring

  מפתח למניעת כפילות, בדיוק כמו ב-/api/v1/send.

• contactName / channelIdstring

  כמו ב-/api/v1/send.

curl -X POST https://quick-chat.app/api/v1/messages/template \
  -H "Authorization: Bearer qsk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "0501234567",
    "name": "your_template_name",
    "language": "he",
    "variables": ["דנה", "פיצה משפחתית"],
    "idempotencyKey": "order-1234-ready"
  }'

{
  "ok": true,
  "duplicate": false,
  "billable": true,
  "conversationId": "conv_...",
  "contactId": "cnt_...",
  "messageId": "msg_...",
  "status": "SENT",
  "conversationCreated": true
}

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

טקסט חופשי או קובץ

שתי דרכי פנייה: `conversationId` כדי להשיב בתוך שיחה קיימת, או `phone` כדי לפנות לאדם. טקסט חופשי עובר רק בתוך חלון 24 השעות.

שדות ב-body

• conversationIdstring

  מזהה שיחה קיימת. חובה בדיוק אחד מבין conversationId / phone.

• phonestring

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

• textstring

  עד 8000 תווים. נדרש text או attachment.

• attachmentobject

  { url, mime, filename?, size? } — קובץ בכתובת ציבורית.

• contactName / channelIdstring

  בשימוש רק יחד עם phone.

curl -X POST https://quick-chat.app/api/v1/messages \
  -H "Authorization: Bearer qsk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "conv_xxxxxxxx",
    "text": "בדקנו — ההזמנה יוצאת היום"
  }'

{
  "ok": true,
  "messageId": "msg_..."
}

• •פנייה לפי `phone` כשהחלון סגור מחזירה 409 עם code `window_closed` ומפנה ל-/api/v1/messages/template. כישלון רועש עדיף על הודעה שנעלמת בשקט באמצע אוטומציה.

רשימת התבניות המאושרות

מחזיר את התבניות שעל ה-WABA של הארגון, כולל מספר המשתנים והכפתורים של כל אחת — כדי שתרחיש חיצוני יוכל לבחור תבנית בלי להיכנס ל-WhatsApp Manager.

פרמטרים ב-query

• channelIdstring

  נדרש רק אם מחוברים כמה ערוצי WhatsApp רשמיים.

• statusstring

  סינון, למשל APPROVED.

curl "https://quick-chat.app/api/v1/templates?status=APPROVED" \
  -H "Authorization: Bearer qsk_xxx"

{
  "channelId": "chn_...",
  "templates": [
    {
      "name": "order_ready",
      "language": "he",
      "status": "APPROVED",
      "category": "UTILITY",
      "body": "היי {{1}}, ההזמנה {{2}} מוכנה",
      "variableCount": 2,
      "buttons": [
        { "index": 0, "type": "URL", "text": "למעקב", "dynamic": true }
      ]
    }
  ]
}

• •`variableCount` הוא בדיוק האורך שצריך להיות ל-`variables` בשליחה. `dynamic: true` על כפתור אומר שחייבים לספק לו value.

יצירה או עדכון (upsert)

מוסיף איש קשר, או מעדכן קיים. הדדופ הוא לפי טלפון ואז לפי אימייל — בדיוק כמו בייבוא CSV מהממשק.

שדות ב-body

• namestring

  שם מלא.

• phonestring

  מספר טלפון.

• emailstring

  כתובת אימייל.

• tagsstring[]

  עד 20 תגיות. דורס את הרשימה הקיימת.

curl -X POST https://quick-chat.app/api/v1/contacts \
  -H "Authorization: Bearer qsk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"דנה לוי","phone":"+972501234567","tags":["ליד קמפיין"]}'

{
  "contact": {
    "id": "cnt_...",
    "name": "דנה לוי",
    "primaryPhone": "+972501234567",
    "primaryEmail": null,
    "tags": ["ליד קמפיין"]
  },
  "created": true
}

• •נדרש לפחות אחד מבין phone / email / name. יצירה מחזירה 201, עדכון מחזיר 200.
• •`tags` כאן דורס. כדי להוסיף תגית בלי למחוק קיימות — /api/v1/contacts/tag.

הוספה והסרה של תגיות

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

שדות ב-body

• phone / email / contactIdstringחובה

  נדרש אחד מהם לאיתור איש הקשר.

• addstring[]

  תגיות להוספה, עד 20. נדרש add או remove.

• removestring[]

  תגיות להסרה.

• namestring

  שם, בשימוש רק אם הקריאה יוצרת את איש הקשר.

curl -X POST https://quick-chat.app/api/v1/contacts/tag \
  -H "Authorization: Bearer qsk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"phone":"0501234567","add":["ליד חם"],"remove":["ליד קר"]}'

{
  "ok": true,
  "contactId": "cnt_...",
  "tags": ["ליד חם"],
  "created": false
}

• •איש קשר חדש נוצר דרך פותר הזהויות, כדי לא לפצל אדם שכבר מוכר לנו מערוץ אחר. לכן נדרש לפחות ערוץ מחובר אחד בארגון.
• •`contactId` שלא נמצא מחזיר 404 — לא ניצור איש קשר תחת מזהה מומצא.

רשימת אנשי קשר

עימוד לפי cursor על תאריך היצירה, מהחדש לישן.

פרמטרים ב-query

• limitnumber

  ברירת מחדל 50, מקסימום 100.

• cursorstring

  ה-createdAt של הפריט האחרון בעמוד הקודם (ISO-8601).

curl "https://quick-chat.app/api/v1/contacts?limit=50" \
  -H "Authorization: Bearer qsk_xxx"

{
  "items": [ { "id": "cnt_...", "name": "דנה לוי", "primaryPhone": "+9725...", "tags": [] } ],
  "nextCursor": "2026-09-20T10:11:12.000Z"
}

• •`nextCursor: null` מציין שהגעתם לעמוד האחרון.

רשימת שיחות

עימוד לפי lastMessageAt, עם סינון לפי סטטוס ומשויך.

פרמטרים ב-query

• statusstring

  OPEN | PENDING | RESOLVED | SNOOZED.

• assignedToUserIdstring

  רשימה מופרדת בפסיקים, או "null" לשיחות לא משויכות.

• limit / cursornumber / string

  ברירת מחדל 50, מקסימום 100. ה-cursor הוא lastMessageAt.

curl "https://quick-chat.app/api/v1/conversations?status=OPEN&limit=20" \
  -H "Authorization: Bearer qsk_xxx"

{
  "items": [
    {
      "id": "conv_...",
      "status": "OPEN",
      "contactId": "cnt_...",
      "channelId": "chn_...",
      "assignedToUserId": null,
      "lastMessageAt": "2026-09-22T08:00:00.000Z",
      "lastInboundAt": "2026-09-22T08:00:00.000Z",
      "firstResponseSeconds": 42,
      "unreadCount": 1
    }
  ],
  "nextCursor": null
}

בדיקת מפתח ומכסות

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

curl https://quick-chat.app/api/v1/me \
  -H "Authorization: Bearer qsk_xxx"

{
  "organizationId": "org_...",
  "organizationName": "קוויק פוד",
  "scopes": ["read", "write"],
  "apiKeyId": "key_...",
  "limits": {
    "apiRequests": { "limit": 120, "used": 3, "remaining": 117, "window": "minute", "resetAt": "..." },
    "templateSends": { "limit": 125, "used": 40, "remaining": 85, "window": "day", "resetAt": "..." }
  }
}

• •קראו לזה פעם אחת לפני לולאה על מאות נמענים — עדיף לגלות שנגמרה המכסה מראש מאשר מ-429 באמצע.