Integrimi i Meta & Instagram API

Referencë për ndërtimin e një aplikacioni Instagram në platformën SMSBAT ChatHub: vërtetimi, Biseda direkte në Instagram, komente në postime dhe rrotullime, përgjigje në histori, grepa në internet dhe sondazhe.

---

1. URL-të bazë

Qëllimi	URL
Chat API + Meta API	https://chatapi.smsbat.com
Swagger UI / OpenAPI	https://chatapi.smsbat.com/index.html · …/swagger/v1/swagger.json
REST API (organizatat, URL-të e kthimit të thirrjes)	https://restapi.smsbat.com
REST API Swagger	https://restapi.smsbat.com/swagger/v1/swagger.json
Paneli ueb i operatorit	https://chat.smsbat.com

---

2. Autentifikimi

Skema e vërtetimit varet nga grupi i pikës fundore. Përzierja e tyre është shkaku më i zakonshëm i 401.

Grupi	Kreu
chatapi.smsbat.com/api/meta/* (postimet, komentet)	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 · Auth bazë

Shenja e organizatës për X-Authorization-Key lëshohet në panel nën Profili. Kompania dhe operatori JWT vijnë nga /api/company/get-token dhe /api/operator/get-token.

2.1 Shenja e kompanisë

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

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

200 OK kthen një varg token të zhveshur.

2.2 Organizatat

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

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

2.3 Operatorët në një organizatë

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

Statuset e operatorit: 0 aktiv, 1 joaktiv, 2 i fshirë.

2.4 Shtoni / sinkronizoni operatorët

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 Operatori 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 kthen JWT si varg.

2.6 Vërtetoni një shenjë operatori

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
}

Kur është i pavlefshëm: { "isValid": false, "error": "Invalid token" }.

2.7 Fut panelin e bisedës së operatorit

<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. Lidhje të thella në panelin e bisedës

Një sistem i jashtëm (CRM, ERP, faqe interneti) mund të hapë një bisedë specifike https://chat.smsbat.com/. Operatori është i autorizuar nga një JWT e kaluar si një parametër pyetës.

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>

Parametri	Përshkrimi
chat_raw_id	ID e bisedës
phone	Numri i telefonit në format ndërkombëtar
from	Identifikuesi i llogarisë së markës / biznesit (bm_id)
source	Burimi i bisedës — 7 për Instagram, shikoni §8.1
token	Operatori i vlefshëm, i paskaduar JWT me akses në biseda

Një JWT e pavlefshme e vendos vizitorin në ekranin e identifikimit të panelit të operatorit.

---

4. Biseda direkte në Instagram

4.1 Lista e bisedave

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

Parametrat e pyetjes, të gjitha opsionale:

Parametri	Lloji	Përshkrimi
source	ChatSource	7 kufizon rezultatet në Instagram
entityId	int	ID-ja e llogarisë së biznesit. Aplikohet vetëm së bashku me source
instagram_user_id	int	ID e përdoruesit të Instagramit në ChatHub
facebook_user_id	int	ID-ja e përdoruesit të Facebook në ChatHub
page / per_page	int	Pagimi, parazgjedhjet 1 / 20
status	ChatStatus[]	Statusi i bisedës, i përsëritshëm
search	string	Kërkimi në tekst të lirë (emri, telefoni, …)
organizationId	int	ID organizate
operatorId	int[]	Filtro sipas operatorëve të caktuar
date	string[]	Dy kufij: ?date=…&date=…
isChain	bool	Kthejini bisedat si zinxhirë, duke mbajtur mesazhe nga bisedat e mëparshme
isUnread, starMark, isOperator, isAIAgent	bool	Filtra shtesë
phone, email, contactId, clientId, tagIds, rate, sortedBy	—	Filtra të tjerë

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

Fushat që kanë rëndësi për një aplikacion Instagram:

Fusha	Kuptimi
instaAccount	**Llogaria e biznesit në Instagram ** (dyqan). id është vlera e filtrit entityId; name është emri i llogarisë nga Meta
instagramUser	Klienti. name është doreza e Instagramit, id është vlera e filtrit instagram_user_id
metaUserId	ID-ja e klientit me shtrirje në anën e Metës (varg)
messSource	7 për Instagram
phone	Zakonisht null për Instagram — mos e përdorni si çelës

ChatDTO mbart gjithashtu 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 dhe taggedMessages.

4.2 Mesazhet e bisedës

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

200 OK kthen një grup prej 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 plotësohet kur mesazhi lidhet me një postim ose Story në Instagram — kalojeni drejt mbrapa si id / postId në Meta API. media është një ChatMediaDTO: { name, format, type, uri, raw, length, isUploaded }.

4.3 Dërgo një mesazh (JSON)

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

Trupi — 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
  }
}

Fusha	Lloji	Përshkrimi
textMessage	string?	Teksti i mesazhit. Mund të jetë bosh kur media është i pranishëm
author	AuthorMessage?	Operatori 0, klienti 1
isInternal	bool?	true shënon një shënim të brendshëm që nuk i dorëzohet klientit
replyToMessageId	int?	ID e mesazhit që i është përgjigjur
appGuid	uuid?	GUID Referimi
media	MediaDTO?	{ name, format, dataBase64, thumbnail, duration, type }

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

Një GUID referimi mund të kalohet gjithashtu në rrugën: POST /api/chat/{chatId}/{referralGuid}/message (po kështu …/message/v1, …/message/v2).

4.4 Dërgo një skedar ose video (shumë pjesësh, v2)

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

Fusha e formularit	Lloji	Përshkrimi
TextMessage	string	Teksti i mesazhit
Author	int	Operatori 0, klienti 1
IsInternal	bool	Shënim i brendshëm
ReplyToMessageId	int	Mesazhi po i përgjigjet
AppGuid	uuid	GUID-i i referimit
Media.File	binary	Vetë skedari
Media.Name	string	Emri i skedarit
Media.Format	string	Lloji MIME (video/mp4, image/png, application/pdf)
Media.Type	MediaType	Shih §8.5
Media.DataBase64	string	Alternativë për Media.File
Media.Thumbnail	string	Korniza e shikimit të videos Base64
Media.Duration	double	Kohëzgjatja e videos në sekonda

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 Ndrysho statusin e bisedës

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

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

200 OK i bën jehonë objektit të përditësuar.

4.6 Përditësoni statuset e mesazheve

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

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

4.7 Fshi një bisedë

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

---

5. Postimet, rrotullat dhe tregimet

Rruga bazë: https://chatapi.smsbat.com/api/meta E vërteta: X-Authorization-Key: <organization token>

5.1 Listoni postimet, rrotullat dhe tregimet

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

Parametri	Lloji	Kërkohet	Përshkrimi
page	int	jo	Faqja, e paracaktuar 1
perPage	int	jo	Artikujt për faqe, parazgjedhja 20
id	int	jo	Filtro sipas ID-së së postës së brendshme
platform	string	jo	instagram ose facebook
mediaType	string	jo	post, reel ose story. Të gjitha llojet kur hiqen

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

Fusha	Përshkrimi
id	ID e postës së brendshme
metaId	Postimi i jashtëm / Bobina / ID e tregimit në Meta
text	Titulli i postimit
imageUrl	URL-ja e medias së përfaqësuesit e kyçur nga MetaPost.Guid jo sekuenciale, ose null
platform	facebook ose instagram
mediaType	post, reel ose story
createdAt	Data e krijimit (data e platformës, ose data e bazës së të dhënave)
story	Prezantoni vetëm për mediaType: "story"
story.id	ID-ja e historisë së brendshme; e barabartë me post.id
story.metaId	ID-ja e historisë së jashtme në Meta
story.url	URL e qëndrueshme e përfaqësuesit të medias së ruajtur të Story; null nëse media nuk mund të ruhej

Media postare shërbehet nga dy rrugë: GET /api/meta/post/media/{id:int} për prapa pajtueshmërinë dhe GET /api/meta/post/media/{guid:guid}. Përgjigjet dhe kthimet e reja të API-së gjeneroni gjithmonë formularin GUID.

5.2 Listoni komentet

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

Parametri	Lloji	Kërkohet	Përshkrimi
page	int	jo	Faqja, e paracaktuar 1
perPage	int	jo	Artikujt për faqe, parazgjedhja 20
postId	int	jo	Filtro sipas ID-së së postës
parentCommentId	int	jo	Komentet (përgjigjet) e fëmijëve të një komenti të dhënë
platform	string	jo	facebook ose 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..."
      }
    }
  ]
}

Fusha	Përshkrimi
id	ID e komentit të brendshëm
metaId	ID e jashtme në Meta. null për një përgjigje tonën në pritje derisa të dërgohet
text	Teksti i komentit
createdAt	Data e krijimit
platform	facebook ose instagram
replyStatus	null për një koment të përdoruesit hyrës; "pending" / "sent" / "failure" për përgjigjen tonë
author.type	"meta_user" përdorues i jashtëm, "owner" pronar i faqes
author.name	Emri i autorit
author.metaUserId	ID-ja e përdoruesit me shtrirje në Meta; null për "owner"
post	Postimi, rrotullimi ose Historia komenti i përket
post.mediaType	post, reel ose story
post.story	Referenca e historisë { id, metaId, url }, Vetëm histori
mediaUrl	Media bashkangjitur komentit, ose null
replyTo	Komenti i prindit { id, metaId, text }; null në nivel të lartë

5.3 Përgjigjuni një komenti

Radhë një përgjigje për dorëzim.

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"

Trupi i kërkesës: { "text": "Reply text" }

202 Accepted kthen objektin e komentit — të njëjtën formë si GET /api/meta/comments — me replyStatus: "pending" dhe metaId: null. Rezultati i dorëzimit arrin më vonë si a source: 13 kthim thirrje (§6.4).

---

6. Uebhooks

SMSBAT dërgon POST kërkesa me application/json në URL-në tuaj dhe pret HTTP 200 të kthehet.

6.1 Regjistroni një URL të kthimit të thirrjes

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

Fusha	Lloji	Përshkrimi
url	string	Pika juaj përfundimtare
source	SendingSourceCallback	Lloji i ngjarjes, shih §8.2
headerName / headerValue	string	Titulli i autorizimit arbitrar i bashkangjitim kërkesës (opsionale)
channelType	ChatSource	Kanali. 7 për Instagram. Opsionale
channelEntityId	int	Një llogari specifike biznesi. Kërkon channelType

Pa channelType URL-ja merr ngjarje nga çdo kanal.

Operacionet e mbetura:

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

[
  {
    "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 Mesazhi i ri dhe përgjigja e Instagram Story (source: 3, 11)

Përgjigjja e një përdoruesi për një Instagram Story mbërrin si një mesazh i zakonshëm në këto kthime telefonatash, me një bllok shtesë të nivelit të lartë 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"
  }
}

Fusha	Përshkrimi
ChatId / MessageId	Identifikuesit e bisedës dhe mesazheve
Author	0 përdorues, 1 operator
Username	Emri ose doreza e shfaqur në Instagram / Facebook
UserId	ID-ja numerike e brendshme e përdoruesit në SMSBAT
MetaUserId	ID me shtrirje të partnerit të bisedës në Meta. Në një mesazh operatori dalës ky ende identifikon përdoruesin Meta të bisedës, jo operatorin
ShopId	ID e brendshme e llogarisë së biznesit në Instagram / Facebook
ShopName	Emri i llogarisë së biznesit siç është marrë nga Meta në kohën e lidhjes
MessageText	Teksti i mesazhit
MessageMedia	URL e medias kur mesazhi është media
type_messenger	Burimi, 7 për Instagram
operator_name	Emri i operatorit kur Author = 1
Story	Paraqisni vetëm në një përgjigje hyrëse të Story
Story.Id	ID-ja e historisë së brendshme (MetaPost) — përdoret drejtpërdrejt si id / postId në Meta API
Story.MetaId	ID-ja e historisë së jashtme në Meta
Story.Url	URL e qëndrueshme e përfaqësuesit të medias së ruajtur të Story. Mungon kur media nuk mund të ruhej — blloku Story dhe mesazhi janë ende të dorëzuar

6.3 Koment i ri (source: 12)

Ndizet kur një përdorues i Meta komenton një postim në Facebook ose një postim në 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 Statusi i përgjigjes së komentit (source: 13)

Ndizet pasi ne përpiqemi të japim një përgjigje, pavarësisht nëse ka sukses ose dështon.

{
  "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 Fushat e kthimit të komenteve të përbashkëta

Të dy kthimet e komenteve ndajnë një formë trupi dhe ndryshojnë vetëm nga type.

Fusha	Përshkrimi
type	"new_comment" ose "comment_status"
platform	"facebook" ose "instagram"
comment.id	ID e komentit të brendshëm
comment.metaId	ID e jashtme në Meta; null për një përgjigje në pritje përpara se të dërgohet
comment.parentCommentId	ID-ja e komentit të prindit. Mungon për një koment të nivelit të lartë
comment.parentMetaId	ID-ja e komentit të jashtëm të prindit. Mungon në nivelin më të lartë
comment.parentCommentText	Teksti i komentit të prindërve. Mungon në nivelin më të lartë
comment.text	Teksti i komentit
comment.createdAt	Data e krijimit
comment.updatedAt	Përditësimi i fundit. Mungon nëse komenti nuk është redaktuar kurrë
comment.replyStatus	"pending" / "sent" / "failure". Mungon për një koment të përdoruesit hyrës
comment.author.type	"meta_user" ose "owner"
comment.author.name	Emri i autorit
comment.author.metaUserId	ID e autorit me shtrirje në Meta. Mungon për "owner"
comment.mediaUrl	Koment media. Mungon kur nuk ka asnjë
post.id	ID e postës së brendshme
post.metaId	Postimi i jashtëm / Bobina / ID e tregimit në Meta
post.text	Teksti i postimit
post.imageUrl	Postoni URL-në e imazhit, ose null
post.createdAt	Data e postimit të krijimit
post.mediaType	Në kthimet e komenteve, vetëm post ose reel

6.6 Bisedë e re (source: 7)

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

6.7 Ndryshimet e statusit të mesazheve dhe bisedës (source: 6 / 5)

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

6.8 Mesazhi u modifikua ose u fshi (source: 9)

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

6.9 Treguesi i shkrimit (source: 8)

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

---

7. Sondazhi i ngjarjes

Për mjediset që nuk mund të pranojnë HTTP hyrëse.

7.1 Merr ngjarje

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

Parametri	Përshkrimi
organizationId	Fakultative. Marrë nga shenja kur hiqet
page / perPage	Pagimi, parazgjedhjet 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"
    }
  ]
}

Çdo ngjarje mbart event_guid, timestamp, organization_id dhe callback_type — një varg që përputhet me vlerat source në §8.2. Fushat e mbetura përputhen me ato përkatëse uebhook në §6.

7.2 Pranoni ngjarjet e përpunuara

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 }

Ngjarjet e hequra tashmë thjesht nuk llogariten në deleted. Porositja dhe riprovimet janë tuajat përgjegjësi e palës.

7.3 Cikli i rekomanduar

1. Anketa GET /api/chat/callback-events në një orar.
2. Përpunoni ngjarjet në shërbimin tuaj.
3. Dërgo listën e përpunuar event_guid në /callback-events/processed.
4. Përsëriteni.

---

8. Referenca e numrit

8.1 ChatSource — kanal (0–9)

Kodi	Kanali
0	Viber
1	ViberBot
2	TelegramBot
3	Whatsapp
4	Widget
5	Rozetka
6	Facebook
7	Instagram
8	Prom
9	Olx

8.2 SendingSourceCallback — lloji i ngjarjes së kthimit të thirrjes (0–13)

Kodi	Ngjarja
3	Chat — mesazh i ri bisede, duke përfshirë përgjigjet e Story
5	Statusi i bisedës ndryshoi
6	Statusi i mesazhit ndryshoi
7	U krijua një bisedë e re
8	Treguesi i shtypjes
9	Mesazhi u përditësua ose u fshi
11	AnyChatMessage — çdo mesazh bisede
12	MetaNewComment — koment i ri në Instagram / Facebook
13	MetaCommentStatus — statusi i dorëzimit të përgjigjes së komentit tonë

Numri përfshin 0–13; vlerat e mbetura nuk nevojiten për integrimet në Instagram.

8.3 ChatStatus (0–4)

0 E re, 1 Hapur, 2 Në pritje, 3 Në pauzë, 4 Mbyllur

8,4 MessageStatus (0–11)

Kodi	Emri
0	E RE
1	SUKSES
2	REFUZOHET
3	LEXO
4	E PANJOHUR
5	PËRPUNIMI
6	DORËZUAR
7	BLOCKED_BY_PERDORUES
8	PËRDORIMI_NOT_FOUND

Numri përfshin 0–11. Vlerat 9, 10 dhe 11 ekzistojnë në API, por nuk janë ende të dokumentuara — trajtojini ato si UNKNOWN.

8,5 MediaType (1–10)

1 Foto, 2 Skedar, 3 Audio, 4 Video, 5 Ngjitës, 6 StickerAnimated, 7 StickerVideo, 8 Animacion, 9 Zëri, 10 VideoNote

8.6 AuthorMessage — autor në Chat API (0–4)

0 Operator, 1 Klient, 2 Bot, 3 ViberAccount

Numri përfshin 0–4; vlera 4 është e padokumentuar. Thirrjet e “mesazhit të ri” përdorin hartëzimi i kundërt — shih §6.2.

8,7 ChatMessageType (0–2)

0 Tekst, 1 Foto, 2 Skedar

8.8 Koment replyStatus

null komenti i përdoruesit hyrës, "pending" përgjigja jonë është në radhë, "sent" është dorëzuar, Dorëzimi "failure" dështoi.

---

Pyetje të hapura

Tre pika ku specifikimi i brendshëm dhe kodi i gjeneruar nga Swagger nuk pajtohen. Një kërkesa me një shenjë të vërtetë i zgjidh të gjitha; deri atëherë, shkruani klientin në mënyrë mbrojtëse.

#	Pyetje	Specifikimi	Kërcim	Si të kontrolloni
1	Kreu i vërtetimit për /api/meta/*	X-Authorization-Key	vetëm Bearer deklaruar	curl -i -H "X-Authorization-Key: <token>" ".../api/meta/posts?perPage=1" — prisni 200, jo 401
2	Fusha e numërimit në përgjigjet Meta	totalCount	total	E njëjta kërkesë — lexoni çelësin rrënjë JSON
3	Lloji author.type dhe kodi i statusit reply	"meta_user" / "owner", 202 me trup	int [0,1], 200 pa trup	curl -i .../api/meta/comments?perPage=1 plus një përgjigje provë

Udhëzime të përkohshme:

• numërues — lexo total ?? totalCount;
• author.type — pranoni një varg dhe një numër të plotë (0 ↔ meta_user, 1 ↔ owner, harta për t’u konfirmuar);
• reply — trajto çdo 2xx si sukses, nuk kërkon asnjë trup, merr statusin përfundimtar nga kthimi i thirrjes source: 13.

---

Shënime të zbatimit

• Auth ndryshon sipas grupit të pikës fundore — /api/meta/* përdor X-Authorization-Key, biseda dhe operatorët përdorin Bearer, restapi pranon ose.
• Falifikimi shkruhet në dy mënyra — per_page në /api/chat/chats, perPage më /api/meta/* dhe /api/chat/callback-events.
• Fushat multipart/form-data janë PascalCase me shënim me pikë (Media.File, Media.Type).
• **Fushat nule janë hequr nga kthimet e thirrjeve ** - një çelës që mungon do të thotë null.
• phone është zakonisht null në Instagram. Identifikoni klientin me instagramUser.id / metaUserId dhe dyqani me instaAccount.id (vlera e filtrit entityId).
• Story.Id nga një kthim i telefonatës mund të kalohet drejtpërsëdrejti si id / postId te Meta API.
• Kontrolloni expiresAt të operatorit JWT përpara se ta përdorni në një lidhje të thellë ose në miniaplikacion.