API הודעות

שליחת הודעה בודדת, ניהול תבניות ה־WhatsApp שמהן שולחים, וקריאה של מה שאנשים משיבים.

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

כל נקודות הקצה בעמוד הזה יחסיות לכתובת הבסיס: https://api-eu1.joryio.com/api - ראו סקירת ה־API.

אימות

Authorization: Bearer your_api_key_or_jwt
Content-Type: application/json

שליחת WhatsApp

שליחת הודעת תבנית

POST /whatsapp/send/template

הדבר היחיד שאפשר לשלוח למי שנמצא מחוץ לחלון שיחה פתוח של 24 שעות. התבנית חייבת להיות מאושרת מראש על ידי Meta.

{
  "to": "+306912345678",
  "templateName": "order_shipped",
  "language": "en",
  "variables": { "1": "Alex", "2": "GR-40921" }
}

שליחת הודעת שיחה

POST /whatsapp/send/text

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

{ "to": "+306912345678", "text": "Your order is out for delivery." }

תבניות

GET /whatsapp/templates
POST /whatsapp/templates

כל התבניות עם סטטוס האישור שלהן. רק תבניות APPROVED ניתנות לשליחה. יצירת תבנית שולחת אותה לאישור Meta - האישור אינו מיידי ועשוי להידחות.

{
  "templates": [
    { "name": "order_shipped", "language": "en", "status": "APPROVED",
      "category": "UTILITY", "variables": 2 }
  ]
}

תבניות SMS (Delivyr בלבד)

Delivyr בלבד. הנתיבים האלה עובדים רק בסביבת עבודה שמספר ה-SMS שלה מקושר לחשבון Delivyr. Delivyr שולחת רק תבניות שהיא אישרה, ורק למספרים בארצות הברית ובקנדה. בכל סביבת עבודה אחרת, כל נתיב מלבד GET /sms/templates/accounts מחזיר 403 עם code: "delivyr_account_required":

{ "statusCode": 403, "code": "delivyr_account_required",
  "message": "SMS templates are available only to workspaces that send SMS through a Delivyr account. Connect one under Integrations > Delivyr." }

קריאה דורשת templates:read. יצירה, רענון ומחיקה דורשים templates:write.

רשימת חשבונות ה-Delivyr של סביבת העבודה

מחזיר [] כשאין חשבון, כך שלקוח יכול לבדוק לפני כל קריאה אחרת. key הוא ה-accountKey שהנתיבים האחרים מקבלים.

GET /sms/templates/accounts

[
  { "key": "6f1c2a9e-3b4d-4e5f-8a7b-9c0d1e2f3a4b", "smsAccountId": "6f1c2a9e-3b4d-4e5f-8a7b-9c0d1e2f3a4b",
    "provider": "delivyr", "name": "Delivyr US" }
]

רשימת תבניות

מסננים אופציונליים: status (pending, approved, rejected, system) ו-accountKey. אפשר לשלוח רק תבניות approved ו-system. mappableVariables הם המשתנים שממלאים לכל איש קשר; את האחרים (account_dba) Delivyr ממלאת בעצמה.

GET /sms/templates?status=approved

[
  { "id": "1d2e3f40-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "accountKey": "6f1c2a9e-3b4d-4e5f-8a7b-9c0d1e2f3a4b",
    "provider": "delivyr", "providerTemplateId": "NMPNWAS6", "title": "We Miss You",
    "body": "Hi {{first_name}}, we miss you: {{link}}", "status": "approved", "source": "portal",
    "variables": ["first_name", "link"], "mappableVariables": ["first_name", "link"] }
]

רענון מ-Delivyr

שולף עכשיו מ-Delivyr את התבניות של החשבון, כולל תבניות שנוצרו בפורטל של Delivyr, ומעדכן את סטטוס הבדיקה שלהן. Joryio מרעננת גם כל 30 דקות. גוף אופציונלי: { "accountKey": "..." }.

POST /sms/templates/sync

