שילוב API של Meta & Instagram

התייחסות לבניית אפליקציית אינסטגרם בפלטפורמת SMSBAT ChatHub: אימות, אינסטגרם שיחות ישירות, הערות על פוסטים ו-Reels, תשובות לסיפורים, webhooks וסקר.

---

1. כתובות אתרים בסיסיות

מטרה	כתובת אתר
Chat API + Meta API	https://chatapi.smsbat.com
Swagger UI / OpenAPI	https://chatapi.smsbat.com/index.html · …/swagger/v1/swagger.json
REST API (ארגונים, כתובות URL להתקשרות חוזרת)	https://restapi.smsbat.com
REST API Swagger	https://restapi.smsbat.com/swagger/v1/swagger.json
פאנל אינטרנט של מפעיל	https://chat.smsbat.com

---

2. אימות

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

קבוצה	כותרת
chatapi.smsbat.com/api/meta/* (פוסטים, תגובות)	X-Authorization-Key: <organization token>
chatapi.smsbat.com/api/chat/*, /api/company/*, /api/operator/*	Authorization: Bearer <JWT>
restapi.smsbat.com/*	X-Authorization-Key · Authorization: Bearer · אישור בסיסי

אסימון הארגון עבור X-Authorization-Key מונפק בפאנל תחת פרופיל. JWT של חברה ומפעיל מגיעים מ-/api/company/get-token ו-/api/operator/get-token.

2.1 אסימון חברה

POST https://chatapi.smsbat.com/api/company/get-token
Content-Type: application/json

{ "login": "company_login", "password": "company_password" }

200 OK מחזיר מחרוזת אסימון חשופה.

2.2 ארגונים

GET https://chatapi.smsbat.com/api/company/organization
Authorization: Bearer <company_token>

[ { "id": 24, "name": "My Instagram Store" } ]

2.3 מפעילים בארגון

GET https://chatapi.smsbat.com/api/operator?organizationId=24
Authorization: Bearer <company_token>

[
  {
    "id": 21,
    "name": "Jane Doe",
    "status": 0,
    "organization": { "id": 24, "name": "My Instagram Store" }
  }
]

סטטוסי מפעיל: 0 פעיל, 1 לא פעיל, 2 נמחק.

2.4 הוסף / סנכרון אופרטורים

POST https://chatapi.smsbat.com/api/operator/synchronize
Authorization: Bearer <company_token>
Content-Type: application/json

[ { "organizationId": 24, "name": "John Operator" } ]

200 OK → [ { "id": 21, "status": 0, "name": "John Operator" } ]

2.5 מפעיל JWT

POST https://chatapi.smsbat.com/api/operator/get-token
Authorization: Bearer <company_token>
Content-Type: application/json

{ "id": 21, "expiresAt": "2026-12-31T23:59:59.000Z" }

200 OK מחזיר את ה-JWT כמחרוזת.

2.6 אימות אסימון מפעיל

POST https://chatapi.smsbat.com/api/operator/validate-token
Authorization: Bearer <company_token>
Content-Type: application/json

"eyJhbGciOi..."

{
  "isValid": true,
  "operatorId": 21,
  "clientId": 0,
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "error": null
}

כאשר לא חוקי: { "isValid": false, "error": "Invalid token" }.

2.7 הטמע את לוח הצ’אט של המפעיל

<script type="module" id="operator-chat-panel-script"
  src="https://widget.smsbat.com/operator-chat-panel/widget-script.js"
  token="YOUR_OPERATOR_JWT_TOKEN"></script>

---

3. קישורים עמוקים ללוח הצ’אט

מערכת חיצונית (CRM, ERP, אתר אינטרנט) יכולה לפתוח שיחה ספציפית פנימה https://chat.smsbat.com/. המפעיל מורשה על ידי JWT שהועבר כפרמטר שאילתה.

https://chat.smsbat.com/?chat_raw_id=<chat_id>&token=<jwt>
https://chat.smsbat.com/?phone=<phone>&token=<jwt>
https://chat.smsbat.com/?from=<bm_id>&phone=<phone>&token=<jwt>
https://chat.smsbat.com/?source=7&from=<bm_id>&phone=<phone>&token=<jwt>

פרמטר	תיאור
chat_raw_id	מזהה צ’אט
phone	מספר טלפון בפורמט בינלאומי
from	מזהה חשבון מותג / עסקי (bm_id)
source	מקור צ’אט — 7 לאינסטגרם, ראה §8.1
token	מפעיל JWT חוקי, שטרם פג, עם גישה לצ’אטים

JWT לא חוקי מנחית את המבקר במסך הכניסה של לוח המפעילים.

---

4. שיחות ישירות באינסטגרם

4.1 רשימת צ’אטים

GET https://chatapi.smsbat.com/api/chat/chats?source=7&page=1&per_page=20
Authorization: Bearer <token>

פרמטרי שאילתה, כולם אופציונליים:

פרמטר	הקלד	תיאור
source	ChatSource	7 מגביל את התוצאות לאינסטגרם
entityId	int	מזהה חשבון עסקי. מיושם רק יחד עם source
instagram_user_id	int	מזהה משתמש באינסטגרם ב-ChatHub
facebook_user_id	int	מזהה משתמש בפייסבוק ב-ChatHub
page / per_page	int	עימוד, ברירות מחדל 1 / 20
status	ChatStatus[]	סטטוס צ’אט, ניתן לחזור על עצמו
search	string	חיפוש טקסט חופשי (שם, טלפון,…)
organizationId	int	מזהה ארגון
operatorId	int[]	סנן לפי אופרטורים שהוקצו
date	string[]	שני גבולות: ?date=…&date=…
isChain	bool	החזרת צ’אטים כשרשראות, נושאת הודעות מצ’אטים קודמים
isUnread, starMark, isOperator, isAIAgent	bool	מסננים נוספים
phone, email, contactId, clientId, tagIds, rate, sortedBy	—	מסננים אחרים

200 OK מחזיר GetChatsResponse:

{
  "total": 1,
  "newMessagesCount": 2,
  "items": [
    {
      "id": 1867,
      "theme": null,
      "messSource": 7,
      "chatStatus": 1,
      "countUnread": 2,
      "metaUserId": "1585775752382460",
      "instaAccount": { "id": 12, "name": "my_instagram_shop", "photo": "https://..." },
      "instagramUser": { "id": 123, "name": "marianna_cat", "photo": "https://..." },
      "operator": { "id": 21, "name": "Jane", "photo": "https://..." },
      "client": { "id": 55, "name": "Marianna", "photo": null },
      "textLastMess": "Hello! Is this product available?",
      "timeLastMess": "2026-08-13T10:15:00Z",
      "authorLastMessage": 1,
      "messageStatus": 6,
      "isMedia": false,
      "phone": null,
      "organizationId": 1,
      "createdAt": "2026-08-13T10:14:00Z",
      "isStarred": false,
      "isBlocked": false,
      "tags": []
    }
  ]
}

השדות החשובים לאפליקציית אינסטגרם:

שדה	המשמעות
instaAccount	החשבון העסקי באינסטגרם (החנות). id הוא ערך המסנן entityId; name הוא שם החשבון מ-Meta
instagramUser	הלקוח. name הוא ידית האינסטגרם, id הוא ערך המסנן instagram_user_id
metaUserId	מזהה הטווח של הלקוח בצד של Meta (מחרוזת)
messSource	7 לאינסטגרם
phone	בדרך כלל null לאינסטגרם — אל תשתמש בו כמפתח

ChatDTO נושא גם olxUser, promUser, waba, rozetkaUser, facebookAccount, facebookUser, viberAccount, tgBot, tgUser, viberBot, viberBotUser, widget, media, isConnectedAI, isPromo, rate, rateComment, closedBy, draft, lang, starMark, contactId, contactName, block, isInStopList, stopList, isSmsFallbackEnabled וtaggedMessages.

4.2 הודעות צ’אט

GET https://chatapi.smsbat.com/api/chat/chats/1867/messages?isChain=false
Authorization: Bearer <token>

200 OK מחזיר מערך של ChatMessageDTO:

[
  {
    "id": 9928,
    "chatId": 1867,
    "message": "Hi! Do you have size M in stock?",
    "messageTranslation": null,
    "phone": null,
    "author": 1,
    "source": 7,
    "media": null,
    "replyTo": null,
    "status": 6,
    "date": "2026-08-13T10:14:00Z",
    "operator": null,
    "client": { "id": 123, "name": "marianna_cat", "photo": "https://..." },
    "messageType": 0,
    "isInternal": false,
    "isBroadcast": false,
    "starMark": false,
    "referralGuid": null,
    "postId": null,
    "isConnectedAI": false,
    "organizationId": 1,
    "countUnreadMessages": 0
  }
]

postId מאוכלס כאשר ההודעה מתייחסת לפוסט או סטורי באינסטגרם - העבר אותו ישר בחזרה כ-id / postId אל Meta API. media הוא ChatMediaDTO: { name, format, type, uri, raw, length, isUploaded }.

4.3 שלח הודעה (JSON)

POST https://chatapi.smsbat.com/api/chat/1867/message
Authorization: Bearer <token>
Content-Type: application/json

גוף - SendChatMessageDTO:

{
  "textMessage": "Hello! Yes, size M is available.",
  "author": 0,
  "isInternal": false,
  "replyToMessageId": 9928,
  "appGuid": "550e8400-e29b-41d4-a716-446655440000",
  "media": {
    "name": "item.jpg",
    "format": "image/jpeg",
    "dataBase64": "/9j/4AAQSkZJRg...",
    "type": 1
  }
}

שדה	הקלד	תיאור
textMessage	string?	טקסט הודעה. עשוי להיות ריק כאשר media קיים
author	AuthorMessage?	מפעיל 0, לקוח 1
isInternal	bool?	true מסמן פתק פנימי שלא נמסר ללקוח
replyToMessageId	int?	מזהה ההודעה לה תשובה
appGuid	uuid?	GUID הפניה
media	MediaDTO?	{ name, format, dataBase64, thumbnail, duration, type }

200 OK → { "id": 9930, "messageStatus": 0 }

GUID הפניה עשוי לעבור גם בנתיב: POST /api/chat/{chatId}/{referralGuid}/message (כמו כן …/message/v1, …/message/v2).

4.4 שלח קובץ או סרטון (רב חלקים, v2)

POST https://chatapi.smsbat.com/api/chat/1867/message/v2
Authorization: Bearer <token>
Content-Type: multipart/form-data

שדה טופס	הקלד	תיאור
TextMessage	string	טקסט הודעה
Author	int	מפעיל 0, לקוח 1
IsInternal	bool	הערה פנימית
ReplyToMessageId	int	הודעה בתשובה
AppGuid	uuid	GUID הפניה
Media.File	binary	הקובץ עצמו
Media.Name	string	שם הקובץ
Media.Format	string	סוג MIME (video/mp4, image/png, application/pdf)
Media.Type	MediaType	ראה §8.5
Media.DataBase64	string	חלופה ל-Media.File
Media.Thumbnail	string	מסגרת תצוגה מקדימה של וידאו Base64
Media.Duration	double	משך הסרטון בשניות

curl -X POST "https://chatapi.smsbat.com/api/chat/1867/message/v2" \
  -H "Authorization: Bearer <token>" \
  -F "TextMessage=Here is the price list" \
  -F "Author=0" \
  -F "Media.Type=2" \
  -F "Media.File=@./price.pdf"

200 OK → { "id": 9931, "messageStatus": 0 }

4.5 שנה סטטוס צ’אט

PUT https://chatapi.smsbat.com/api/chat/status
Authorization: Bearer <token>
Content-Type: application/json

{ "id": 1867, "status": 4 }

200 OK מהדהד את האובייקט המעודכן.

4.6 עדכן סטטוסים של הודעות

PUT https://chatapi.smsbat.com/api/chat/messages/status
Authorization: Bearer <token>
Content-Type: application/json

{ "status": 3, "messageIds": [9928, 9929] }

4.7 מחק צ’אט

DELETE https://chatapi.smsbat.com/api/chat/chats/1867
Authorization: Bearer <token>

---

5. פוסטים, סלילים וסיפורים

נתיב בסיס: https://chatapi.smsbat.com/api/meta אישור: X-Authorization-Key: <organization token>

5.1 רשימת פוסטים, סלילים וסיפורים

GET https://chatapi.smsbat.com/api/meta/posts?platform=instagram&mediaType=story&page=1&perPage=20
X-Authorization-Key: <token>

פרמטר	הקלד	חובה	תיאור
page	int	לא	עמוד, ברירת מחדל 1
perPage	int	לא	פריטים בעמוד, ברירת מחדל 20
id	int	לא	סנן לפי מזהה פוסט פנימי
platform	string	לא	instagram או facebook
mediaType	string	לא	post, reel או story. כל הסוגים כשהם מושמטים

# Every post
curl -H "X-Authorization-Key: <token>" \
  "https://chatapi.smsbat.com/api/meta/posts?page=1&perPage=10"

# Instagram only
curl -H "X-Authorization-Key: <token>" \
  "https://chatapi.smsbat.com/api/meta/posts?platform=instagram"

# A single post by ID
curl -H "X-Authorization-Key: <token>" \
  "https://chatapi.smsbat.com/api/meta/posts?id=42"

# Instagram Stories only
curl -H "X-Authorization-Key: <token>" \
  "https://chatapi.smsbat.com/api/meta/posts?platform=instagram&mediaType=story"

200 OK:

{
  "total": 42,
  "items": [
    {
      "id": 42,
      "metaId": "18113450675314072",
      "text": "Check out our new collection!",
      "imageUrl": "https://dashboard.smsbat.com/api/meta/post/media/7d124c36-1711-4aa8-b21d-f6dbf8f347ef",
      "platform": "instagram",
      "mediaType": "story",
      "createdAt": "2026-07-22T09:35:30Z",
      "story": {
        "id": 42,
        "metaId": "18113450675314072",
        "url": "https://dashboard.smsbat.com/api/meta/post/media/7d124c36-1711-4aa8-b21d-f6dbf8f347ef"
      }
    }
  ]
}

שדה	תיאור
id	מזהה פוסט פנימי
metaId	פוסט חיצוני / סליל / מזהה סיפור במטא
text	כיתוב פוסט
imageUrl	כתובת האתר של מדיה פרוקסי ממוקמת על ידי ה-MetaPost.Guid, או null הלא רציף
platform	facebook או instagram
mediaType	post, reel או story
createdAt	תאריך יצירה (תאריך פלטפורמה, או תאריך מסד הנתונים)
story	הצג בלבד עבור mediaType: "story"
story.id	מזהה סיפור פנימי; שווה ל-post.id
story.metaId	מזהה סיפור חיצוני במטא
story.url	כתובת פרוקסי יציבה של מדיית ה-Story המאוחסנת; null אם לא ניתן היה לשמור את המדיה

מדיה לפוסט מוגשת בשני מסלולים: GET /api/meta/post/media/{id:int} לאחור תאימות ו-GET /api/meta/post/media/{guid:guid}. תגובות API חדשות והתקשרויות חוזרות תמיד ליצור את טופס ה-GUID.

5.2 רשימת הערות

GET https://chatapi.smsbat.com/api/meta/comments?platform=instagram&postId=42&page=1&perPage=20
X-Authorization-Key: <token>

פרמטר	הקלד	חובה	תיאור
page	int	לא	עמוד, ברירת מחדל 1
perPage	int	לא	פריטים בעמוד, ברירת מחדל 20
postId	int	לא	סנן לפי מזהה פוסט
parentCommentId	int	לא	הערות ילדים (תגובות) של הערה נתונה
platform	string	לא	facebook או instagram

200 OK:

{
  "total": 100,
  "items": [
    {
      "id": 5,
      "metaId": "179000000000005",
      "text": "What is the price?",
      "createdAt": "2026-04-15T10:30:00Z",
      "platform": "instagram",
      "replyStatus": null,
      "author": {
        "type": "meta_user",
        "name": "John Doe",
        "metaUserId": "1585775752382460"
      },
      "post": {
        "id": 1,
        "metaId": "18113450675314072",
        "text": null,
        "imageUrl": "https://dashboard.smsbat.com/api/meta/post/media/7d124c36-…",
        "createdAt": "2026-07-22T09:35:30Z",
        "mediaType": "story",
        "story": {
          "id": 1,
          "metaId": "18113450675314072",
          "url": "https://dashboard.smsbat.com/api/meta/post/media/7d124c36-…"
        }
      },
      "mediaUrl": "https://chatapi.smsbat.com/api/meta/comment/media/5",
      "replyTo": {
        "id": 3,
        "metaId": "179000000000003",
        "text": "Parent comment..."
      }
    }
  ]
}

שדה	תיאור
id	מזהה הערה פנימית
metaId	מזהה חיצוני במטא. null לתשובה ממתינה שלנו עד שליחתה
text	טקסט תגובה
createdAt	תאריך יצירה
platform	facebook או instagram
replyStatus	null להערת משתמש נכנסת; "pending" / "sent" / "failure" לתשובתנו
author.type	"meta_user" משתמש חיצוני, בעל דף "owner"
author.name	שם המחבר
author.metaUserId	מזהה משתמש בהיקף ב-Meta; null עבור "owner"
post	הפוסט, ה-Reel או ה-Story שהתגובה שייכת לו
post.mediaType	post, reel או story
post.story	הפניה לסיפור { id, metaId, url }, סיפורים בלבד
mediaUrl	מדיה מצורפת לתגובה, או null
replyTo	הערת הורה { id, metaId, text }; null ברמה העליונה

5.3 השב להערה

תור תשובה למשלוח.

curl -X POST \
  -H "X-Authorization-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{"text": "Thanks for the feedback!"}' \
  "https://chatapi.smsbat.com/api/meta/comments/5/reply"

גוף הבקשה: { "text": "Reply text" }

202 Accepted מחזיר את אובייקט ההערה - אותה צורה כמו GET /api/meta/comments - עם replyStatus: "pending" ו-metaId: null. תוצאת המסירה מגיעה מאוחר יותר בתור א source: 13 התקשרות חוזרת (§6.4).

---

6. Webhooks

SMSBAT שולח בקשות POST עם application/json לכתובת האתר שלך ומצפה ל-HTTP 200 בחזרה.

6.1 רשום כתובת URL להתקשרות חוזרת

curl -X POST 'https://restapi.smsbat.com/organizations/callback_urls' \
  -H 'X-Authorization-Key: <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://your-server.com/webhook",
    "source": 12,
    "headerName": "X-Webhook-Secret",
    "headerValue": "your-secret",
    "channelType": 7,
    "channelEntityId": 12
  }'

שדה	הקלד	תיאור
url	string	נקודת הקצה שלך
source	SendingSourceCallback	סוג אירוע, ראה §8.2
headerName / headerValue	string	כותרת אישור שרירותית שאנו מצרפים לבקשה (אופציונלי)
channelType	ChatSource	ערוץ. 7 לאינסטגרם. אופציונלי
channelEntityId	int	חשבון עסקי ספציפי. דורש channelType

ללא channelType כתובת האתר מקבלת אירועים מכל ערוץ.

פעולות שנותרו:

GET    https://restapi.smsbat.com/organizations/callback_urls?source=12
GET    https://restapi.smsbat.com/organizations/callback_urls/{id}
PUT    https://restapi.smsbat.com/organizations/callback_urls/{id}
DELETE https://restapi.smsbat.com/organizations/callback_urls/{id}

GET מחזיר:

[
  {
    "id": 101,
    "url": "https://your-server.com/webhook",
    "source": 12,
    "headerName": "X-Webhook-Secret",
    "headerValue": "your-secret",
    "createdAt": "2026-08-13T09:00:00Z",
    "channelType": 7,
    "channelEntityId": 12
  }
]

6.2 הודעה חדשה ותגובה לסטורי באינסטגרם (source: 3, 11)

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

{
  "ChatId": 123,
  "MessageId": 456,
  "MessageText": "😍",
  "Username": "Jane Smith",
  "UserId": 789,
  "MetaUserId": "1585775752382460",
  "ShopId": 12,
  "ShopName": "instagram shop name",
  "Author": 0,
  "type_messenger": 7,
  "Story": {
    "Id": 42,
    "MetaId": "18113450675314072",
    "Url": "https://dashboard.smsbat.com/api/meta/post/media/7d124c36-1711-4aa8-b21d-f6dbf8f347ef"
  }
}

שדה	תיאור
ChatId / MessageId	מזהי צ’אט והודעות
Author	משתמש 0, אופרטור 1
Username	שם תצוגה או ידית אינסטגרם / פייסבוק
UserId	מזהה משתמש מספרי פנימי ב-SMSBAT
MetaUserId	מזהה בהיקף של שותף השיחה במטא. בהודעת מפעיל יוצאת זה עדיין מזהה את משתמש המטה של ​​הצ’אט, לא את המפעיל
ShopId	מזהה פנימי של החשבון העסקי של אינסטגרם / פייסבוק
ShopName	שם חשבון העסק כפי שהתקבל מ-Meta בזמן החיבור
MessageText	טקסט הודעה
MessageMedia	כתובת URL של מדיה כאשר ההודעה היא מדיה
type_messenger	מקור, 7 עבור אינסטגרם
operator_name	שם המפעיל כאשר Author = 1
Story	הצג רק בתשובת סיפור נכנסת
Story.Id	מזהה סיפור פנימי (MetaPost) — ניתן לשימוש ישירות בתור id / postId בממשק API של Meta
Story.MetaId	מזהה סיפור חיצוני במטא
Story.Url	כתובת פרוקסי יציבה של מדיית ה-Story המאוחסנת. נעדר כאשר לא ניתן היה לשמור את המדיה — החסימה Story וההודעה עדיין נשלחות

6.3 תגובה חדשה (source: 12)

נדלק כאשר משתמש Meta מגיב על פוסט בפייסבוק או פוסט / סליל באינסטגרם.

{
  "type": "new_comment",
  "platform": "instagram",
  "comment": {
    "id": 10,
    "metaId": "179000000000010",
    "parentCommentId": 5,
    "parentMetaId": "179000000000005",
    "parentCommentText": "The user's previous comment",
    "text": "Great product!",
    "createdAt": "2026-04-16T12:00:00Z",
    "author": {
      "type": "meta_user",
      "name": "Jane Smith",
      "metaUserId": "1585775752382460"
    }
  },
  "post": {
    "id": 1,
    "metaId": "123456789012345",
    "text": "Post description...",
    "imageUrl": "https://dashboard.smsbat.com/api/meta/post/media/7d124c36-…",
    "createdAt": "2026-04-10T12:00:00Z",
    "mediaType": "post"
  }
}

6.4 סטטוס תגובה לתגובה (source: 13)

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

{
  "type": "comment_status",
  "platform": "instagram",
  "comment": {
    "id": 15,
    "metaId": "179000000000015",
    "parentCommentId": 10,
    "parentMetaId": "179000000000010",
    "parentCommentText": "Great product!",
    "text": "Thanks for the feedback!",
    "createdAt": "2026-04-16T12:05:00Z",
    "updatedAt": "2026-04-16T12:05:03Z",
    "replyStatus": "sent",
    "author": {
      "type": "owner",
      "name": "Support Agent"
    }
  },
  "post": {
    "id": 1,
    "metaId": "179999999999999",
    "text": "Reel description...",
    "imageUrl": "https://dashboard.smsbat.com/api/meta/post/media/7d124c36-…",
    "createdAt": "2026-07-22T09:35:30Z",
    "mediaType": "reel"
  }
}

6.5 שדות התקשרות חוזרת של הערות משותפות

שתי ההתקשרויות חוזרות לתגובות חולקות מבנה גוף אחד ונבדלות רק ב-type.

שדה	תיאור
type	"new_comment" או "comment_status"
platform	"facebook" או "instagram"
comment.id	מזהה הערה פנימית
comment.metaId	מזהה חיצוני במטא; null לתשובה ממתינה לפני שליחתה
comment.parentCommentId	מזהה הערה של הורה. נעדר לתגובה ברמה העליונה
comment.parentMetaId	מזהה הערת הורה חיצוני. נעדר ברמה העליונה
comment.parentCommentText	טקסט הערת הורה. נעדר ברמה העליונה
comment.text	טקסט תגובה
comment.createdAt	תאריך יצירה
comment.updatedAt	עדכון אחרון. נעדר אם התגובה מעולם לא נערכה
comment.replyStatus	"pending" / "sent" / "failure". נעדר להערת משתמש נכנסת
comment.author.type	"meta_user" או "owner"
comment.author.name	שם המחבר
comment.author.metaUserId	מזהה מחבר בהיקף במטא. נעדר עבור "owner"
comment.mediaUrl	תקשורת תגובה. נעדר כאשר אין
post.id	מזהה פוסט פנימי
post.metaId	פוסט חיצוני / סליל / מזהה סיפור במטא
post.text	טקסט פוסט
post.imageUrl	כתובת אתר של תמונה, או null
post.createdAt	תאריך יצירת הפוסט
post.mediaType	בהתקשרויות חוזרות, רק post או reel

6.6 צ’אט חדש (source: 7)

{ "ChatId": 12345, "Phone": "+380501234567", "chat.Source": 7 }

6.7 שינויים בסטטוס הודעות וצ’אט (source: 6 / 5)

{ "name": "changed_message_status", "id": 9928, "status": 6 }
{ "name": "changed_chat_status",    "id": 1867, "status": 4 }

6.8 הודעה נערך או נמחקה (source: 9)

{ "messageId": 9930, "text": "Updated message text" }
{ "messageId": 9931, "delete": true }

6.9 מחוון הקלדה (source: 8)

{ "chat_id": 1867, "event": "start_typing", "operator_name": "Iryna" }
{ "chat_id": 1867, "event": "end_typing" }

---

7. סקרים לאירועים

עבור סביבות שאינן יכולות לקבל HTTP נכנס.

7.1 אחזור אירועים

GET https://chatapi.smsbat.com/api/chat/callback-events?page=1&perPage=20
Authorization: Bearer <token>

פרמטר	תיאור
organizationId	אופציונלי. נלקח מהאסימון כשהושמט
page / perPage	עימוד, ברירות מחדל 1 / 20

{
  "page": 1,
  "perPage": 20,
  "total": 947,
  "items": [
    {
      "ChatId": 1867,
      "MessageId": 9928,
      "MessageText": "Hello there!",
      "MessageMedia": null,
      "Phone": null,
      "Username": "marianna_cat",
      "UserId": 123,
      "ShopId": 12,
      "ShopName": "instagram shop name",
      "Author": 1,
      "type_messenger": 7,
      "message_date": "2026-08-13T12:27:39.724Z",
      "timestamp": "2026-08-13T12:27:39.736Z",
      "event_guid": "ff60129e-c6e4-4876-9d90-badb430c0606",
      "organization_id": 1,
      "callback_type": "3"
    }
  ]
}

כל אירוע נושא את event_guid, timestamp, organization_id וcallback_type - א מחרוזת התואמת את ערכי source ב-§8.2. שאר השדות תואמים את השדות המתאימים webhook ב-§6.

7.2 אישור אירועים מעובדים

POST https://chatapi.smsbat.com/api/chat/callback-events/processed
Authorization: Bearer <token>
Content-Type: application/json

[ "ff60129e-c6e4-4876-9d90-badb430c0606" ]

200 OK → { "deleted": 1 }

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

7.3 לולאה מומלצת

1. סקר GET /api/chat/callback-events על לוח זמנים.
2. עבדו את האירועים בשירותכם.
3. שלח את רשימת event_guid המעובד אל /callback-events/processed.
4. חזור על הפעולה.

---

8. הפניה ל-Enum

8.1 ChatSource — ערוץ (0–9)

קוד	ערוץ
0	Viber
1	ViberBot
2	TelegramBot
3	וואטסאפ
4	יישומון
5	רוזטקה
6	פייסבוק
7	אינסטגרם
8	נשף
9	אולקס

8.2 SendingSourceCallback — סוג אירוע התקשרות חוזר (0–13)

קוד	אירוע
3	Chat - הודעת צ’אט חדשה, כולל תשובות סיפור
5	סטטוס הצ’אט השתנה
6	סטטוס ההודעה השתנה
7	צ’אט חדש נוצר
8	מחוון הקלדה
9	ההודעה עודכנה או נמחקה
11	AnyChatMessage — כל הודעת צ’אט
12	MetaNewComment — תגובה חדשה באינסטגרם / פייסבוק
13	MetaCommentStatus — סטטוס מסירה של תשובת התגובה שלנו

המצוין משתרע על 0–13; הערכים הנותרים אינם נחוצים עבור שילובי אינסטגרם.

8.3 ChatStatus (0–4)

0 חדש, 1 פתוח, 2 ממתין, 3 OnPause, 4 סגור

8.4 MessageStatus (0–11)

קוד	שם
0	חדש
1	הצלחה
2	נדחה
3	קרא
4	לא ידוע
5	עיבוד
6	נמסר
7	BLOCKED_BY_USER
8	USER_NOT_FOUND

המצוין משתרע על 0–11. הערכים 9, 10 ו-11 קיימים ב-API אך עדיין לא מתועדים - התייחס אליהם כאל UNKNOWN.

8.5 MediaType (1–10)

1 תמונה, 2 קובץ, 3 אודיו, 4 וידאו, 5 מדבקה, 6 StickerAnimated, 7 StickerVideo, 8 אנימציה, 9 קול, 10 VideoNote

8.6 AuthorMessage — מחבר ב-Chat API (0–4)

0 מפעיל, 1 לקוח, 2 בוט, 3 ViberAccount

המניין משתרע על 0–4; הערך 4 אינו מתועד. התקשרות חוזרת של “הודעה חדשה” משתמשת ב מיפוי הפוך - ראה §6.2.

8.7 ChatMessageType (0–2)

0 טקסט, 1 תמונה, 2 קובץ

8.8 תגובה replyStatus

null הערת משתמש נכנסת, "pending" התשובה שלנו נמצאת בתור, "sent" נמסרה, משלוח "failure" נכשל.

---

שאלות פתוחות

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

#	שאלה	מפרט	סוואגר	איך בודקים
1	כותרת אימות עבור /api/meta/*	X-Authorization-Key	רק Bearer הוצהר	curl -i -H "X-Authorization-Key: <token>" ".../api/meta/posts?perPage=1" — צפו ל200, לא 401
2	שדה מונה בתגובות Meta	totalCount	total	אותה בקשה - קרא את מפתח JSON השורש
3	סוג author.type וקוד סטטוס reply	"meta_user" / "owner", 202 עם גוף	int [0,1], 200 ללא גוף	curl -i .../api/meta/comments?perPage=1 בתוספת תשובת מבחן

הנחיות ביניים:

• מונה - קרא את total ?? totalCount;
• author.type — קבל גם מחרוזת וגם מספר שלם (0 ↔ meta_user, 1 ↔ owner, המיפוי יאושר);
• reply - התייחס לכל 2xx כהצלחה, אין צורך בגוף, קח את הסטטוס הסופי מההתקשרות חזרה source: 13.

---

הערות יישום

• האימות שונה לכל קבוצת נקודות קצה — /api/meta/* משתמש ב-X-Authorization-Key, בצ’אטים וב מפעילים משתמשים ב- Bearer, restapi מקבל גם אחד מהם.
• הדף מאוית בשני אופנים - per_page ב-/api/chat/chats, perPage ב-/api/chat/chats /api/meta/* ו/api/chat/callback-events.
• שדות multipart/form-data הם PascalCase עם סימון נקודות (Media.File, Media.Type).
• שדות אפס מושמטים בהתקשרות חוזרת - מפתח נעדר פירושו null.
• phone הוא בדרך כלל null באינסטגרם. זהה את הלקוח לפי instagramUser.id / metaUserId והחנות לפי instaAccount.id (ערך המסנן entityId).
• Story.Id מ-callback ניתן להעביר ישר אחורה בתור id / postId אל Meta API.
• בדוק את expiresAt של המפעיל JWT לפני השימוש בו בקישור עמוק או בווידג’ט.