Integracja API Meta i Instagrama

Dokumentacja dotycząca tworzenia aplikacji Instagram na platformie SMSBAT ChatHub: uwierzytelnianie, Bezpośrednie rozmowy na Instagramie, komentarze do postów i rolek, odpowiedzi na historie, webhooki i ankiety.

---

1. Bazowe adresy URL

Cel	Adres URL
Czat API + Meta API	https://chatapi.smsbat.com
Swagger UI / OpenAPI	https://chatapi.smsbat.com/index.html · …/swagger/v1/swagger.json
REST API (organizacje, adresy URL wywołań zwrotnych)	https://restapi.smsbat.com
REST API Swagger	https://restapi.smsbat.com/swagger/v1/swagger.json
Panel WWW operatora	https://chat.smsbat.com

---

2. Uwierzytelnianie

Schemat uwierzytelniania zależy od grupy punktów końcowych. Pomieszanie ich jest najczęstszą przyczyną 401.

Grupa	Nagłówek
chatapi.smsbat.com/api/meta/* (posty, komentarze)	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 · Podstawowa autoryzacja

Token organizacji dla X-Authorization-Key wydawany jest w panelu w zakładce Profil. JWT firmy i operatora pochodzą z /api/company/get-token i /api/operator/get-token.

2.1 Token firmy

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

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

200 OK zwraca pusty ciąg tokenów.

2.2 Organizacje

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

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

2.3 Operatorzy w organizacji

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" }
  }
]

Statusy operatora: 0 Aktywny, 1 Nieaktywny, 2 Usunięty.

2.4 Dodawanie/synchronizacja operatorów

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 Operator 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 zwraca JWT jako ciąg znaków.

2.6 Zweryfikuj token operatora

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
}

Gdy nieważne: { "isValid": false, "error": "Invalid token" }.

2.7 Osadź panel czatu operatora

<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. Głębokie linki do panelu czatu

W zewnętrznym systemie (CRM, ERP, stronie internetowej) można otworzyć konkretną rozmowę https://chat.smsbat.com/. Operator jest autoryzowany przez token JWT przekazywany jako parametr zapytania.

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>

Parametr	Opis
chat_raw_id	Identyfikator czatu
phone	Numer telefonu w formacie międzynarodowym
from	Identyfikator konta marki/firmy (bm_id)
source	Źródło czatu — 7 dla Instagrama, patrz §8.1
token	Obowiązujący, nieważny operator JWT z dostępem do czatów

Nieprawidłowy JWT powoduje wylądowanie gościa na ekranie logowania panelu operatora.

---

4. Bezpośrednie rozmowy na Instagramie

4.1 Wyświetl listę czatów

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

Parametry zapytania, wszystkie opcjonalne:

Parametr	Wpisz	Opis
source	ChatSource	7 ogranicza wyniki do Instagrama
entityId	int	Identyfikator konta firmowego. Stosowane tylko razem z source
instagram_user_id	int	Identyfikator użytkownika Instagrama w ChatHub
facebook_user_id	int	Identyfikator użytkownika Facebooka w ChatHub
page / per_page	int	Paginacja, domyślnie 1 / 20
status	ChatStatus[]	Stan czatu, powtarzalny
search	string	Wyszukiwanie dowolnego tekstu (imię i nazwisko, telefon, …)
organizationId	int	Identyfikator organizacji
operatorId	int[]	Filtruj według przypisanych operatorów
date	string[]	Dwie granice: ?date=…&date=…
isChain	bool	Zwróć czaty jako łańcuchy, przenosząc wiadomości z poprzednich czatów
isUnread, starMark, isOperator, isAIAgent	bool	Dodatkowe filtry
phone, email, contactId, clientId, tagIds, rate, sortedBy	—	Inne filtry

200 OK zwraca 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": []
    }
  ]
}

Pola istotne dla aplikacji na Instagramie:

Pole	Znaczenie
instaAccount	Konto firmowe na Instagramie (sklep). id to wartość filtra entityId; name to nazwa konta w Meta
instagramUser	Klient. name to uchwyt na Instagramie, id to wartość filtra instagram_user_id
metaUserId	Identyfikator zakresu klienta po stronie Meta (string)
messSource	7 na Instagramie
phone	Zwykle null dla Instagrama — nie używaj go jako klucza

ChatDTO przenosi również 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 i taggedMessages.

4.2 Wiadomości na czacie

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

200 OK zwraca tablicę 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 jest wypełniane, gdy wiadomość dotyczy postu lub historii na Instagramie — przekaż ją prosto z powrotem jako id / postId do Meta API. media to ChatMediaDTO: { name, format, type, uri, raw, length, isUploaded }.

4.3 Wyślij wiadomość (JSON)

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

Ciało — 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
  }
}

Pole	Wpisz	Opis
textMessage	string?	Tekst wiadomości. Może być pusty, gdy obecne jest media
author	AuthorMessage?	0 operator, 1 klient
isInternal	bool?	true oznacza notatkę wewnętrzną, która nie jest dostarczana do klienta
replyToMessageId	int?	Identyfikator wiadomości, na którą odpowiadasz
appGuid	uuid?	Identyfikator GUID skierowania
media	MediaDTO?	{ name, format, dataBase64, thumbnail, duration, type }

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

W ścieżce można także przekazać identyfikator GUID polecenia: POST /api/chat/{chatId}/{referralGuid}/message (podobnie …/message/v1, …/message/v2).

4.4 Wyślij plik lub wideo (wieloczęściowy, v2)

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

Pole formularza	Wpisz	Opis
TextMessage	string	Tekst wiadomości
Author	int	0 operator, 1 klient
IsInternal	bool	Notatka wewnętrzna
ReplyToMessageId	int	Wiadomość, na którą odpowiadasz
AppGuid	uuid	Identyfikator GUID skierowania
Media.File	binary	Sam plik
Media.Name	string	Nazwa pliku
Media.Format	string	Typ MIME (video/mp4, image/png, application/pdf)
Media.Type	MediaType	Zobacz §8.5
Media.DataBase64	string	Alternatywa dla Media.File
Media.Thumbnail	string	Ramka podglądu wideo Base64
Media.Duration	double	Czas trwania filmu w sekundach

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 Zmień status czatu

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

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

200 OK powtarza zaktualizowany obiekt.

4.6 Aktualizuj statusy wiadomości

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

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

4.7 Usuń czat

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

---

5. Posty, krążki i historie

Ścieżka podstawowa: https://chatapi.smsbat.com/api/meta Autoryzacja: X-Authorization-Key: <organization token>

5.1 Listy postów, krążki i historie

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

Parametr	Wpisz	Wymagane	Opis
page	int	nie	Strona, domyślnie 1
perPage	int	nie	Elementy na stronę, domyślnie 20
id	int	nie	Filtruj według wewnętrznego identyfikatora postu
platform	string	nie	instagram lub facebook
mediaType	string	nie	post, reel lub story. Wszystkie typy, jeśli pominięto

# 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"
      }
    }
  ]
}

Pole	Opis
id	Wewnętrzny identyfikator postu
metaId	Post zewnętrzny / Reel / Identyfikator historii w Meta
text	Tytuł wpisu
imageUrl	Adres URL nośnika proxy z kluczem niesekwencyjnym MetaPost.Guid lub null
platform	facebook lub instagram
mediaType	post, reel lub story
createdAt	Data utworzenia (data platformy lub data bazy danych)
story	Obecne tylko dla mediaType: "story"
story.id	Wewnętrzny identyfikator historii; równe post.id
story.metaId	Zewnętrzny identyfikator historii w Meta
story.url	Stabilny adres URL proxy przechowywanych multimediów Story; null jeśli nie udało się zapisać multimediów

Media pocztowe są obsługiwane dwiema drogami: GET /api/meta/post/media/{id:int} dla wstecz kompatybilność i GET /api/meta/post/media/{guid:guid}. Nowe odpowiedzi API i wywołania zwrotne zawsze generuj formularz GUID.

5.2 Lista komentarzy

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

Parametr	Wpisz	Wymagane	Opis
page	int	nie	Strona, domyślnie 1
perPage	int	nie	Elementy na stronę, domyślnie 20
postId	int	nie	Filtruj według identyfikatora postu
parentCommentId	int	nie	Komentarze podrzędne (odpowiedzi) danego komentarza
platform	string	nie	facebook lub 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..."
      }
    }
  ]
}

Pole	Opis
id	Wewnętrzny identyfikator komentarza
metaId	Zewnętrzny identyfikator w Meta. null za naszą oczekującą odpowiedź do czasu jej wysłania
text	Tekst komentarza
createdAt	Data utworzenia
platform	facebook lub instagram
replyStatus	null dla przychodzącego komentarza użytkownika; "pending" / "sent" / "failure" za naszą odpowiedź
author.type	"meta_user" użytkownik zewnętrzny, "owner" właściciel strony
author.name	Nazwisko autora
author.metaUserId	Identyfikator użytkownika o określonym zakresie w Meta; null dla "owner"
post	Post, Reel lub Story, do którego należy komentarz
post.mediaType	post, reel lub story
post.story	Odniesienie do historii { id, metaId, url }, Tylko historie
mediaUrl	Multimedia dołączone do komentarza, lub null
replyTo	Komentarz rodzica { id, metaId, text }; null na najwyższym poziomie

5.3 Odpowiedz na komentarz

Kolejkuje odpowiedź do dostarczenia.

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"

Treść żądania: { "text": "Reply text" }

202 Accepted zwraca obiekt komentarza — taki sam kształt jak GET /api/meta/comments — z replyStatus: "pending" i metaId: null. Wynik dostawy pojawia się później jako a source: 13 oddzwonienie (§6.4).

---

6. Webhooki

SMSBAT wysyła POST żądań z application/json na Twój adres URL i oczekuje HTTP 200 odpowiedzi.

6.1 Zarejestruj adres URL wywołania zwrotnego

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
  }'

Pole	Wpisz	Opis
url	string	Twój punkt końcowy
source	SendingSourceCallback	Typ zdarzenia, patrz §8.2
headerName / headerValue	string	Dowolny nagłówek autoryzacji, który dołączamy do żądania (opcjonalnie)
channelType	ChatSource	Kanał. 7 na Instagramie. Opcjonalne
channelEntityId	int	Konkretne konto firmowe. Wymaga channelType

Bez channelType adres URL odbiera zdarzenia z każdego kanału.

Pozostałe operacje:

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 zwraca:

[
  {
    "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 Nowa wiadomość i odpowiedź na historię na Instagramie (source: 3, 11)

Odpowiedź użytkownika na Historię na Instagramie pojawia się jako zwykła wiadomość w ramach tych wywołań zwrotnych, z dodatkowym blokiem najwyższego poziomu 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"
  }
}

Pole	Opis
ChatId / MessageId	Identyfikatory czatów i wiadomości
Author	0 użytkownik, 1 operator
Username	Nazwa wyświetlana lub uchwyt na Instagramie / Facebooku
UserId	Wewnętrzny numeryczny identyfikator użytkownika w SMSBAT
MetaUserId	Identyfikator zakresu rozmówcy w Meta. W wychodzącej wiadomości operatora nadal identyfikuje to użytkownika Meta czatu, a nie operatora
ShopId	Wewnętrzny identyfikator konta firmowego na Instagramie / Facebooku
ShopName	Nazwa konta firmowego otrzymana od Meta w momencie połączenia
MessageText	Tekst wiadomości
MessageMedia	Adres URL multimediów, gdy wiadomość jest multimedialna
type_messenger	Źródło, 7 dla Instagrama
operator_name	Nazwa operatora, gdy Author = 1
Story	Prezentuj tylko w przychodzącej odpowiedzi na historię
Story.Id	Identyfikator historii wewnętrznej (MetaPost) — można go używać bezpośrednio jako id / postId w Meta API
Story.MetaId	Zewnętrzny identyfikator historii w Meta
Story.Url	Stabilny adres URL proxy przechowywanych multimediów Story. Nieobecny, gdy nie można było zapisać multimediów — blok Story i wiadomość są nadal dostarczane

6.3 Nowy komentarz (source: 12)

Uruchamia się, gdy użytkownik Meta komentuje post na Facebooku lub post na Instagramie/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 Stan odpowiedzi na komentarz (source: 13)

Uruchamia się po próbie dostarczenia odpowiedzi, niezależnie od tego, czy się powiedzie, czy nie.

{
  "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 Pola wywołania zwrotnego komentarzy współdzielonych

Obydwa wywołania zwrotne komentarzy mają jeden kształt i różnią się jedynie type.

Pole	Opis
type	"new_comment" lub "comment_status"
platform	"facebook" lub "instagram"
comment.id	Wewnętrzny identyfikator komentarza
comment.metaId	Zewnętrzny identyfikator w Meta; null dla oczekującej odpowiedzi przed jej wysłaniem
comment.parentCommentId	Identyfikator komentarza nadrzędnego. Nieobecny w związku z komentarzem na najwyższym poziomie
comment.parentMetaId	Zewnętrzny identyfikator komentarza nadrzędnego. Nieobecny na najwyższym szczeblu
comment.parentCommentText	Tekst komentarza rodzica. Nieobecny na najwyższym szczeblu
comment.text	Tekst komentarza
comment.createdAt	Data utworzenia
comment.updatedAt	Ostatnia aktualizacja. Nieobecne, jeśli komentarz nie był nigdy edytowany
comment.replyStatus	"pending" / "sent" / "failure". Nieobecny w związku z przychodzącym komentarzem użytkownika
comment.author.type	"meta_user" lub "owner"
comment.author.name	Nazwisko autora
comment.author.metaUserId	Identyfikator autora o określonym zakresie w Meta. Nieobecny przez "owner"
comment.mediaUrl	Komentuj media. Nieobecny, gdy go nie ma
post.id	Wewnętrzny identyfikator postu
post.metaId	Post zewnętrzny / Reel / Identyfikator historii w Meta
post.text	Tekst wpisu
post.imageUrl	Opublikuj adres URL obrazu lub null
post.createdAt	Data utworzenia wpisu
post.mediaType	W wywołaniach zwrotnych komentarzy tylko post lub reel

6.6 Nowy czat (source: 7)

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

6.7 Zmiany statusu wiadomości i czatu (source: 6 / 5)

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

6.8 Wiadomość edytowana lub usunięta (source: 9)

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

6.9 Wskaźnik pisania (source: 8)

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

---

7. Odpytywanie zdarzeń

Dla środowisk, które nie mogą akceptować przychodzącego protokołu HTTP.

7.1 Pobieranie zdarzeń

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

Parametr	Opis
organizationId	Fakultatywny. Pobrane z tokena w przypadku pominięcia
page / perPage	Paginacja, wartości domyślne 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"
    }
  ]
}

Każde wydarzenie niesie ze sobą event_guid, timestamp, organization_id i callback_type — ciąg pasujący do wartości source w §8.2. Pozostałe pola pasują do odpowiednich webhook w §6.

7.2 Zatwierdź przetworzone zdarzenia

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 }

Wydarzenia już usunięte po prostu nie wliczają się do deleted. Zamawianie i ponowne próby należą do Ciebie odpowiedzialność strony.

7.3 Zalecana pętla

1. Sonda GET /api/chat/callback-events zgodnie z harmonogramem.
2. Przetwórz zdarzenia w swojej usłudze.
3. Wyślij przetworzoną listę event_guid na numer /callback-events/processed.
4. Powtórz.

---

8. Odniesienie do wyliczenia

8.1 ChatSource — kanał (0–9)

Kod	Kanał
0	Vibera
1	ViberBota
2	TelegramBot
3	Whatsapp
4	Widżet
5	Rozetka
6	Facebooka
7	Instagram
8	Studniówka
9	Olx

8.2 SendingSourceCallback — typ zdarzenia wywołania zwrotnego (0–13)

Kod	Wydarzenie
3	Chat — nowa wiadomość na czacie, zawierająca odpowiedzi na historie
5	Status czatu zmieniony
6	Status wiadomości zmieniony
7	Utworzono nowy czat
8	Wskaźnik pisania
9	Wiadomość zaktualizowana lub usunięta
11	AnyChatMessage — dowolna wiadomość na czacie
12	MetaNewComment — nowy komentarz na Instagramie/Facebooku
13	MetaCommentStatus — status dostarczenia odpowiedzi na nasz komentarz

Wyliczenie obejmuje 0–13; pozostałe wartości nie są potrzebne do integracji z Instagramem.

8,3 ChatStatus (0–4)

0 Nowy, 1 Otwarty, 2 Oczekiwanie, 3 Pauza, 4 Zamknięty

8,4 MessageStatus (0–11)

Kod	Imię
0	NOWOŚĆ
1	SUKCES
2	ODRZUCONE
3	CZYTAJ
4	NIEZNANE
5	PRZETWARZANIE
6	DOSTARCZONE
7	BLOCKED_BY_USER
8	USER_NOT_FOUND

Wyliczenie obejmuje 0–11. Wartości 9, 10 i 11 istnieją w API, ale nie zostały jeszcze udokumentowane — traktuj je jako UNKNOWN.

8,5 MediaType (1–10)

1 Zdjęcie, 2 Plik, 3 Audio, 4 Wideo, 5 Naklejka, 6 NaklejkaAnimowana, 7 NaklejkaWideo, 8 Animacja, 9 Głos, 10 WideoNotatka

8.6 AuthorMessage — autor w Chat API (0–4)

0 Operator, 1 Klient, 2 Bot, 3 ViberAccount

Wyliczenie obejmuje 0–4; wartość 4 jest nieudokumentowana. ** Wywołania zwrotne „nowa wiadomość” korzystają z metody mapowanie przeciwne** — patrz §6.2.

8,7 ChatMessageType (0–2)

0 Tekst, 1 Zdjęcie, 2 Plik

8.8 Komentarz replyStatus

null przychodzący komentarz użytkownika, "pending" nasza odpowiedź jest oczekujona w kolejce, "sent" dostarczona, "failure" dostawa nie powiodła się.

---

Pytania otwarte

Trzy punkty, w których wewnętrzna specyfikacja i wygenerowany kod Swagger nie zgadzają się. Jeden żądanie z prawdziwym tokenem rozlicza je wszystkie; do tego czasu pisz do klienta defensywnie.

#	Pytanie	Specyfikacja	Przechwałka	Jak sprawdzić
1	Nagłówek uwierzytelniania dla /api/meta/*	X-Authorization-Key	tylko Bearer zadeklarowano	curl -i -H "X-Authorization-Key: <token>" ".../api/meta/posts?perPage=1" — spodziewaj się 200, a nie 401
2	Pole licznika w metaodpowiedziach	totalCount	total	To samo żądanie — przeczytaj główny klucz JSON
3	author.type typ i reply kod statusu	"meta_user" / "owner", 202 z korpusem	int [0,1], 200 bez korpusu	curl -i .../api/meta/comments?perPage=1 plus odpowiedź testowa

Wytyczne tymczasowe:

• licznik — czytaj total ?? totalCount;
• author.type — akceptuje zarówno ciąg znaków, jak i liczbę całkowitą (0 ↔ meta_user, 1 ↔ owner, mapowanie do potwierdzenia);
• reply — traktuj dowolne 2xx jako sukces, nie wymagaj treści, przyjmij ostateczny status z wywołania zwrotnego source: 13.

---

Uwagi dotyczące wdrożenia

• Uwierzytelnianie różni się w zależności od grupy punktów końcowych — /api/meta/* używa X-Authorization-Key, czatów i operatorzy używają Bearer, restapi akceptuje oba.
• Paginacja jest zapisywana na dwa sposoby — per_page na /api/chat/chats, perPage na /api/meta/* i /api/chat/callback-events.
• Pola multipart/form-data to PascalCase z oznaczeniem kropkowym (Media.File, Media.Type).
• Pola zerowe są pomijane w wywołaniach zwrotnych — brak klucza oznacza null.
• phone to zazwyczaj null na Instagramie. Zidentyfikuj klienta poprzez instagramUser.id / metaUserId i sklep po instaAccount.id (wartość filtra entityId).
• Story.Id z wywołania zwrotnego można bezpośrednio przekazać z powrotem jako id / postId do Meta API.
• Sprawdź operator JWT expiresAt przed użyciem go w deeplinku lub widżecie.