Meta & Instagram API интеграция

Справка за изграждане на приложение на Instagram на SMSBAT ChatHub Platform: удостоверяване, Директни разговори в Instagram, коментари за публикации и барабани, отговори на истории, уеб кукички и анкети.

---

1. Основни URL адреси

Цел	URL
API за чат + 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	ID на чата
phone	Телефонен номер в международен формат
from	Идентификатор на марка/бизнес акаунт (bm_id)
source	Източник на чат — 7 за Instagram, вижте §8.1
token	Валиден, неизтекъл оператор JWT с достъп до чатове

Невалиден JWT отвежда посетителя на екрана за вход на операторския панел.

---

4. Директни разговори в Instagram

4.1 Списък на чатове

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

Параметри на заявката, всички незадължителни:

Параметър	Тип	Описание
source	ChatSource	7 ограничава резултатите до Instagram
entityId	int	ID на бизнес акаунт. Прилага се само заедно с source
instagram_user_id	int	Потребителски идентификатор на Instagram в ChatHub
facebook_user_id	int	Facebook потребителски идентификатор в ChatHub
page / per_page	int	Страниране, по подразбиране 1 / 20
status	ChatStatus[]	Състояние на чата, повторяемо
search	string	Търсене в свободен текст (име, телефон, …)
organizationId	int	ID на организация
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": []
    }
  ]
}

Полетата, които имат значение за приложението на Instagram:

Поле	Значение
instaAccount	Бизнес акаунтът в Instagram (магазинът). id е стойността на филтъра entityId; name е името на акаунта от Meta
instagramUser	Клиентът. name е манипулаторът на Instagram, id е instagram_user_id стойността на филтъра
metaUserId	ID с обхват на клиента от страната на Meta (низ)
messSource	7 за Instagram
phone	Обикновено null за Instagram — не го използвайте като ключ

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 се попълва, когато съобщението е свързано с публикация в Instagram или история — предайте го обратно като 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?	ID на съобщението, на което се отговаря
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 Изпращане на файл или видео (multipart, 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	не	Филтриране по ID на вътрешен пост
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	ID на вътрешен пост
metaId	Външна публикация / барабан / ИД на история в мета
text	Надпис на публикация
imageUrl	URL адрес на прокси медия, въведен от непоследователния MetaPost.Guid или null
platform	facebook или instagram
mediaType	post, reel или story
createdAt	Дата на създаване (датата на платформата или датата на базата данни)
story	Предлага се само за mediaType: "story"
story.id	ID на вътрешната история; равно на post.id
story.metaId	Външен идентификатор на история в мета
story.url	Стабилен прокси 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	не	Филтриране по ID на публикация
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	ID на вътрешен коментар
metaId	Външен идентификатор в мета. null за чакащ отговор от нас до изпращането му
text	Текст на коментар
createdAt	Дата на създаване
platform	facebook или instagram
replyStatus	null за входящ потребителски коментар; "pending" / "sent" / "failure" за нашия отговор
author.type	"meta_user" външен потребител, "owner" собственик на страница
author.name	Име на автора
author.metaUserId	Идентификатор на потребител с обхват в мета; null за "owner"
post	Публикацията, барабанът или историята, към които принадлежи коментарът
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. Резултатът от доставката пристига по-късно като a source: 13 обратно извикване (§6.4).

---

6. Уеб кукички

SMSBAT изпраща POST заявки с application/json към вашия URL адрес и очаква 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 за Instagram. По избор
channelEntityId	int	Конкретен бизнес акаунт. Изисква channelType

Без channelType URL получава събития от всеки канал.

Оставащи операции:

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 Ново съобщение и отговор на Instagram Story (source: 3, 11)

Отговорът на потребител на Instagram Story пристига като обикновено съобщение в тези обратни повиквания, с допълнителен блок 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	Име или манипулатор на Instagram/Facebook
UserId	Вътрешен цифров потребителски идентификатор в SMSBAT
MetaUserId	ID с обхват на партньора за разговор в Meta. При изходящо операторско съобщение това все още идентифицира мета потребителя на чата, а не оператора
ShopId	Вътрешен идентификатор на бизнес акаунта в Instagram / Facebook
ShopName	Име на бизнес акаунт, както е получено от Meta по време на свързване
MessageText	Текст на съобщението
MessageMedia	URL адрес на медия, когато съобщението е медия
type_messenger	Източник, 7 за Instagram
operator_name	Име на оператора, когато Author = 1
Story	Представяне само при входящ отговор на история
Story.Id	ID на вътрешната история (MetaPost) — използва се директно като id / postId в Meta API
Story.MetaId	Външен идентификатор на история в мета
Story.Url	Стабилен прокси URL адрес на съхранената медия Story. Отсъства, когато медията не може да бъде запазена — блокът Story и съобщението все още се доставят

6.3 Нов коментар (source: 12)

Задейства се, когато Meta потребител коментира публикация във Facebook или публикация в Instagram / Reel.

{
  "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	ID на вътрешен коментар
comment.metaId	Външен идентификатор в мета; null за чакащ отговор, преди да бъде изпратен
comment.parentCommentId	ID на родителския коментар. Отсъства за коментар от най-високо ниво
comment.parentMetaId	ID на външен родителски коментар. Отсъства на най-високо ниво
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	ID на автора с обхват в мета. Отсъства за "owner"
comment.mediaUrl	Коментирайте медиите. Отсъства, когато няма
post.id	ID на вътрешен пост
post.metaId	Външна публикация / барабан / ИД на история в мета
post.text	Публикувай текст
post.imageUrl	Публикувайте URL адрес на изображение или 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 — a низ, съответстващ на стойностите 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. Препратка към списък

8.1 ChatSource — канал (0–9)

Код	Канал
0	Viber
1	ViberBot
2	TelegramBot
3	Whatsapp
4	Джаджа
5	Розетка
6	Facebook
7	Instagram
8	Абитуриентски бал
9	Olx

8.2 SendingSourceCallback — тип събитие за обратно извикване (0–13)

Код	Събитие
3	Chat — ново съобщение в чата, включително отговори на историята
5	Състоянието на чата е променено
6	Състоянието на съобщението е променено
7	Създаден е нов чат
8	Индикатор за въвеждане
9	Съобщението е актуализирано или изтрито
11	AnyChatMessage — всяко съобщение в чата
12	MetaNewComment — нов коментар в Instagram / Facebook
13	MetaCommentStatus — състояние на доставка на нашия отговор на коментар

Изброяването обхваща 0–13; останалите стойности не са необходими за интеграции в Instagram.

8,3 ChatStatus (0–4)

0 Ново, 1 Отворено, 2 Изчакване, 3 На пауза, 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 Анимиран стикер, 7 StickerVideo, 8 Анимация, 9 Глас, 10 VideoNote

8.6 AuthorMessage — автор в API за чат (0–4)

0 Оператор, 1 Клиент, 2 Бот, 3 Viber акаунт

Енумът обхваща 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	Поле за брояч в Мета отговори	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/meta/* и /api/chat/callback-events.
• Полетата multipart/form-data са PascalCase с нотация с точка (Media.File, Media.Type).
• Нулевите полета са пропуснати от обратните извиквания — липсващ ключ означава null.
• phone обикновено е null в Instagram. Идентифицирайте клиента чрез instagramUser.id / metaUserId и магазина от instaAccount.id (стойността на филтъра entityId).
• Story.Id от обратно извикване може да се предаде направо обратно като id / postId към Meta API.
• Проверете expiresAt на оператора JWT, преди да го използвате в дълбока връзка или джаджа.