{"openapi":"3.1.0","info":{"title":"WeHub Public API","version":"1.2.0","description":"ה-API הציבורי של WeHub: אנשי-קשר, שיחות, שליחת הודעות (חכמה: ערוץ/מופע/תוכן נבחרים בשרת), ערוצים, ניהול תבניות ווטסאפ (יצירה, סטטוס, מחיקה) ו-webhooks יוצאים.\n\n**אימות**: `Authorization: Bearer wh_live_…`. המפתח מזוהה עם העסק,\nולכן אין צורך בכותרת-עסק. מפתח מבוטל, מפתח לא-קיים ומפתח בלי קידומת מוכרת\nמקבלים כולם את אותה תשובת 401.\n\n**קצב**: המכסה נגזרת מהתוכנית של העסק (`limits.api_rate_per_min`). חריגה מחזירה 429\nעם `Retry-After`.\n\n**אידמפוטנטיות**: `POST /messages` מקבל `idempotencyKey` (או כותרת `Idempotency-Key`); אותו מפתח ב-24 השעות הבאות מחזיר את התשובה המקורית ולא שולח שוב.\n\n**webhooks יוצאים**: הגוף נחתם ב-`x-wehub-signature: v1=<hex>`, שהוא\nHMAC-SHA256 של `${timestamp}.${body}` עם סוד-המנוי, כאשר `timestamp` הוא ערך `x-wehub-timestamp`\n(שניות Unix). ניסיונות-חוזרים: 1ד׳, 5ד׳, 30ד׳, 2ש׳, 12ש׳.\n\n**האירועים**: `message.received` — הודעה נכנסת (כל ערוץ); `message.sent` — הודעה יוצאת נשלחה בפועל; `message.delivered` — הודעה יוצאת נמסרה ללקוח; `message.read` — הודעה יוצאת נקראה; `message.failed` — שליחת הודעה נכשלה; `conversation.opened` — שיחה חדשה נפתחה; `conversation.closed` — שיחה נסגרה; `conversation.assigned` — רשימת-האחראים בשיחה השתנתה; `csat.received` — הלקוח דירג את השירות; `call.ended` — שיחת-טלפון הסתיימה; `template.status_changed` — סטטוס תבנית ווטסאפ השתנה (אושרה / נדחתה / הושהתה)."},"servers":[{"url":"https://api.wehub.co.il/api/v1/public"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"wh_live_<32 base62>","description":"מפתח-API של העסק. נוצר במסך \"API ומפתחים\" ומוצג פעם אחת בלבד."}},"schemas":{"Error":{"type":"object","description":"צורת-השגיאה האחידה של WeHub (CONTRACT §4). `error` ו-`reason` זהים; `text` בעברית ומוכן-לתצוגה; `details` תלוי-נתיב (למשל `action:\"template\"` כשחלון-המענה סגור, או `code:\"channel-unavailable\"`).","properties":{"error":{"type":"string","description":"קוד-השגיאה"},"reason":{"type":"string","description":"זהה ל-error — נשמר לתאימות עם הלקוחות הקיימים"},"text":{"type":"string","description":"הודעה מוכנה-לתצוגה, בעברית"},"details":{"type":"object","additionalProperties":true}},"required":["error","reason","text"]},"Identity":{"type":"object","properties":{"kind":{"type":"string","enum":["wa","tel","email","ig","fb"]},"value":{"type":"string","description":"מנורמל: E.164 בלי + לטלפון, lower-case לאימייל"},"label":{"type":["string","null"]},"verified":{"type":"boolean"}},"required":["kind","value"]},"Contact":{"type":"object","properties":{"id":{"type":"string","description":"ULID"},"name":{"type":"string"},"company":{"type":["string","null"]},"fields":{"type":"object","additionalProperties":true,"description":"שדות מותאמים לפי הגדרות העסק"},"tags":{"type":"array","items":{"type":"string"}},"consent":{"type":"object","additionalProperties":{"type":"boolean"}},"blocked":{"type":"boolean"},"identities":{"type":"array","items":{"$ref":"#/components/schemas/Identity"}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","tags","blocked","createdAt","updatedAt"]},"ContactPage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["items","page","limit","total","hasMore"]},"Conversation":{"type":"object","properties":{"id":{"type":"string"},"channel":{"type":"string","enum":["wa","email","ig","fb","phone"]},"instanceId":{"type":"string","description":"מזהה מופע-הערוץ (מספר ווטסאפ / תיבת-מייל מסוימת) — ר' GET /channels"},"identity":{"type":"string","description":"הזהות של הלקוח בערוץ: E.164 / כתובת מייל / מזהה-מטא"},"title":{"type":"string"},"status":{"type":"string","enum":["open","pending","snoozed","closed"]},"assignees":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}},"priority":{"type":"string"},"unread":{"type":"integer"},"contact":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},{"type":"null"}]},"lastMessageAt":{"type":["string","null"]},"lastMessagePreview":{"type":"string"},"windowOpen":{"type":"boolean","description":"האם חלון-המענה של הערוץ פתוח לשליחה חופשית. false ⇒ צריך template"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","channel","status","createdAt","updatedAt"]},"ConversationPage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"nextCursor":{"type":["integer","null"],"description":"להעברה כ-cursor בבקשה הבאה; null = סוף"}},"required":["items"]},"Message":{"type":"object","properties":{"id":{"type":"string"},"conversationId":{"type":"string"},"direction":{"type":"string","enum":["in","out"]},"kind":{"type":"string","description":"text / image / video / audio / document / template / note / system …"},"text":{"type":"string","description":"הטקסט; בתבנית — הגוף המרונדר; בקובץ — הכיתוב"},"status":{"type":["string","null"],"enum":["queued","sent","delivered","read","failed",null],"description":"הודעה יוצאת: מצב-המסירה האחרון"},"internal":{"type":"boolean","description":"הערה פנימית של הצוות — לעולם לא יוצאת ללקוח"},"from":{"type":"object","properties":{"type":{"type":["string","null"],"description":"customer / agent / system"},"name":{"type":["string","null"]}}},"template":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"language":{"type":"string"}}},{"type":"null"}]},"media":{"anyOf":[{"type":"object","properties":{"mime":{"type":["string","null"]},"filename":{"type":["string","null"]},"size":{"type":["integer","null"]}}},{"type":"null"}]},"at":{"type":"string"}},"required":["id","conversationId","direction","kind","at"]},"MessageDetail":{"allOf":[{"$ref":"#/components/schemas/Message"},{"type":"object","properties":{"channel":{"type":"string","enum":["wa","email","ig","fb","phone"]},"statusAt":{"type":["string","null"],"description":"מתי הסטטוס האחרון התקבל"},"error":{"anyOf":[{"$ref":"#/components/schemas/MessageError"},{"type":"null"}],"description":"רק כש-status=failed. קוד קצר + הסבר בעברית — בלי פרטי-ספק"}},"required":["channel","statusAt","error"]}]},"MessageError":{"type":"object","properties":{"code":{"type":["string","null"],"description":"`outbound-locked`, `channel-instance-disabled`, קוד-מטא מספרי כמחרוזת… או null"},"he":{"type":"string","description":"ההסבר בעברית — מה שהנציג רואה במסך"}},"required":["code","he"]},"SendTemplate":{"type":"object","description":"תבנית ווטסאפ מאושרת. `body` הוא מערך לפי מיקום ({{1}},{{2}}…) **או** אובייקט לפי שם ({{name}}) — ר' `params` ב-GET /templates.","properties":{"name":{"type":"string","description":"שם התבנית כפי שהוא במטא"},"language":{"type":"string","description":"ברירת-מחדל he"},"body":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"object","additionalProperties":{"type":"string"}}],"description":"ערכי משתני-הגוף: מערך (מיקומי) או אובייקט {שם: ערך} (נקוב)"},"header":{"type":"object","description":"לכותרת עם משתנה: `{text}`; לכותרת-מדיה: `{mediaId}` (מזהה שהועלה למטא); לכותרת-מיקום: `{location:{lat,lng,name?,address?}}`","additionalProperties":true},"buttons":{"type":"object","description":"לפי אינדקס-הכפתור בתבנית: `{\"0\": {type:\"url\", value:\"…\"}}`, `{type:\"copy_code\", value}`, `{type:\"quick_reply\", value}`","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}},"required":["type","value"]}}},"required":["name"]},"SendMedia":{"type":"object","description":"קובץ לשליחה — השרת מוריד מה-URL (https ציבורי בלבד), מאמת ושולח כ-image/video/audio/document לפי הסוג.","properties":{"url":{"type":"string","description":"כתובת ציבורית (https). עד 15MB. סוגים: image/*, video/mp4, audio/*, application/pdf, doc/docx/xls/xlsx"},"filename":{"type":"string","description":"שם-הקובץ שיוצג ללקוח; ברירת-מחדל: מהכתובת"},"caption":{"type":"string","description":"כיתוב מתחת לקובץ (ווטסאפ)"}},"required":["url"]},"SendRequest":{"type":"object","description":"יעד אחד בדיוק (conversationId / contactPublicId / to), ותוכן: text ו/או template, או media.","properties":{"conversationId":{"type":"string","description":"שיחה קיימת — גובר על השאר"},"contactPublicId":{"type":"string","description":"ULID של איש-קשר — הזהות והערוץ נבחרים אוטומטית (או לפי channel)"},"to":{"oneOf":[{"type":"string","description":"טלפון (E.164 או מקומי: +972501234567 / 0501234567) ⇒ ווטסאפ; כתובת מייל ⇒ מייל"},{"type":"object","properties":{"kind":{"type":"string","enum":["wa","tel","email","ig","fb"]},"value":{"type":"string"}},"required":["kind","value"]}],"description":"הנמען: מחרוזת (מזוהה אוטומטית) או {kind,value} מפורש"},"channel":{"type":"string","enum":["auto","wa","whatsapp","email","mail","fb","messenger","ig","instagram"],"description":"ברירת-מחדל auto: שיחה קיימת שחלון-המענה שלה פתוח (wa→fb→ig→email), אחרת הערוץ הטבעי של הזהות. כינויים מתקבלים."},"instanceId":{"type":"string","description":"מופע-ערוץ מסוים (wa / wa2 / email…). ברירת-מחדל: המופע שכבר משוחח עם הנמען, אחרת מופע-ברירת-המחדל, אחרת הראשון המופעל"},"text":{"type":"string","description":"טקסט חופשי — עד 4096 תווים. מותר רק בתוך חלון-המענה; במייל זה גוף ההודעה"},"subject":{"type":"string","description":"מייל בלבד: נושא. ברירת-מחדל: \"Re: <נושא-השיחה>\" או \"הודעה מ-<שם-העסק>\""},"template":{"$ref":"#/components/schemas/SendTemplate"},"media":{"$ref":"#/components/schemas/SendMedia"},"idempotencyKey":{"type":"string","description":"מפתח-אידמפוטנטיות (או כותרת Idempotency-Key). אותו מפתח ב-24 השעות הבאות מחזיר את התשובה המקורית ולא שולח שוב"}}},"SendResult":{"type":"object","properties":{"id":{"type":"string","description":"מזהה-ההודעה — לשאילתה ב-GET /messages/{id} ולהתאמה עם אירועי message.*"},"conversationId":{"type":"string"},"channel":{"type":"string","enum":["wa","email","ig","fb"],"description":"הערוץ שנבחר בפועל"},"instanceId":{"type":"string","description":"המופע שנבחר בפועל"},"sent":{"type":"string","enum":["text","template","media"],"description":"מה יצא — חשוב כש-text ו-template נשלחו יחד"},"status":{"type":"string","enum":["queued","sent","failed"],"description":"מצב מיידי; delivered/read מגיעים אחר-כך ב-webhook או ב-GET /messages/{id}"},"mock":{"type":"boolean","description":"true = השער היוצא במצב הדמיה: ההודעה נרשמה ולא יצאה החוצה (CONTRACT §10)"},"mockReasons":{"type":"array","items":{"type":"string"}},"replayed":{"type":"boolean","description":"true = תשובה שמורה של בקשה קודמת עם אותו idempotencyKey; לא נשלח שוב"}},"required":["id","conversationId","channel","instanceId","sent","status","mock","replayed"]},"ChannelCapabilities":{"type":"object","properties":{"text":{"type":"boolean","description":"טקסט חופשי (בתוך חלון-המענה, כשיש חלון)"},"templates":{"type":"boolean","description":"תבניות מאושרות — הדרך לפנות מחוץ לחלון"},"media":{"type":"boolean"},"windowHours":{"type":["integer","null"],"description":"אורך חלון-המענה לטקסט חופשי; null = אין חלון (מייל)"},"maxText":{"type":"integer"}},"required":["text","templates","media","windowHours","maxText"]},"Channel":{"type":"object","properties":{"id":{"type":"string","description":"ה-instanceId לשליחה: wa / wa2 / email / ig / fb / phone…"},"type":{"type":"string","enum":["wa","email","ig","fb","phone"]},"name":{"type":"string","description":"שם המופע כפי שהוגדר בדסק"},"display":{"type":"string","description":"מספר-הוואטסאפ / כתובת-המייל השולחת / @שם-אינסטגרם / שם-הדף; ריק כשלא הוגדר"},"enabled":{"type":"boolean"},"isDefault":{"type":"boolean","description":"מופע-ברירת-המחדל של הסוג (המזהה שווה לסוג)"},"capabilities":{"$ref":"#/components/schemas/ChannelCapabilities"}},"required":["id","type","name","display","enabled","isDefault","capabilities"]},"TemplateParams":{"type":"object","description":"מה צריך כדי לבנות בקשת-שליחה לתבנית הזו, בלי לראות את components של מטא.","properties":{"body":{"type":"integer","description":"כמה משתנים בגוף"},"named":{"type":["array","null"],"items":{"type":"string"},"description":"שמות המשתנים לפי סדר כשהתבנית נקובה ({{name}}); null בתבנית מיקומית ({{1}})"},"header":{"type":"string","enum":["text","image","video","document","location","none"]},"headerVariable":{"type":"boolean","description":"כותרת-טקסט עם משתנה ⇒ צריך template.header.text"},"buttons":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"type":{"type":"string","enum":["quick_reply","url","phone_number","copy_code"]},"text":{"type":["string","null"]},"variable":{"type":"boolean","description":"צריך ערך בשליחה (url עם משתנה / copy_code)"}},"required":["index","type","variable"]}}},"required":["body","named","header","headerVariable","buttons"]},"Template":{"type":"object","properties":{"name":{"type":"string"},"language":{"type":"string"},"status":{"type":"string","description":"APPROVED / PENDING / REJECTED — כפי שמטא מדווחת. רק APPROVED ניתנת לשליחה"},"statusHe":{"type":"string"},"category":{"type":"string","description":"MARKETING / UTILITY / AUTHENTICATION"},"body":{"type":"string","description":"גוף התבנית עם המשתנים"},"vars":{"type":"array","items":{"type":"string","description":"{{1}} או {{name}} לפי סדר"}},"header":{"type":["object","null"],"additionalProperties":true},"footer":{"type":["string","null"]},"buttons":{"type":"array","items":{"type":"object","additionalProperties":true}},"params":{"$ref":"#/components/schemas/TemplateParams"},"rejectedReason":{"type":["string","null"],"description":"קוד-הדחייה של מטא (`rejected_reason`), רק ב-REJECTED"},"rejectedReasonHe":{"type":["string","null"]},"qualityScore":{"type":["string","null"],"description":"GREEN / YELLOW / RED — ציון-האיכות של מטא; RED מוביל להשהיה"}},"required":["name","language","status","params"]},"TemplateList":{"type":"object","properties":{"instanceId":{"type":"string","description":"המופע שממנו נקראה הרשימה — מפורש או ברירת-המחדל"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Template"}}},"required":["instanceId","items"]},"TemplateCreate":{"type":"object","description":"יצירת תבנית. המספרים הנאכפים: גוף עד 1024 תווים, כותרת-טקסט עד 60 (משתנה אחד), תחתית עד 60 (בלי משתנים), עד 10 כפתורים (עד 10 תשובה-מהירה, עד 2 קישור, אחד טלפון, אחד העתקת-קוד), תווית-כפתור עד 25 תווים.","properties":{"instanceId":{"type":"string","description":"מופע-ווטסאפ; ברירת-מחדל: המופע הראשי (wa)"},"name":{"type":"string","description":"a-z, 0-9 וקו-תחתון, עד 60 תווים. תווים אחרים מומרים לקו-תחתון"},"language":{"type":"string","description":"קוד-שפה של מטא: he / en / en_US. ברירת-מחדל he"},"category":{"type":"string","enum":["UTILITY","MARKETING"],"description":"AUTHENTICATION מוכרת אך אינה נתמכת ליצירה (מבנה ה-OTP לא מומש) ⇒ 400"},"header":{"type":"object","description":"`{type:\"text\", text, example?}` (משתנה אחד לכל היותר, ואז example חובה) · `{type:\"image\"|\"video\"|\"document\", handle}` (ה-handle מ-POST /templates/header-media) · `{type:\"location\"}` · `{type:\"none\"}`","additionalProperties":true},"body":{"type":"string","description":"גוף התבנית. `{{1}}` מיקומי או `{{name}}` נקוב; אסור להתחיל או להסתיים במשתנה"},"examples":{"type":"array","items":{"type":"string","description":"דוגמה אחת לכל משתנה בגוף, לפי הסדר — מטא דורשת אותן כדי לבדוק את התבנית"}},"footer":{"type":["string","null"],"description":"עד 60 תווים, בלי משתנים"},"buttons":{"type":"array","items":{"type":"object","description":"`{type:\"quick_reply\", text}` · `{type:\"url\", text, url, example?}` (משתנה יחיד, {{1}}, בסוף ה-URL בלבד) · `{type:\"phone_number\", text, phone}` · `{type:\"copy_code\", example}`","additionalProperties":true}}},"required":["name","body"]},"TemplateCreated":{"type":"object","properties":{"id":{"type":["string","null"],"description":"מזהה-התבנית אצל מטא — זה שמופיע גם ב-template.status_changed וב-WhatsApp Manager"},"name":{"type":"string","description":"השם אחרי הנרמול (lower-case, קו-תחתון)"},"language":{"type":"string"},"category":{"type":"string"},"status":{"type":"string","description":"PENDING — כל תבנית חדשה נולדת בהמתנה לבדיקת-תוכן של מטא"},"statusHe":{"type":"string"},"instanceId":{"type":"string"}},"required":["id","name","language","category","status","statusHe","instanceId"]},"TemplateHeaderMedia":{"type":"object","properties":{"handle":{"type":"string","description":"ל-`header.handle` ב-POST /templates. תקף לזמן מוגבל אצל מטא — השתמשו בו מיד"},"mime":{"type":"string"},"filename":{"type":"string"},"size":{"type":"integer","description":"בבתים"},"instanceId":{"type":"string"}},"required":["handle","mime","filename","size","instanceId"]},"Webhook":{"type":"object","properties":{"id":{"type":"string","description":"ULID"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["message.received","message.sent","message.delivered","message.read","message.failed","conversation.opened","conversation.closed","conversation.assigned","csat.received","call.ended","template.status_changed"]}},"active":{"type":"boolean"},"secretMasked":{"type":"string","description":"אינדיקציה בלבד — הסוד עצמו מוצג פעם אחת ביצירה/סיבוב"},"createdAt":{"type":"string"},"lastDeliveryAt":{"type":"string"},"failing":{"type":"boolean","description":"נכשל 3 פעמים ברצף או יותר"}},"required":["id","url","events","active","createdAt","failing"]},"WebhookCreated":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","properties":{"secret":{"type":"string","description":"סוד-החתימה — מוצג פעם אחת ואינו ניתן לשחזור"}},"required":["secret"]}]},"Delivery":{"type":"object","properties":{"id":{"type":"string","description":"ULID — זהה ל-id שבגוף המשלוח, לצורך דה-דופליקציה אצל המקבל"},"webhookId":{"type":"string"},"event":{"type":"string","enum":["message.received","message.sent","message.delivered","message.read","message.failed","conversation.opened","conversation.closed","conversation.assigned","csat.received","call.ended","template.status_changed"]},"status":{"type":"string","enum":["pending","delivered","failed","exhausted"]},"attempt":{"type":"integer","description":"כמה שליחות בוצעו (1 = הראשונה)"},"responseStatus":{"type":"integer"},"lastError":{"type":"string"},"nextAttemptAt":{"type":"string"},"createdAt":{"type":"string"},"deliveredAt":{"type":"string"}},"required":["id","webhookId","event","status","attempt","createdAt"]}}},"paths":{"/openapi.json":{"get":{"summary":"מסמך OpenAPI 3.1 של ה-API הציבורי","x-summary-en":"OpenAPI 3.1 document","description":"הנתיב היחיד (לצד /docs.md) שאינו דורש מפתח — אחרת אי-אפשר לגלות את ה-API. אזור-המפתחים במוצר מצייר את התיעוד מהמסמך הזה.","operationId":"getOpenapiJson","tags":["openapi"],"security":[],"responses":{"200":{"description":"בהצלחה","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/docs.md":{"get":{"summary":"מדריך-המפתחים המלא (Markdown)","x-summary-en":"Developer guide (Markdown)","description":"המדריך המלא — אימות, שליחה חכמה, ערוצים, תבניות, מדיה, אידמפוטנטיות, webhooks ודוגמאות-קוד ב-Node / PHP / Python / curl — כ-`text/markdown; charset=utf-8`.","operationId":"getDocsMd","tags":["docs"],"security":[],"responses":{"200":{"description":"בהצלחה","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"לא נמצא — או ששייך לעסק אחר","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts":{"get":{"summary":"רשימת אנשי-קשר","x-summary-en":"List contacts","description":"עימוד לפי עמוד. `q` מחפש בשם, בחברה ובערכי-הזהויות (טלפון/מייל).","operationId":"getContacts","tags":["contacts"],"security":[{"apiKey":[]}],"x-wehub-scope":"contacts:read","x-wehub-scopes":["contacts:read"],"parameters":[{"name":"q","in":"query","required":false,"description":"חיפוש חופשי בשם, בחברה או בערך-זהות","schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"description":"סינון לפי תגית","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"מספר-עמוד (מ-1)","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","required":false,"description":"כמה פריטים להחזיר","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"בהצלחה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactPage"},"examples":{"default":{"value":{"items":[{"id":"01J8XK2Q9M4V7C0RTBNEFGHJ5A","name":"דנה כהן","company":null,"fields":{"city":"תל אביב"},"tags":["vip"],"consent":{"marketing":true},"blocked":false,"identities":[{"kind":"wa","value":"972501234567","label":null,"verified":false}],"createdAt":"2026-09-01T08:00:00.000Z","updatedAt":"2026-09-04T09:30:00.000Z"}],"page":1,"limit":25,"total":1,"hasMore":false}}}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"יצירת איש-קשר","x-summary-en":"Create a contact","description":"ערכי-הזהות מנורמלים בשרת (E.164 בלי + לטלפון, lower-case למייל). זהות שכבר שייכת לכרטיס אחר ⇒ 409.","operationId":"postContacts","tags":["contacts"],"security":[{"apiKey":[]}],"x-wehub-scope":"contacts:write","x-wehub-scopes":["contacts:write"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"company":{"type":["string","null"]},"fields":{"type":"object","additionalProperties":true},"tags":{"type":"array","items":{"type":"string"}},"identities":{"type":"array","items":{"$ref":"#/components/schemas/Identity"}}}},"examples":{"default":{"value":{"name":"דנה כהן","tags":["vip"],"identities":[{"kind":"wa","value":"+972501234567"}]}}}}}},"responses":{"201":{"description":"בהצלחה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"},"examples":{"default":{"value":{"id":"01J8XK2Q9M4V7C0RTBNEFGHJ5A","name":"דנה כהן","company":null,"fields":{"city":"תל אביב"},"tags":["vip"],"consent":{"marketing":true},"blocked":false,"identities":[{"kind":"wa","value":"972501234567","label":null,"verified":false}],"createdAt":"2026-09-01T08:00:00.000Z","updatedAt":"2026-09-04T09:30:00.000Z"}}}}}},"400":{"description":"קלט שגוי — `text` מסביר, `details` מפרט (למשל missing/unknown בפרמטרים נקובים)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"התנגשות — חלון-מענה סגור (`details.action:\"template\"`), תבנית לא-מאושרת, אין מופע מופעל (`details.code:\"channel-unavailable\"`), בקשה אידמפוטנטית עדיין רצה, מופע-ווטסאפ שאינו מחובר למטא (`details.code:\"not-connected\"`), שם-תבנית שכבר קיים (`details.code:\"template-exists\"`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts/{publicId}":{"get":{"summary":"איש-קשר בודד, כולל זהויות","x-summary-en":"Get a contact","operationId":"getContactsPublicId","tags":["contacts"],"security":[{"apiKey":[]}],"x-wehub-scope":"contacts:read","x-wehub-scopes":["contacts:read"],"parameters":[{"name":"publicId","in":"path","required":true,"description":"ה-ULID של איש-הקשר","schema":{"type":"string"}}],"responses":{"200":{"description":"בהצלחה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"},"examples":{"default":{"value":{"id":"01J8XK2Q9M4V7C0RTBNEFGHJ5A","name":"דנה כהן","company":null,"fields":{"city":"תל אביב"},"tags":["vip"],"consent":{"marketing":true},"blocked":false,"identities":[{"kind":"wa","value":"972501234567","label":null,"verified":false}],"createdAt":"2026-09-01T08:00:00.000Z","updatedAt":"2026-09-04T09:30:00.000Z"}}}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"לא נמצא — או ששייך לעסק אחר","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"עדכון איש-קשר","x-summary-en":"Update a contact","description":"רק השדות שנשלחו משתנים. `tags` ו-`fields` מחליפים את הערך כולו.","operationId":"patchContactsPublicId","tags":["contacts"],"security":[{"apiKey":[]}],"x-wehub-scope":"contacts:write","x-wehub-scopes":["contacts:write"],"parameters":[{"name":"publicId","in":"path","required":true,"description":"ה-ULID של איש-הקשר","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"company":{"type":["string","null"]},"fields":{"type":"object","additionalProperties":true},"tags":{"type":"array","items":{"type":"string"}},"consent":{"type":"object","additionalProperties":{"type":"boolean"}},"blocked":{"type":"boolean"}}},"examples":{"default":{"value":{"tags":["vip","returning"],"fields":{"city":"חיפה"}}}}}}},"responses":{"200":{"description":"בהצלחה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"},"examples":{"default":{"value":{"id":"01J8XK2Q9M4V7C0RTBNEFGHJ5A","name":"דנה כהן","company":null,"fields":{"city":"חיפה"},"tags":["vip","returning"],"consent":{"marketing":true},"blocked":false,"identities":[{"kind":"wa","value":"972501234567","label":null,"verified":false}],"createdAt":"2026-09-01T08:00:00.000Z","updatedAt":"2026-09-04T09:30:00.000Z"}}}}}},"400":{"description":"קלט שגוי — `text` מסביר, `details` מפרט (למשל missing/unknown בפרמטרים נקובים)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"לא נמצא — או ששייך לעסק אחר","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations":{"get":{"summary":"רשימת שיחות","x-summary-en":"List conversations","description":"מוחזרות **כל** שיחות העסק: מפתח-API שייך לעסק ולא לנציג, ולכן אין כאן סינון לפי היקף-ראייה. העימוד הוא cursor-based: מעבירים את `nextCursor` מהתשובה הקודמת; `null` = סוף.","operationId":"getConversations","tags":["conversations"],"security":[{"apiKey":[]}],"x-wehub-scope":"conversations:read","x-wehub-scopes":["conversations:read"],"parameters":[{"name":"status","in":"query","required":false,"description":"סינון לפי מצב","schema":{"type":"string","enum":["open","pending","snoozed","closed"]}},{"name":"channel","in":"query","required":false,"description":"סינון לפי ערוץ","schema":{"type":"string"}},{"name":"instanceId","in":"query","required":false,"description":"סינון לפי מופע-ערוץ (‏`wa`, `wa2`, `phone`…)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"ה-nextCursor מהעמוד הקודם","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"כמה פריטים להחזיר","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"בהצלחה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationPage"},"examples":{"default":{"value":{"items":[{"id":"l7d3p0","channel":"wa","instanceId":"wa","identity":"972501234567","title":"דנה כהן","status":"pending","assignees":["noa@example.co.il"],"labels":["orders"],"priority":"normal","unread":0,"contact":{"id":"01J8XK2Q9M4V7C0RTBNEFGHJ5A","name":"דנה כהן"},"lastMessageAt":"2026-09-04T10:12:00.000Z","lastMessagePreview":"ההזמנה 12345 יצאה למשלוח","windowOpen":true,"createdAt":"2026-09-01T08:00:00.000Z","updatedAt":"2026-09-04T10:12:00.000Z"}],"nextCursor":null}}}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations/{id}":{"get":{"summary":"שיחה בודדת","x-summary-en":"Get a conversation","description":"`windowOpen` אומר אם אפשר לשלוח עכשיו טקסט חופשי בשיחה הזו; `false` ⇒ צריך template (ווטסאפ) או להמתין שהלקוח יכתוב.","operationId":"getConversationsId","tags":["conversations"],"security":[{"apiKey":[]}],"x-wehub-scope":"conversations:read","x-wehub-scopes":["conversations:read"],"parameters":[{"name":"id","in":"path","required":true,"description":"מזהה-השיחה","schema":{"type":"string"}}],"responses":{"200":{"description":"בהצלחה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"},"examples":{"default":{"value":{"id":"l7d3p0","channel":"wa","instanceId":"wa","identity":"972501234567","title":"דנה כהן","status":"pending","assignees":["noa@example.co.il"],"labels":["orders"],"priority":"normal","unread":0,"contact":{"id":"01J8XK2Q9M4V7C0RTBNEFGHJ5A","name":"דנה כהן"},"lastMessageAt":"2026-09-04T10:12:00.000Z","lastMessagePreview":"ההזמנה 12345 יצאה למשלוח","windowOpen":true,"createdAt":"2026-09-01T08:00:00.000Z","updatedAt":"2026-09-04T10:12:00.000Z"}}}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"לא נמצא — או ששייך לעסק אחר","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations/{id}/messages":{"get":{"summary":"הודעות בשיחה, מהחדש לישן","x-summary-en":"List messages in a conversation","description":"הערות פנימיות (`internal:true`) נכללות — הן חלק מהשיחה בדסק, אך לעולם לא נשלחו ללקוח.","operationId":"getConversationsIdMessages","tags":["conversations"],"security":[{"apiKey":[]}],"x-wehub-scope":"conversations:read","x-wehub-scopes":["conversations:read"],"parameters":[{"name":"id","in":"path","required":true,"description":"מזהה-השיחה","schema":{"type":"string"}},{"name":"before","in":"query","required":false,"description":"מזהה-הודעה לדפדוף אחורה","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"כמה פריטים להחזיר","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"בהצלחה","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"hasMore":{"type":"boolean"}},"required":["items","hasMore"]},"examples":{"default":{"value":{"items":[{"id":"m8x2k1q9","conversationId":"l7d3p0","direction":"out","kind":"text","text":"ההזמנה 12345 יצאה למשלוח","status":"delivered","internal":false,"from":{"type":"agent","name":"API"},"template":null,"media":null,"at":"2026-09-04T10:12:00.000Z"}],"hasMore":false}}}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"לא נמצא — או ששייך לעסק אחר","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages":{"post":{"summary":"שליחת הודעה (חכמה)","x-summary-en":"Send a message (smart routing)","description":"נקודת-השליחה היחידה. השרת מכריע יעד, ערוץ, מופע ותוכן לפי הכללים ב-`x-wehub-notes`, ומחזיר ב-`channel`/`instanceId`/`sent` מה נבחר בפועל. השליחה עוברת באותם מנעולים כמו שליחה מהמסך (CONTRACT §10): כשהשער היוצא במצב הדמיה התשובה נושאת `mock:true`. `201` לשליחה חדשה; `200` עם `replayed:true` כשהבקשה זוהתה כחזרה על `idempotencyKey` קודם.","x-wehub-notes":["יעד: conversationId ⇐ contactPublicId ⇐ to (בסדר הזה, אחד בלבד). `to` כמחרוזת מזוהה אוטומטית: טלפון ⇒ ווטסאפ, מייל ⇒ מייל; לאינסטגרם/מסנג׳ר משתמשים ב-{kind,value} או ב-contactPublicId.","ערוץ (channel:\"auto\", ברירת-המחדל): כשהנמען מוכר כאיש-קשר, נבחרת שיחה קיימת שחלון-המענה שלה פתוח עכשיו — ווטסאפ ⇐ מסנג׳ר ⇐ אינסטגרם ⇐ מייל — כי שם אפשר לכתוב טקסט חופשי בלי תבנית. אחרת: הערוץ הטבעי של הזהות. ערוץ מפורש מכובד תמיד (400 אם לאיש-הקשר אין זהות בו). כינויים: whatsapp / mail / messenger / instagram.","מופע (instanceId): המופע שכבר מנהל שיחה עם הנמען ⇐ מופע-ברירת-המחדל של הערוץ אם מופעל ⇐ המופע המופעל הראשון ⇐ 409 עם details.code=\"channel-unavailable\". מופע מפורש חייב להיות מהסוג של הערוץ ומופעל.","תוכן: text בלבד ⇒ טקסט חופשי (חלון סגור ⇒ 409 עם details.action=\"template\"). template בלבד ⇒ תבנית מאושרת. text + template יחד ⇒ הטקסט אם החלון פתוח, אחרת התבנית — והתשובה אומרת מה יצא ב-`sent`.","media.url ⇒ השרת מוריד (https ציבורי, עד 15MB, image/* · video/mp4 · audio/* · pdf · doc/docx/xls/xlsx), שומר ושולח כ-image/video/audio/document, עם caption אופציונלי. media לא משתלב עם text או template. מייל: אין קבצים דרך ה-API (409).","מייל: text הוא גוף ההודעה, subject רשות (ברירת-מחדל \"Re: <נושא-השיחה>\" או \"הודעה מ-<שם-העסק>\"). תבנית למייל ⇒ 409.","פרמטרים נקובים: template.body כאובייקט ממופה למשתני התבנית לפי שמם ({{customer_name}}); שם חסר או לא-מוכר ⇒ 400 עם missing/unknown/expected. מערך = מיקומי כמו קודם.","אידמפוטנטיות: idempotencyKey בגוף או Idempotency-Key בכותרת. אותו מפתח ב-24 השעות הבאות מחזיר את התשובה המקורית (200, replayed:true) ולא שולח שוב. בקשה שנכשלה משחררת את המפתח; בקשה שעדיין רצה ⇒ 409 details.code=\"idempotency-in-flight\".","אידמפוטנטיות — הגבולות: המפתח כרוך בתוכן הבקשה. אותו idempotencyKey עם יעד או תוכן אחרים ⇒ 422 details.code=\"idempotency-key-reused\" (ולא התשובה הישנה בשקט); סדר-שדות שונה באותו תוכן אינו \"תוכן אחר\". מרחב-המפתחות הוא פר-מפתח-API, ולכן שתי אינטגרציות של אותו עסק יכולות להשתמש באותו מזהה-הזמנה בלי להתנגש.","mock:true פירושו שהשער היוצא סגור בסביבה הזו (פיתוח/בדיקות/העסק לא הופעל לשליחה חיה): ההודעה נרשמה בדסק ולא יצאה ללקוח. mockReasons[] מסביר. לא לפרש כמסירה.","מסירה: status בתשובה הוא מיידי (sent/failed). delivered/read מגיעים אחר-כך — ב-webhooks message.delivered / message.read / message.failed, או בפולינג GET /messages/{id}."],"operationId":"postMessages","tags":["messages"],"security":[{"apiKey":[]}],"x-wehub-scope":"messages:send","x-wehub-scopes":["messages:send"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"שקול ל-`idempotencyKey` בגוף (הגוף גובר)","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendRequest"},"examples":{"default":{"value":{"to":"+972501234567","text":"היי דנה, ההזמנה 12345 יצאה למשלוח 🎉","template":{"name":"order_shipped","language":"he","body":{"name":"דנה","order":"12345"}},"idempotencyKey":"order-12345-shipped"}}}}}},"responses":{"200":{"description":"תשובה-חוזרת: אותו idempotencyKey כבר נשלח ב-24 השעות האחרונות — לא נשלח שוב","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResult"},"examples":{"default":{"value":{"id":"m8x2k1q9","conversationId":"l7d3p0","channel":"wa","instanceId":"wa","sent":"text","status":"sent","mock":false,"replayed":true}}}}}},"201":{"description":"בהצלחה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResult"},"examples":{"default":{"value":{"id":"m8x2k1q9","conversationId":"l7d3p0","channel":"wa","instanceId":"wa","sent":"text","status":"sent","mock":false,"replayed":false}}}}}},"400":{"description":"קלט שגוי — `text` מסביר, `details` מפרט (למשל missing/unknown בפרמטרים נקובים)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"לא נמצא — או ששייך לעסק אחר","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"התנגשות — חלון-מענה סגור (`details.action:\"template\"`), תבנית לא-מאושרת, אין מופע מופעל (`details.code:\"channel-unavailable\"`), בקשה אידמפוטנטית עדיין רצה, מופע-ווטסאפ שאינו מחובר למטא (`details.code:\"not-connected\"`), שם-תבנית שכבר קיים (`details.code:\"template-exists\"`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"השער היוצא נעול (live-locked)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"ספק חיצוני (מטא/ערוץ) החזיר שגיאה — `details.messageId` כשההודעה נשמרה כ-failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages/{id}":{"get":{"summary":"מצב-המסירה של הודעה","x-summary-en":"Get a message and its delivery status","description":"לפולינג אחרי שליחה, למי שלא עובד עם webhooks. `status` מתקדם queued → sent → delivered → read, או failed; `error` (רק ב-failed) נושא קוד קצר והסבר בעברית — בלי פרטי-ספק. מזהה של עסק אחר הוא 404.","operationId":"getMessagesId","tags":["messages"],"security":[{"apiKey":[]}],"x-wehub-scope":"messages:send","x-wehub-scopes":["messages:send","conversations:read"],"parameters":[{"name":"id","in":"path","required":true,"description":"מזהה-ההודעה מתשובת POST /messages","schema":{"type":"string"}}],"responses":{"200":{"description":"בהצלחה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDetail"},"examples":{"default":{"value":{"id":"m8x2k1q9","conversationId":"l7d3p0","direction":"out","kind":"text","text":"ההזמנה 12345 יצאה למשלוח","status":"delivered","internal":false,"from":{"type":"agent","name":"API"},"template":null,"media":null,"at":"2026-09-04T10:12:00.000Z","channel":"wa","statusAt":"2026-09-04T10:12:03.000Z","error":null}}}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"לא נמצא — או ששייך לעסק אחר","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/channels":{"get":{"summary":"מופעי-הערוץ של העסק ומה כל אחד יודע","x-summary-en":"List channel instances and capabilities","description":"ה-`id` הוא ה-`instanceId` לשליחה. `display` הוא מה שהלקוח רואה (מספר / כתובת / @שם / דף). מופעים מושבתים נכללים עם `enabled:false` — כדי ש\"למה נדחיתי\" תהיה שאלה עם תשובה.","operationId":"getChannels","tags":["channels"],"security":[{"apiKey":[]}],"x-wehub-scope":"messages:send","x-wehub-scopes":["messages:send","templates:read","conversations:read"],"responses":{"200":{"description":"בהצלחה","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}}},"required":["items"]},"examples":{"default":{"value":{"items":[{"id":"wa","type":"wa","name":"ווטסאפ","display":"+972-3-555-1234","enabled":true,"isDefault":true,"capabilities":{"text":true,"templates":true,"media":true,"windowHours":24,"maxText":4096}},{"id":"email","type":"email","name":"מייל","display":"support@example.co.il","enabled":true,"isDefault":true,"capabilities":{"text":true,"templates":false,"media":true,"windowHours":null,"maxText":20000}},{"id":"phone","type":"phone","name":"טלפון","display":"+972-3-555-0000","enabled":true,"isDefault":true,"capabilities":{"text":false,"templates":false,"media":false,"windowHours":null,"maxText":0}}]}}}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/templates":{"get":{"summary":"תבניות ווטסאפ של מופע-הערוץ","x-summary-en":"List WhatsApp templates","description":"כפי שמטא מדווחת, עם `params` — כמה משתנים, אם הם נקובים, ומה דורשים הכותרת והכפתורים — כדי לבנות בקשת-שליחה בלי לראות את `components` הגולמי. רק `status:\"APPROVED\"` ניתנת לשליחה. הסינון מתבצע בצד שלנו על הרשימה המלאה (מטא מחזירה עד 200 בקריאה אחת), ו-`status`/`language` אינם רגישים לרישיות.","x-wehub-notes":["מפתח-בדיקה (wh_test_) קורא תבניות ואינו משנה אותן: POST /templates, POST /templates/header-media ו-DELETE /templates/{name} מחזירים 403 details.code=\"test-key-readonly\". ניהול-תבניות נוגע ב-WABA האמיתי של העסק — מחיקה מפילה את השם על כל שפותיו ודורשת אישור-מחדש של מטא — ולכן היא דורשת מפתח live.","מחזור-חיים: יצירה ⇒ PENDING (\"ממתינה לאישור\") ⇒ APPROVED או REJECTED. מטא יכולה גם להשהות (PAUSED) או להשבית (DISABLED) תבנית מאושרת לפי איכות ותלונות. רק APPROVED ניתנת לשליחה. ההתראה על כל מעבר היא ה-webhook `template.status_changed`; `GET /templates/{name}?language=` הוא הפולינג המקביל.","קטגוריה: UTILITY (עדכון על עסקה קיימת — הזמנה, תור, משלוח) או MARKETING (פנייה יזומה). מטא בודקת את התוכן מול הקטגוריה, ותוכן מכירתי ב-UTILITY הוא סיבת-דחייה מתועדת. AUTHENTICATION (OTP) אינה נתמכת ליצירה דרך ה-API.","כותרת: טקסט עד 60 תווים עם עד 1 משתנה (ואז `example` חובה), או מדיה — תמונה/וידאו/מסמך — שמועלית מראש ב-`POST /templates/header-media` ומועברת כ-`header.handle`. אפשר גם `{type:\"location\"}`.","גוף: עד 1024 תווים. משתנים מיקומיים `{{1}}`,`{{2}}` ברצף בלי דילוגים, או נקובים `{{customer_name}}`. הגוף לא יכול להתחיל או להסתיים במשתנה, וצריך דוגמה אחת ב-`examples` לכל משתנה — מטא בודקת את התבנית דרכן.","תחתית: עד 60 תווים, בלי משתנים.","כפתורים: עד 10 בסך הכול — quick_reply · url · phone_number · copy_code. עד 10 תשובה-מהירה, עד 2 קישור, 1 טלפון, 1 העתקת-קוד. תווית עד 25 תווים; URL עד 2000; דוגמת-קוד עד 20.","כפתורי תשובה-מהירה חייבים להיות רצופים — כולם בתחילת רשימת-הכפתורים או כולם בסופה. \"קישור, תשובה-מהירה, קישור\" נדחה.","כפתור קישור עם משתנה: משתנה אחד בלבד, `{{1}}`, ובסוף ה-URL בלבד, ועם `example`. כפתור העתקת-קוד אינו נושא תווית מותאמת — רק `example`.","שם: אותיות קטנות, ספרות וקו-תחתון, עד 60 תווים. תווים אחרים מומרים לקו-תחתון, ולכן השם בתשובה הוא השם שנוצר בפועל. שם+שפה שכבר קיימים ⇒ 409 עם `details.code:\"template-exists\"`.","שפה: לתבנית אחת יש גרסה נפרדת לכל שפה, עם סטטוס נפרד. `DELETE /templates/{name}` מוחק את **כל** השפות של השם — כך מטא עובדת.","מופע שאינו מחובר למטא ⇒ 409 עם `details.code:\"not-connected\"` (ולא רשימה ריקה ולא 502) — יש להשלים את חיבור ערוץ הווטסאפ בהגדרות."],"operationId":"getTemplates","tags":["templates"],"security":[{"apiKey":[]}],"x-wehub-scope":"templates:read","x-wehub-scopes":["templates:read"],"parameters":[{"name":"instanceId","in":"query","required":false,"description":"ברירת-מחדל: המופע הראשי (wa)","schema":{"type":"string"}},{"name":"name","in":"query","required":false,"description":"שם מדויק (לא חיפוש חלקי) — תבנית אחת לכל שפה","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"APPROVED / PENDING / REJECTED וכד׳ — הערך של מטא, לא רגיש לרישיות","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"קוד-שפה (he, en, en_US)","schema":{"type":"string"}}],"responses":{"200":{"description":"בהצלחה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateList"},"examples":{"default":{"value":{"instanceId":"wa","items":[{"name":"order_shipped","language":"he","status":"APPROVED","statusHe":"מאושרת","category":"UTILITY","body":"שלום {{name}}, ההזמנה {{order}} יצאה למשלוח.","vars":["{{name}}","{{order}}"],"header":null,"footer":null,"buttons":[],"params":{"body":2,"named":["name","order"],"header":"none","headerVariable":false,"buttons":[]},"rejectedReason":null,"rejectedReasonHe":null,"qualityScore":"GREEN"}]}}}}}},"400":{"description":"קלט שגוי — `text` מסביר, `details` מפרט (למשל missing/unknown בפרמטרים נקובים)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"התנגשות — חלון-מענה סגור (`details.action:\"template\"`), תבנית לא-מאושרת, אין מופע מופעל (`details.code:\"channel-unavailable\"`), בקשה אידמפוטנטית עדיין רצה, מופע-ווטסאפ שאינו מחובר למטא (`details.code:\"not-connected\"`), שם-תבנית שכבר קיים (`details.code:\"template-exists\"`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"ספק חיצוני (מטא/ערוץ) החזיר שגיאה — `details.messageId` כשההודעה נשמרה כ-failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"יצירת תבנית ווטסאפ","x-summary-en":"Create a WhatsApp template","description":"התבנית נשלחת לבדיקת-תוכן של מטא ונולדת `PENDING`. האישור מגיע דקות עד שעות אחר-כך — האזינו ל-`template.status_changed` או בדקו ב-`GET /templates/{name}`. עד `APPROVED` אי-אפשר לשלוח אותה.\n\n**דחיות נפוצות של מטא**: משתנים לא-רצופים ({{1}},{{2}},{{4}}), גוף שמתחיל או מסתיים במשתנה, דוגמה חסרה למשתנה, וניסוח שיווקי בתבנית שהוגדרה `UTILITY`. הוולידציה שלנו חוסמת את שלוש הראשונות **לפני** שהתבנית נשלחת, ומחזירה 400 עם ההסבר בעברית.","x-wehub-notes":["מפתח-בדיקה (wh_test_) קורא תבניות ואינו משנה אותן: POST /templates, POST /templates/header-media ו-DELETE /templates/{name} מחזירים 403 details.code=\"test-key-readonly\". ניהול-תבניות נוגע ב-WABA האמיתי של העסק — מחיקה מפילה את השם על כל שפותיו ודורשת אישור-מחדש של מטא — ולכן היא דורשת מפתח live.","מחזור-חיים: יצירה ⇒ PENDING (\"ממתינה לאישור\") ⇒ APPROVED או REJECTED. מטא יכולה גם להשהות (PAUSED) או להשבית (DISABLED) תבנית מאושרת לפי איכות ותלונות. רק APPROVED ניתנת לשליחה. ההתראה על כל מעבר היא ה-webhook `template.status_changed`; `GET /templates/{name}?language=` הוא הפולינג המקביל.","קטגוריה: UTILITY (עדכון על עסקה קיימת — הזמנה, תור, משלוח) או MARKETING (פנייה יזומה). מטא בודקת את התוכן מול הקטגוריה, ותוכן מכירתי ב-UTILITY הוא סיבת-דחייה מתועדת. AUTHENTICATION (OTP) אינה נתמכת ליצירה דרך ה-API.","כותרת: טקסט עד 60 תווים עם עד 1 משתנה (ואז `example` חובה), או מדיה — תמונה/וידאו/מסמך — שמועלית מראש ב-`POST /templates/header-media` ומועברת כ-`header.handle`. אפשר גם `{type:\"location\"}`.","גוף: עד 1024 תווים. משתנים מיקומיים `{{1}}`,`{{2}}` ברצף בלי דילוגים, או נקובים `{{customer_name}}`. הגוף לא יכול להתחיל או להסתיים במשתנה, וצריך דוגמה אחת ב-`examples` לכל משתנה — מטא בודקת את התבנית דרכן.","תחתית: עד 60 תווים, בלי משתנים.","כפתורים: עד 10 בסך הכול — quick_reply · url · phone_number · copy_code. עד 10 תשובה-מהירה, עד 2 קישור, 1 טלפון, 1 העתקת-קוד. תווית עד 25 תווים; URL עד 2000; דוגמת-קוד עד 20.","כפתורי תשובה-מהירה חייבים להיות רצופים — כולם בתחילת רשימת-הכפתורים או כולם בסופה. \"קישור, תשובה-מהירה, קישור\" נדחה.","כפתור קישור עם משתנה: משתנה אחד בלבד, `{{1}}`, ובסוף ה-URL בלבד, ועם `example`. כפתור העתקת-קוד אינו נושא תווית מותאמת — רק `example`.","שם: אותיות קטנות, ספרות וקו-תחתון, עד 60 תווים. תווים אחרים מומרים לקו-תחתון, ולכן השם בתשובה הוא השם שנוצר בפועל. שם+שפה שכבר קיימים ⇒ 409 עם `details.code:\"template-exists\"`.","שפה: לתבנית אחת יש גרסה נפרדת לכל שפה, עם סטטוס נפרד. `DELETE /templates/{name}` מוחק את **כל** השפות של השם — כך מטא עובדת.","מופע שאינו מחובר למטא ⇒ 409 עם `details.code:\"not-connected\"` (ולא רשימה ריקה ולא 502) — יש להשלים את חיבור ערוץ הווטסאפ בהגדרות."],"operationId":"postTemplates","tags":["templates"],"security":[{"apiKey":[]}],"x-wehub-scope":"templates:write","x-wehub-scopes":["templates:write"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateCreate"},"examples":{"default":{"value":{"name":"order_shipped","language":"he","category":"UTILITY","header":{"type":"text","text":"עדכון הזמנה {{1}}","example":"12345"},"body":"שלום {{1}}, ההזמנה {{2}} יצאה למשלוח.","examples":["דנה","12345"],"footer":"WeHub","buttons":[{"type":"url","text":"מעקב","url":"https://example.co.il/track/{{1}}","example":"ABC123"},{"type":"phone_number","text":"התקשרו","phone":"+97231234567"}]}}}}}},"responses":{"201":{"description":"בהצלחה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateCreated"},"examples":{"default":{"value":{"id":"1234567890123456","name":"order_shipped","language":"he","category":"UTILITY","status":"PENDING","statusHe":"ממתינה לאישור","instanceId":"wa"}}}}}},"400":{"description":"קלט שגוי — `text` מסביר, `details` מפרט (למשל missing/unknown בפרמטרים נקובים)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"התנגשות — חלון-מענה סגור (`details.action:\"template\"`), תבנית לא-מאושרת, אין מופע מופעל (`details.code:\"channel-unavailable\"`), בקשה אידמפוטנטית עדיין רצה, מופע-ווטסאפ שאינו מחובר למטא (`details.code:\"not-connected\"`), שם-תבנית שכבר קיים (`details.code:\"template-exists\"`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"ספק חיצוני (מטא/ערוץ) החזיר שגיאה — `details.messageId` כשההודעה נשמרה כ-failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/templates/header-media":{"post":{"summary":"העלאת מדיה לכותרת-תבנית (מ-URL)","x-summary-en":"Upload template header media from a URL","description":"תבנית עם כותרת תמונה/וידאו/מסמך דורשת `handle` שהועלה מראש למטא (Resumable Upload) — **לא** מזהה-מדיה של הודעה; מטא מבחינה בין השניים. השרת מוריד מהכתובת (https ציבורי, עד 15MB), מוודא סוג, מעלה, ומחזיר את ה-`handle` להעברה כ-`header.handle` ב-`POST /templates`.\n\nהסוגים המותרים כאן צרים מאלה של `media.url` בשליחה: `image/*`, `video/mp4`, `application/pdf` בלבד — אלה פורמטי-הכותרת של מטא. אחר ⇒ 400 עם `details.allowed`.","x-wehub-notes":["ה-handle הזה אינו מזהה-מדיה של הודעה. מזהה-מדיה נשלח ב-`template.header.mediaId` בשליחה; ה-handle משמש **רק** ליצירת התבנית.","הוא תקף לזמן מוגבל אצל מטא — העלו ואז צרו את התבנית באותו תהליך, ואל תשמרו אותו לשימוש מאוחר.","הסוגים: `image/*`, `video/mp4`, `application/pdf` בלבד — צר מהרשימה של `media.url` בשליחה, כי אלה פורמטי-הכותרת של מטא."],"operationId":"postTemplatesHeaderMedia","tags":["templates"],"security":[{"apiKey":[]}],"x-wehub-scope":"templates:write","x-wehub-scopes":["templates:write"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"instanceId":{"type":"string","description":"ברירת-מחדל: המופע הראשי (wa)"},"url":{"type":"string","description":"https ציבורי; כתובות פנימיות נדחות"},"filename":{"type":"string","description":"שם-הקובץ שיישלח למטא; ברירת-מחדל — מהכתובת"}},"required":["url"]},"examples":{"default":{"value":{"url":"https://cdn.example.com/banner.png","filename":"banner.png"}}}}}},"responses":{"201":{"description":"בהצלחה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateHeaderMedia"},"examples":{"default":{"value":{"handle":"4::aW1hZ2UvcG5n:ARZ…","mime":"image/png","filename":"banner.png","size":48213,"instanceId":"wa"}}}}}},"400":{"description":"קלט שגוי — `text` מסביר, `details` מפרט (למשל missing/unknown בפרמטרים נקובים)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"התנגשות — חלון-מענה סגור (`details.action:\"template\"`), תבנית לא-מאושרת, אין מופע מופעל (`details.code:\"channel-unavailable\"`), בקשה אידמפוטנטית עדיין רצה, מופע-ווטסאפ שאינו מחובר למטא (`details.code:\"not-connected\"`), שם-תבנית שכבר קיים (`details.code:\"template-exists\"`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"ספק חיצוני (מטא/ערוץ) החזיר שגיאה — `details.messageId` כשההודעה נשמרה כ-failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/templates/{name}":{"get":{"summary":"תבנית לפי שם — כולל הסטטוס והסיבה לדחייה","x-summary-en":"Get a template by name","description":"עם `language` מוחזר **אובייקט-התבנית**; בלעדיו מוחזר `{instanceId, items}` עם גרסה לכל שפה — לתבנית אחת אצל מטא יש גרסה נפרדת, עם סטטוס נפרד, לכל שפה. שם שאינו קיים במופע ⇒ 404. זו הדרך לבדוק אם תבנית שנוצרה כבר אושרה, למי שלא עובד עם webhooks.","x-wehub-notes":["זו נקודת-הפולינג אחרי `POST /templates`: `status` עובר מ-PENDING ל-APPROVED או ל-REJECTED. עדיף להאזין ל-webhook `template.status_changed` במקום לדגום.","ב-REJECTED יש `rejectedReason` (הקוד של מטא) ו-`rejectedReasonHe` (ההסבר). קוד שעדיין לא תורגם יוצא כמשפט שנושא את הקוד, לא כניחוש.","`qualityScore` (GREEN/YELLOW/RED) נמדד לפי חסימות ותלונות של נמענים; RED מוביל להשהיה אוטומטית של התבנית אצל מטא."],"operationId":"getTemplatesName","tags":["templates"],"security":[{"apiKey":[]}],"x-wehub-scope":"templates:read","x-wehub-scopes":["templates:read"],"parameters":[{"name":"name","in":"path","required":true,"description":"שם התבנית (lower-case, כמו שהוא במטא)","schema":{"type":"string"}},{"name":"instanceId","in":"query","required":false,"description":"ברירת-מחדל: המופע הראשי (wa)","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"עם שפה ⇒ תבנית אחת; בלעדיה ⇒ כל השפות","schema":{"type":"string"}}],"responses":{"200":{"description":"בהצלחה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"},"examples":{"default":{"value":{"name":"order_shipped","language":"he","status":"APPROVED","statusHe":"מאושרת","category":"UTILITY","body":"שלום {{name}}, ההזמנה {{order}} יצאה למשלוח.","vars":["{{name}}","{{order}}"],"header":null,"footer":null,"buttons":[],"params":{"body":2,"named":["name","order"],"header":"none","headerVariable":false,"buttons":[]},"rejectedReason":null,"rejectedReasonHe":null,"qualityScore":"GREEN"}}}}}},"400":{"description":"קלט שגוי — `text` מסביר, `details` מפרט (למשל missing/unknown בפרמטרים נקובים)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"לא נמצא — או ששייך לעסק אחר","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"התנגשות — חלון-מענה סגור (`details.action:\"template\"`), תבנית לא-מאושרת, אין מופע מופעל (`details.code:\"channel-unavailable\"`), בקשה אידמפוטנטית עדיין רצה, מופע-ווטסאפ שאינו מחובר למטא (`details.code:\"not-connected\"`), שם-תבנית שכבר קיים (`details.code:\"template-exists\"`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"ספק חיצוני (מטא/ערוץ) החזיר שגיאה — `details.messageId` כשההודעה נשמרה כ-failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"מחיקת תבנית (כל השפות של השם)","x-summary-en":"Delete a template","description":"מטא מוחקת לפי **שם**, כלומר את כל גרסאות-השפה שלו יחד — אין מחיקה של שפה בודדת. הקיום נבדק לפני המחיקה, ולכן שם שאינו קיים הוא 404 ולא שגיאת-ספק. מחיקה אינה הפיכה, ושליחה של תבנית שנמחקה תיכשל.","x-wehub-notes":["המחיקה היא לפי **שם** — כל גרסאות-השפה של אותו שם נמחקות יחד. אין מחיקה של שפה בודדת.","שם שאינו קיים במופע ⇒ 404 (הקיום נבדק לפני שפונים למטא), ולא שגיאת-ספק.","המחיקה אינה הפיכה: שליחה של תבנית שנמחקה תיכשל, וכדי להחזיר אותה צריך ליצור מחדש ולעבור שוב בדיקת-תוכן."],"operationId":"deleteTemplatesName","tags":["templates"],"security":[{"apiKey":[]}],"x-wehub-scope":"templates:write","x-wehub-scopes":["templates:write"],"parameters":[{"name":"name","in":"path","required":true,"description":"שם התבנית","schema":{"type":"string"}},{"name":"instanceId","in":"query","required":false,"description":"ברירת-מחדל: המופע הראשי (wa)","schema":{"type":"string"}}],"responses":{"200":{"description":"בהצלחה","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"name":{"type":"string"},"instanceId":{"type":"string"}},"required":["ok","name","instanceId"]},"examples":{"default":{"value":{"ok":true,"name":"order_shipped","instanceId":"wa"}}}}}},"400":{"description":"קלט שגוי — `text` מסביר, `details` מפרט (למשל missing/unknown בפרמטרים נקובים)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"לא נמצא — או ששייך לעסק אחר","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"התנגשות — חלון-מענה סגור (`details.action:\"template\"`), תבנית לא-מאושרת, אין מופע מופעל (`details.code:\"channel-unavailable\"`), בקשה אידמפוטנטית עדיין רצה, מופע-ווטסאפ שאינו מחובר למטא (`details.code:\"not-connected\"`), שם-תבנית שכבר קיים (`details.code:\"template-exists\"`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"ספק חיצוני (מטא/ערוץ) החזיר שגיאה — `details.messageId` כשההודעה נשמרה כ-failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"get":{"summary":"רשימת ה-webhooks היוצאים","x-summary-en":"List outgoing webhooks","operationId":"getWebhooks","tags":["webhooks"],"security":[{"apiKey":[]}],"x-wehub-scope":"webhooks:manage","x-wehub-scopes":["webhooks:manage"],"responses":{"200":{"description":"בהצלחה","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}},"required":["items"]},"examples":{"default":{"value":{"items":[{"id":"01J8XM3P7Q2R5T8V1W4Y6Z9BCD","url":"https://example.com/wehub","events":["message.received","message.delivered"],"active":true,"secretMasked":"whsec_…","createdAt":"2026-09-04T09:00:00.000Z","lastDeliveryAt":"2026-09-04T10:12:05.000Z","failing":false}]}}}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"יצירת webhook יוצא","x-summary-en":"Create an outgoing webhook","description":"הסוד מוחזר פעם אחת בלבד. הוא החותם של x-wehub-signature.\n\n**היקף נוסף בהתניה:** מנוי לאירועי-תוכן (`message.*`, `conversation.*`, `csat.*`, `call.*`) דורש **גם** `conversations:read`, כי גוף-האירוע נושא את תוכן-ההודעה. מפתח בלי ההיקף הזה מקבל `403`.\n\n**האירועים:** `message.received` — הודעה נכנסת (כל ערוץ); `message.sent` — הודעה יוצאת נשלחה בפועל; `message.delivered` — הודעה יוצאת נמסרה ללקוח; `message.read` — הודעה יוצאת נקראה; `message.failed` — שליחת הודעה נכשלה; `conversation.opened` — שיחה חדשה נפתחה; `conversation.closed` — שיחה נסגרה; `conversation.assigned` — רשימת-האחראים בשיחה השתנתה; `csat.received` — הלקוח דירג את השירות; `call.ended` — שיחת-טלפון הסתיימה; `template.status_changed` — סטטוס תבנית ווטסאפ השתנה (אושרה / נדחתה / הושהתה).","operationId":"postWebhooks","tags":["webhooks"],"security":[{"apiKey":[]}],"x-wehub-scope":"webhooks:manage","x-wehub-scopes":["webhooks:manage"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"https בלבד; כתובות פנימיות נדחות"},"events":{"type":"array","items":{"type":"string","enum":["message.received","message.sent","message.delivered","message.read","message.failed","conversation.opened","conversation.closed","conversation.assigned","csat.received","call.ended","template.status_changed"]}},"active":{"type":"boolean"}},"required":["url","events"]},"examples":{"default":{"value":{"url":"https://example.com/wehub","events":["message.received","message.delivered","message.failed"]}}}}}},"responses":{"201":{"description":"בהצלחה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreated"},"examples":{"default":{"value":{"id":"01J8XM3P7Q2R5T8V1W4Y6Z9BCD","url":"https://example.com/wehub","events":["message.received","message.delivered"],"active":true,"secretMasked":"whsec_…","createdAt":"2026-09-04T09:00:00.000Z","lastDeliveryAt":"2026-09-04T10:12:05.000Z","failing":false,"secret":"whsec_9f2c…(מוצג פעם אחת)"}}}}}},"400":{"description":"קלט שגוי — `text` מסביר, `details` מפרט (למשל missing/unknown בפרמטרים נקובים)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"התנגשות — חלון-מענה סגור (`details.action:\"template\"`), תבנית לא-מאושרת, אין מופע מופעל (`details.code:\"channel-unavailable\"`), בקשה אידמפוטנטית עדיין רצה, מופע-ווטסאפ שאינו מחובר למטא (`details.code:\"not-connected\"`), שם-תבנית שכבר קיים (`details.code:\"template-exists\"`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}":{"get":{"summary":"webhook בודד","x-summary-en":"Get a webhook","operationId":"getWebhooksId","tags":["webhooks"],"security":[{"apiKey":[]}],"x-wehub-scope":"webhooks:manage","x-wehub-scopes":["webhooks:manage"],"parameters":[{"name":"id","in":"path","required":true,"description":"ה-ULID של המנוי","schema":{"type":"string"}}],"responses":{"200":{"description":"בהצלחה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"},"examples":{"default":{"value":{"id":"01J8XM3P7Q2R5T8V1W4Y6Z9BCD","url":"https://example.com/wehub","events":["message.received","message.delivered"],"active":true,"secretMasked":"whsec_…","createdAt":"2026-09-04T09:00:00.000Z","lastDeliveryAt":"2026-09-04T10:12:05.000Z","failing":false}}}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"לא נמצא — או ששייך לעסק אחר","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"עדכון webhook","x-summary-en":"Update a webhook","description":"**היקף נוסף בהתניה:** מנוי לאירועי-תוכן (`message.*`, `conversation.*`) דורש **גם** `conversations:read`.","operationId":"patchWebhooksId","tags":["webhooks"],"security":[{"apiKey":[]}],"x-wehub-scope":"webhooks:manage","x-wehub-scopes":["webhooks:manage"],"parameters":[{"name":"id","in":"path","required":true,"description":"ה-ULID של המנוי","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["message.received","message.sent","message.delivered","message.read","message.failed","conversation.opened","conversation.closed","conversation.assigned","csat.received","call.ended","template.status_changed"]}},"active":{"type":"boolean"}}},"examples":{"default":{"value":{"active":false}}}}}},"responses":{"200":{"description":"בהצלחה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"},"examples":{"default":{"value":{"id":"01J8XM3P7Q2R5T8V1W4Y6Z9BCD","url":"https://example.com/wehub","events":["message.received","message.delivered"],"active":false,"secretMasked":"whsec_…","createdAt":"2026-09-04T09:00:00.000Z","lastDeliveryAt":"2026-09-04T10:12:05.000Z","failing":false}}}}}},"400":{"description":"קלט שגוי — `text` מסביר, `details` מפרט (למשל missing/unknown בפרמטרים נקובים)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"לא נמצא — או ששייך לעסק אחר","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"מחיקת webhook (יומן-המשלוחים נשמר)","x-summary-en":"Delete a webhook","operationId":"deleteWebhooksId","tags":["webhooks"],"security":[{"apiKey":[]}],"x-wehub-scope":"webhooks:manage","x-wehub-scopes":["webhooks:manage"],"parameters":[{"name":"id","in":"path","required":true,"description":"ה-ULID של המנוי","schema":{"type":"string"}}],"responses":{"200":{"description":"בהצלחה","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]},"examples":{"default":{"value":{"ok":true}}}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"לא נמצא — או ששייך לעסק אחר","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/deliveries":{"get":{"summary":"יומן-המשלוחים של המנוי","x-summary-en":"List webhook deliveries","description":"מהחדש לישן. `attempt` סופר שליחות שבוצעו; אחרי 6 (שליחה + 5 ניסיונות-חוזרים) המשלוח `exhausted`.","operationId":"getWebhooksIdDeliveries","tags":["webhooks"],"security":[{"apiKey":[]}],"x-wehub-scope":"webhooks:manage","x-wehub-scopes":["webhooks:manage"],"parameters":[{"name":"id","in":"path","required":true,"description":"ה-ULID של המנוי","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"סינון לפי מצב","schema":{"type":"string","enum":["pending","delivered","failed","exhausted"]}},{"name":"limit","in":"query","required":false,"description":"כמה פריטים להחזיר","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"בהצלחה","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}}},"required":["items"]},"examples":{"default":{"value":{"items":[{"id":"01J8XN0000000000000000DEL","webhookId":"01J8XM3P7Q2R5T8V1W4Y6Z9BCD","event":"message.delivered","status":"delivered","attempt":1,"responseStatus":200,"createdAt":"2026-09-04T10:12:05.000Z","deliveredAt":"2026-09-04T10:12:06.000Z"}]}}}}}},"401":{"description":"מפתח חסר או לא תקף","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"למפתח אין את ה-scope הנדרש, או שהעסק מושעה","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"לא נמצא — או ששייך לעסק אחר","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חריגה ממכסת-הקצב של התוכנית — `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"x-wehub-webhook-events":["message.received","message.sent","message.delivered","message.read","message.failed","conversation.opened","conversation.closed","conversation.assigned","csat.received","call.ended","template.status_changed"],"x-wehub-webhook-event-labels":{"message.received":{"he":"הודעה נכנסת (כל ערוץ)","en":"Inbound message (any channel)"},"message.sent":{"he":"הודעה יוצאת נשלחה בפועל","en":"Outbound message sent"},"message.delivered":{"he":"הודעה יוצאת נמסרה ללקוח","en":"Outbound message delivered"},"message.read":{"he":"הודעה יוצאת נקראה","en":"Outbound message read"},"message.failed":{"he":"שליחת הודעה נכשלה","en":"Outbound message failed"},"conversation.opened":{"he":"שיחה חדשה נפתחה","en":"Conversation opened"},"conversation.closed":{"he":"שיחה נסגרה","en":"Conversation closed"},"conversation.assigned":{"he":"רשימת-האחראים בשיחה השתנתה","en":"Conversation assignees changed"},"csat.received":{"he":"הלקוח דירג את השירות","en":"CSAT rating received"},"call.ended":{"he":"שיחת-טלפון הסתיימה","en":"Phone call ended"},"template.status_changed":{"he":"סטטוס תבנית ווטסאפ השתנה (אושרה / נדחתה / הושהתה)","en":"WhatsApp template status changed"}},"x-wehub-smart-send":["יעד: conversationId ⇐ contactPublicId ⇐ to (בסדר הזה, אחד בלבד). `to` כמחרוזת מזוהה אוטומטית: טלפון ⇒ ווטסאפ, מייל ⇒ מייל; לאינסטגרם/מסנג׳ר משתמשים ב-{kind,value} או ב-contactPublicId.","ערוץ (channel:\"auto\", ברירת-המחדל): כשהנמען מוכר כאיש-קשר, נבחרת שיחה קיימת שחלון-המענה שלה פתוח עכשיו — ווטסאפ ⇐ מסנג׳ר ⇐ אינסטגרם ⇐ מייל — כי שם אפשר לכתוב טקסט חופשי בלי תבנית. אחרת: הערוץ הטבעי של הזהות. ערוץ מפורש מכובד תמיד (400 אם לאיש-הקשר אין זהות בו). כינויים: whatsapp / mail / messenger / instagram.","מופע (instanceId): המופע שכבר מנהל שיחה עם הנמען ⇐ מופע-ברירת-המחדל של הערוץ אם מופעל ⇐ המופע המופעל הראשון ⇐ 409 עם details.code=\"channel-unavailable\". מופע מפורש חייב להיות מהסוג של הערוץ ומופעל.","תוכן: text בלבד ⇒ טקסט חופשי (חלון סגור ⇒ 409 עם details.action=\"template\"). template בלבד ⇒ תבנית מאושרת. text + template יחד ⇒ הטקסט אם החלון פתוח, אחרת התבנית — והתשובה אומרת מה יצא ב-`sent`.","media.url ⇒ השרת מוריד (https ציבורי, עד 15MB, image/* · video/mp4 · audio/* · pdf · doc/docx/xls/xlsx), שומר ושולח כ-image/video/audio/document, עם caption אופציונלי. media לא משתלב עם text או template. מייל: אין קבצים דרך ה-API (409).","מייל: text הוא גוף ההודעה, subject רשות (ברירת-מחדל \"Re: <נושא-השיחה>\" או \"הודעה מ-<שם-העסק>\"). תבנית למייל ⇒ 409.","פרמטרים נקובים: template.body כאובייקט ממופה למשתני התבנית לפי שמם ({{customer_name}}); שם חסר או לא-מוכר ⇒ 400 עם missing/unknown/expected. מערך = מיקומי כמו קודם.","אידמפוטנטיות: idempotencyKey בגוף או Idempotency-Key בכותרת. אותו מפתח ב-24 השעות הבאות מחזיר את התשובה המקורית (200, replayed:true) ולא שולח שוב. בקשה שנכשלה משחררת את המפתח; בקשה שעדיין רצה ⇒ 409 details.code=\"idempotency-in-flight\".","אידמפוטנטיות — הגבולות: המפתח כרוך בתוכן הבקשה. אותו idempotencyKey עם יעד או תוכן אחרים ⇒ 422 details.code=\"idempotency-key-reused\" (ולא התשובה הישנה בשקט); סדר-שדות שונה באותו תוכן אינו \"תוכן אחר\". מרחב-המפתחות הוא פר-מפתח-API, ולכן שתי אינטגרציות של אותו עסק יכולות להשתמש באותו מזהה-הזמנה בלי להתנגש.","mock:true פירושו שהשער היוצא סגור בסביבה הזו (פיתוח/בדיקות/העסק לא הופעל לשליחה חיה): ההודעה נרשמה בדסק ולא יצאה ללקוח. mockReasons[] מסביר. לא לפרש כמסירה.","מסירה: status בתשובה הוא מיידי (sent/failed). delivered/read מגיעים אחר-כך — ב-webhooks message.delivered / message.read / message.failed, או בפולינג GET /messages/{id}."],"x-wehub-templates":["מפתח-בדיקה (wh_test_) קורא תבניות ואינו משנה אותן: POST /templates, POST /templates/header-media ו-DELETE /templates/{name} מחזירים 403 details.code=\"test-key-readonly\". ניהול-תבניות נוגע ב-WABA האמיתי של העסק — מחיקה מפילה את השם על כל שפותיו ודורשת אישור-מחדש של מטא — ולכן היא דורשת מפתח live.","מחזור-חיים: יצירה ⇒ PENDING (\"ממתינה לאישור\") ⇒ APPROVED או REJECTED. מטא יכולה גם להשהות (PAUSED) או להשבית (DISABLED) תבנית מאושרת לפי איכות ותלונות. רק APPROVED ניתנת לשליחה. ההתראה על כל מעבר היא ה-webhook `template.status_changed`; `GET /templates/{name}?language=` הוא הפולינג המקביל.","קטגוריה: UTILITY (עדכון על עסקה קיימת — הזמנה, תור, משלוח) או MARKETING (פנייה יזומה). מטא בודקת את התוכן מול הקטגוריה, ותוכן מכירתי ב-UTILITY הוא סיבת-דחייה מתועדת. AUTHENTICATION (OTP) אינה נתמכת ליצירה דרך ה-API.","כותרת: טקסט עד 60 תווים עם עד 1 משתנה (ואז `example` חובה), או מדיה — תמונה/וידאו/מסמך — שמועלית מראש ב-`POST /templates/header-media` ומועברת כ-`header.handle`. אפשר גם `{type:\"location\"}`.","גוף: עד 1024 תווים. משתנים מיקומיים `{{1}}`,`{{2}}` ברצף בלי דילוגים, או נקובים `{{customer_name}}`. הגוף לא יכול להתחיל או להסתיים במשתנה, וצריך דוגמה אחת ב-`examples` לכל משתנה — מטא בודקת את התבנית דרכן.","תחתית: עד 60 תווים, בלי משתנים.","כפתורים: עד 10 בסך הכול — quick_reply · url · phone_number · copy_code. עד 10 תשובה-מהירה, עד 2 קישור, 1 טלפון, 1 העתקת-קוד. תווית עד 25 תווים; URL עד 2000; דוגמת-קוד עד 20.","כפתורי תשובה-מהירה חייבים להיות רצופים — כולם בתחילת רשימת-הכפתורים או כולם בסופה. \"קישור, תשובה-מהירה, קישור\" נדחה.","כפתור קישור עם משתנה: משתנה אחד בלבד, `{{1}}`, ובסוף ה-URL בלבד, ועם `example`. כפתור העתקת-קוד אינו נושא תווית מותאמת — רק `example`.","שם: אותיות קטנות, ספרות וקו-תחתון, עד 60 תווים. תווים אחרים מומרים לקו-תחתון, ולכן השם בתשובה הוא השם שנוצר בפועל. שם+שפה שכבר קיימים ⇒ 409 עם `details.code:\"template-exists\"`.","שפה: לתבנית אחת יש גרסה נפרדת לכל שפה, עם סטטוס נפרד. `DELETE /templates/{name}` מוחק את **כל** השפות של השם — כך מטא עובדת.","מופע שאינו מחובר למטא ⇒ 409 עם `details.code:\"not-connected\"` (ולא רשימה ריקה ולא 502) — יש להשלים את חיבור ערוץ הווטסאפ בהגדרות."]}