{ "results": [ { "accountKey": "6f1c2a9e-3b4d-4e5f-8a7b-9c0d1e2f3a4b", "added": 2, "updated": 5, "removed": 0, "total": 7 } ] }

יצירת תבנית

שולח את התבנית לבדיקה של Delivyr. התבנית מתחילה כ-pending, והסטטוס משתנה אחרי הבדיקה. השתמשו במשתנים מסוג {{name}}. שימו {{link}} במקום שבו צריך להופיע קישור, ו-Joryio ממלאת אותו בקישור מקוצר ומנוטר משלה בזמן השליחה. צריך accountKey רק כשסביבת העבודה שולחת דרך יותר מחשבון Delivyr אחד. אי אפשר לשנות טקסט מאושר: כדי לשנות נוסח, צרו תבנית חדשה.

POST /sms/templates

{
  "title": "Weekend offer",
  "body": "Hi {{first_name}}, your weekend offer is ready: {{link}} Reply STOP to opt out.",
  "tags": ["promo"]
}

קבלת תבנית או מחיקתה

מחיקה מוחקת את התבנית גם ב-Delivyr. אי אפשר למחוק את תבניות המערכת של Delivyr.

GET /sms/templates/:id
DELETE /sms/templates/:id

שימוש ומגבלות

GET /whatsapp/usage?period=monthly&startDate=2026-08-01&endDate=2026-08-31
GET /whatsapp/usage/limits?wabaId=waba_120363

WhatsApp מחייבת לפי שיחה בת 24 שעות ולא לפי הודעה, ולכן ספירת הודעות אינה מנבאת עלות. מסלול השימוש מחזיר את שורות השימוש השמורות של חשבונות מרחב העבודה - שורה לכל חשבון ותקופה, מהתקופה החדשה ביותר. פרמטרים (כולם אופציונליים): wabaId (חשבון אחד), period (daily או monthly), startDate / endDate (תאריכי ISO; שורות שתקופתן מתחילה ב-startDate או אחריו ומסתיימת ב-endDate או לפניו). כל שורה נושאת גם organizationId, workspaceId, createdAt ו-updatedAt.

[
  {
    "id": "usage_9f2c", "wabaId": "waba_120363", "period": "monthly",
    "periodStart": "2026-08-01", "periodEnd": "2026-08-31",
    "conversations": { "marketing": 4120, "utility": 8802, "authentication": 310, "service": 1904, "total": 15136 },
    "messages": { "sent": 31204, "delivered": 30877, "read": 22410, "failed": 327, "received": 4810 },
    "estimatedCost": 812.4,
    "currency": "USD"
  }
]

מסלול המגבלות מציג את הרמה ש־Meta מאפשרת למספר שלכם וכמה נוצל - הגעה לתקרה מכשילה שליחות, היא אינה מציבה אותן בתור. wabaId אופציונלי - בלעדיו המגבלות הן של חשבון ברירת המחדל ושלושת נתוני השימוש מוחזרים כ-0, כי שימוש נבדק רק עבור חשבון שצוין בשם.

{
  "tier": "TIER_10K",
  "dailyLimit": 10000,
  "dailyConversations": 3410,
  "monthlyConversations": 41200,
  "monthlyEstimatedCost": 812.4,
  "qualityRating": "GREEN"
}

ההודעות של איש קשר

GET /messages?userId=665f1e2a9b3c4d5e6f7a8b9c&direction=outbound&channel=email&limit=50&offset=0

מה ששלחתם לאיש קשר וגם מה שהוא שלח לכם, מהחדש לישן: כל message.sent מקמפיין או ממסע (אימייל, SMS, WhatsApp, Push, Viber - לא צמתי webhook) והתשובות ש-GET /messages/inbound מחזיר. זו לשונית ההודעות בפרופיל איש הקשר.

פרמטר	תיאור
userId	חובה. מזהה איש הקשר ב-Joryio או ה-externalId שלו. איש קשר לא מוכר מחזיר עמוד ריק.
direction	אופציונלי. outbound (שליחות) או inbound (תשובות); בלי הפרמטר - שניהם.
channel	אופציונלי. ערוץ אחד, למשל email, sms, whatsapp, push.
limit	אופציונלי. ברירת מחדל 50, מוגבל ל-1-200.
offset	אופציונלי. שורות לדלג, ברירת מחדל 0, לכל היותר 5000.

Response:

{
  "data": [
    { "direction": "outbound", "channel": "email", "eventName": "message.sent",
      "timestamp": "2026-10-28 10:00:00.000", "subject": "Your cart is still here",
      "messageId": "0100019a2b3c", "status": "opened",
      "source": { "kind": "journey", "id": "8f0c2d1e-5b7a-4c3e-9f1a-2d3e4f5a6b7c", "name": "Cart recovery" },
      "body": null, "from": null, "toNumber": null, "account": null, "messageType": null },
    { "direction": "inbound", "channel": "sms", "eventName": "sms.message.received",
      "timestamp": "2026-10-27 18:02:00.000", "body": "thanks!", "from": "+306912345678",
      "toNumber": "+302101234567", "account": "Support line", "messageType": "text",
      "subject": null, "messageId": null, "source": null, "status": null }
  ],
  "total": 2
}

שליחה מציינת ב-source מה שלח אותה (kind הוא journey או campaign, ו-name הוא null כשאי אפשר עוד לזהות אותו), את subject של האימייל, ואת status - התוצאה הרחוקה ביותר שנרשמה להודעה: sent, delivered, opened, clicked, או failed / bounced, שגוברים על כל השאר. תשובה כוללת from, toNumber, account ו-body כמו ב-/messages/inbound. הנתיב קורא את 12 החודשים האחרונים; total הוא גודל העמוד, לכן דפדפו עם offset עד שעמוד חוזר קצר מ-limit.

הודעות נכנסות

GET /messages/inbound?userId=665f1e2a9b3c4d5e6f7a8b9c&channel=whatsapp&limit=50&offset=0
GET /sms/messages?userId=665f1e2a9b3c4d5e6f7a8b9c&limit=50

מה שאיש קשר אחד שלח אליכם, ב־WhatsApp וב־SMS - השורות מגיעות מאירועי <channel>.message.received של איש הקשר. userId (מזהה ה-Joryio של איש הקשר, ה-id ש-Users API מחזיר) הוא חובה - בלעדיו המסלול מחזיר עמוד ריק. channel מסנן לערוץ אחד (sms או whatsapp); limit ברירת מחדל 50, מוגבל ל-1-200; offset ברירת מחדל 0. total הוא גודל העמוד שהוחזר ולא ספירה כוללת - דפדפו לפי offset עד שעמוד חוזר קצר מ-limit. אין סמן since במסלול הזה. toNumber הוא המספר שההודעה הגיעה אליו ו-account תווית החשבון המקבל; שניהם null בהודעות שנרשמו לפני שהחלו להיחתם.

{
  "data": [
    { "channel": "whatsapp", "from": "+306912345678", "toNumber": "+302101234567",
      "account": "Support line", "body": "when will it arrive?", "messageType": "text",
      "eventName": "whatsapp.message.received", "timestamp": "2026-08-27T09:41:00Z" }
  ],
  "total": 1
}

GET /sms/messages מחזיר את הודעות ה-SMS של איש קשר (ציר הזמן בפרופיל), מהחדשה לישנה, כמערך JSON. userId חובה - בלעדיו המסלול מחזיר []; limit ברירת מחדל 50, מוגבל ל-1-200. direction הוא inbound או outbound. אין במסלול הזה סטטוס מסירה מהמפעיל - מסירה וכישלון הם אירועים בציר הזמן של איש הקשר (GET /users/:id/events).

[
  { "id": "sms_411", "body": "STOP", "phoneNumber": "+306912345678",
    "direction": "inbound", "messageType": "text", "accountId": "acct_7a1",
    "createdAt": "2026-08-26T18:02:00Z" }
]