Integrazzjoni tal-API Meta & Instagram

Referenza għall-bini ta’ app Instagram fuq il-SMSBAT ChatHub Platform: awtentikazzjoni, Instagram Konversazzjonijiet diretti, kummenti fuq postijiet u Rukkelli, risposti għall-Istorja, webhooks u polling.

---

1. URLs bażi

Għan	URL
Chat API + Meta API	https://chatapi.smsbat.com
Swagger UI / OpenAPI	https://chatapi.smsbat.com/index.html · …/swagger/v1/swagger.json
REST API (organizzazzjonijiet, URLs callback)	https://restapi.smsbat.com
REST API Swagger	https://restapi.smsbat.com/swagger/v1/swagger.json
Panew tal-web tal-operatur	https://chat.smsbat.com

---

2. Awtentikazzjoni

L-iskema ta’ awtorizzazzjoni tiddependi fuq il-grupp tal-endpoint. It-taħlit tagħhom huwa l-aktar kawża komuni ta’ 401.

Grupp	Intestatura
chatapi.smsbat.com/api/meta/* (postijiet, kummenti)	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 · Awtorizzazzjoni Bażika

It-token tal-organizzazzjoni għal X-Authorization-Key jinħareġ fil-panel taħt Profil. JWTs tal-kumpaniji u tal-operaturi ġejjin minn /api/company/get-token u /api/operator/get-token.

2.1 Token tal-kumpanija

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

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

200 OK jirritorna sekwenza ta’ tokens vojta.

2.2 Organizzazzjonijiet

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

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

2.3 Operaturi f’organizzazzjoni

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

Status tal-operatur: 0 Attiv, 1 Inattiv, 2 Imħassar.

2.4 Żid / issinkronizza l-operaturi

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 Operatur 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 jirritorna l-JWT bħala string.

2.6 Ivvalida token tal-operatur

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
}

Meta invalidu: { "isValid": false, "error": "Invalid token" }.

2.7 Inkorpora l-pannell taċ-chat tal-operatur

<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. Deeplinks fil-panel taċ-chat

Sistema esterna (CRM, ERP, websajt) tista’ tiftaħ konversazzjoni speċifika fiha https://chat.smsbat.com/. L-operatur huwa awtorizzat minn JWT mgħoddi bħala parametru ta’ mistoqsija.

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>

Parametru	Deskrizzjoni
chat_raw_id	Chat ID
phone	Numru tat-telefon f’format internazzjonali
from	Identifikatur tal-kont tal-marka / tan-negozju (bm_id)
source	Sors taċ-chat — 7 għal Instagram, ara §8.1
token	Operatur JWT validu u mhux skadut b’aċċess għal chats

JWT invalidu jpoġġi lill-viżitatur fuq l-iskrin tal-login tal-pannell tal-operatur.

---

4. Instagram Konversazzjonijiet diretti

4.1 Elenka ċ-chats

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

Parametri tal-mistoqsija, kollha mhux obbligatorji:

Parametru	Tip	Deskrizzjoni
source	ChatSource	7 jirrestrinġi r-riżultati għal Instagram
entityId	int	ID tal-kont tan-negozju. Applikata biss flimkien ma’ source
instagram_user_id	int	ID tal-utent Instagram fi ChatHub
facebook_user_id	int	ID tal-utent ta’ Facebook fi ChatHub
page / per_page	int	Paġnar, defaults 1 / 20
status	ChatStatus[]	Stat taċ-chat, li jista’ jiġi ripetut
search	string	Tfittxija b’test liberu (isem, telefon, …)
organizationId	int	ID Organizzazzjoni
operatorId	int[]	Iffiltra mill-operaturi assenjati
date	string[]	Żewġ limiti: ?date=…&date=…
isChain	bool	Irritorna ċ-chats bħala ktajjen, li jġorru messaġġi minn chats preċedenti
isUnread, starMark, isOperator, isAIAgent	bool	Filtri addizzjonali
phone, email, contactId, clientId, tagIds, rate, sortedBy	—	Filtri oħra

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

L-oqsma li huma importanti għal app Instagram:

Qasam	Tifsira
instaAccount	Il-kont tan-negozju ta’ Instagram (il-ħanut). id huwa l-valur tal-filtru entityId; name huwa l-isem tal-kont minn Meta
instagramUser	Il-klijent. name huwa l-manku ta’ Instagram, id huwa l-valur tal-filtru instagram_user_id
metaUserId	L-ID b’ambitu tal-klijent fuq in-naħa ta’ Meta (string)
messSource	7 għal Instagram
phone	Normalment null għal Instagram — tużahiex bħala ċavetta

ChatDTO iġorr ukoll 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 u taggedMessages.

4.2 Messaġġi taċ-chat

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

200 OK jirritorna firxa ta’ 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 jiġi popolat meta l-messaġġ ikun relatat ma’ post jew Storja ta’ Instagram — għaddih dritt lura bħala id / postId għall-Meta API. media huwa ChatMediaDTO: { name, format, type, uri, raw, length, isUploaded }.

4.3 Ibgħat messaġġ (JSON)

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

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

Qasam	Tip	Deskrizzjoni
textMessage	string?	Test tal-messaġġ. Jista’ jkun vojt meta media ikun preżenti
author	AuthorMessage?	0 operatur, 1 klijent
isInternal	bool?	true timmarka nota interna li mhix ikkunsinnata lill-klijent
replyToMessageId	int?	ID tal-messaġġ li qed jitwieġeb
appGuid	uuid?	GUID ta’ referenza
media	MediaDTO?	{ name, format, dataBase64, thumbnail, duration, type }

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

GUID ta’ riferiment jista’ wkoll jiġi mgħoddi fil-mogħdija: POST /api/chat/{chatId}/{referralGuid}/message (bl-istess mod …/message/v1, …/message/v2).

4.4 Ibgħat fajl jew vidjo (b’ħafna partijiet, v2)

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

Field field	Tip	Deskrizzjoni
TextMessage	string	Test tal-messaġġ
Author	int	0 operatur, 1 klijent
IsInternal	bool	Nota interna
ReplyToMessageId	int	Messaġġ li qed jitwieġeb għal
AppGuid	uuid	GUID ta’ referenza
Media.File	binary	Il-fajl innifsu
Media.Name	string	Isem tal-fajl
Media.Format	string	Tip MIME (video/mp4, image/png, application/pdf)
Media.Type	MediaType	Ara §8.5
Media.DataBase64	string	Alternattiva għal Media.File
Media.Thumbnail	string	Frame preview tal-vidjo Base64
Media.Duration	double	Tul tal-vidjo f’sekondi

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 Ibdel l-istatus taċ-chat

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

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

200 OK jirrepeti l-oġġett aġġornat.

4.6 Aġġorna l-istatus tal-messaġġi

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

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

4.7 Ħassar chat

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

---

5. Postijiet, Rukkelli u Stejjer

Mogħdija bażi: https://chatapi.smsbat.com/api/meta Awth: X-Authorization-Key: <organization token>

5.1 Elenka postijiet, Rukkelli u Stejjer

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

Parametru	Tip	Meħtieġa	Deskrizzjoni
page	int	le	Paġna, default 1
perPage	int	le	Oġġetti għal kull paġna, default 20
id	int	le	Iffiltra mill-ID tal-post intern
platform	string	le	instagram jew facebook
mediaType	string	le	post, reel jew story. It-tipi kollha meta jitħallew barra

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

Qasam	Deskrizzjoni
id	ID tal-post intern
metaId	Post estern / Rukkell / Story ID fil-Meta
text	Post caption
imageUrl	Proxy media URL immarkat mill-MetaPost.Guid mhux sekwenzjali, jew null
platform	facebook jew instagram
mediaType	post, reel jew story
createdAt	Data tal-ħolqien (data tal-pjattaforma, jew id-data tad-database)
story	Ippreżenta biss għal mediaType: "story"
story.id	ID tal-Istorja Interna; ugwali għal post.id
story.metaId	ID Storja Esterna fil-Meta
story.url	URL prokura stabbli tal-midja Story maħżuna; null jekk il-midja ma setgħetx tiġi ssejvjata

Il-midja tal-posta hija moqdija b’żewġ rotot: GET /api/meta/post/media/{id:int} għal lura kompatibilità u GET /api/meta/post/media/{guid:guid}. Risposti API ġodda u callbacks dejjem iġġenera l-formola GUID.

5.2 Elenka l-kummenti

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

Parametru	Tip	Meħtieġa	Deskrizzjoni
page	int	le	Paġna, default 1
perPage	int	le	Oġġetti għal kull paġna, default 20
postId	int	le	Iffiltra bl-ID tal-posta
parentCommentId	int	le	Kummenti tat-tfal (tweġibiet) ta’ kumment partikolari
platform	string	le	facebook jew 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..."
      }
    }
  ]
}

Qasam	Deskrizzjoni
id	ID tal-kumment intern
metaId	ID esterna fil-Meta. null għal tweġiba pendenti tagħna sakemm tintbagħat
text	Test tal-kumment
createdAt	Data tal-ħolqien
platform	facebook jew instagram
replyStatus	null għal kumment ta’ utent deħlin; "pending" / "sent" / "failure" għat-tweġiba tagħna
author.type	"meta_user" utent estern, "owner" sid tal-paġna
author.name	Isem tal-awtur
author.metaUserId	ID tal-utent b’ambitu fil-Meta; null għal "owner"
post	Il-post, Rukkell jew Storja li jappartjeni għall-kumment
post.mediaType	post, reel jew story
post.story	Referenza għall-istorja { id, metaId, url }, Stejjer biss
mediaUrl	Midja mehmuża mal-kumment, jew null
replyTo	Kumment tal-ġenitur { id, metaId, text }; null fl-ogħla livell

5.3 Tweġiba għal kumment

Kjuw tweġiba għall-kunsinna.

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"

Korp tat-talba: { "text": "Reply text" }

202 Accepted jirritorna l-oġġett tal-kumment — l-istess forma bħal GET /api/meta/comments — bi replyStatus: "pending" u metaId: null. Ir-riżultat tal-kunsinna jasal aktar tard bħala a source: 13 callback (§6.4).

---

6. Webhooks

SMSBAT jibgħat POST talbiet b’application/json lill-URL tiegħek u jistenna HTTP 200 lura.

6.1 Irreġistra URL ta’ callback

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

Qasam	Tip	Deskrizzjoni
url	string	L-endpoint tiegħek
source	SendingSourceCallback	Tip ta’ avveniment, ara §8.2
headerName / headerValue	string	Header ta’ awtorizzazzjoni arbitrarja aħna nehmeż mat-talba (mhux obbligatorju)
channelType	ChatSource	Kanal. 7 għal Instagram. Fakultattiv
channelEntityId	int	Kont tan-negozju speċifiku. Jeħtieġ channelType

Mingħajr channelType l-URL jirċievi avvenimenti minn kull kanal.

Operazzjonijiet li fadal:

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

[
  {
    "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 Messaġġ ġdid u tweġiba għall-Istorja ta’ Instagram (source: 3, 11)

It-tweġiba ta’ utent għal Storja ta’ Instagram tasal bħala messaġġ ordinarju f’dawn it-telefonati lura, bi blokk Story tal-ogħla livell addizzjonali:

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

Qasam	Deskrizzjoni
ChatId / MessageId	Identifikaturi taċ-chat u tal-messaġġ
Author	0 utent, 1 operatur
Username	Isem tal-wiri ta’ Instagram / Facebook jew manku
UserId	ID tal-utent numeriku intern fl-SMSBAT
MetaUserId	ID b’ambitu tas-sieħeb tal-konversazzjoni f’Meta. Fuq messaġġ ta’ operatur ħerġin dan xorta jidentifika l-utent Meta taċ-chat, mhux l-operatur
ShopId	ID interna tal-kont tan-negozju ta’ Instagram/Facebook
ShopName	Isem tal-kont tan-negozju kif riċevut mingħand Meta fil-ħin tal-konnessjoni
MessageText	Test tal-messaġġ
MessageMedia	Media URL meta l-messaġġ huwa media
type_messenger	Sors, ​​7 għal Instagram
operator_name	Isem tal-operatur meta Author = 1
Story	Ippreżenta biss fuq risposta ta’ Storja deħlin
Story.Id	Storja Interna (MetaPost) ID — tista’ tintuża direttament bħala id / postId fil-Meta API
Story.MetaId	ID Storja Esterna fil-Meta
Story.Url	URL prokura stabbli tal-midja Story maħżuna. Assenti meta l-midja ma setgħetx tiġi ssejvjata — il-blokk Story u l-messaġġ għadhom jitwasslu

6.3 Kumment ġdid (source: 12)

Jispara meta utent Meta jikkummenta fuq post fuq Facebook jew fuq Instagram post / Rukkell.

{
  "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 Stat tat-tweġiba għall-kumment (source: 13)

Nirien wara li nippruvaw nagħtu tweġiba, kemm jekk tirnexxi jew tfalli.

{
  "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 Oqsma ta’ callback ta’ kummenti kondiviżi

Iż-żewġ callbacks tal-kummenti jaqsmu forma waħda tal-ġisem u jvarjaw biss b’type.

Qasam	Deskrizzjoni
type	"new_comment" jew "comment_status"
platform	"facebook" jew "instagram"
comment.id	ID tal-kumment intern
comment.metaId	ID esterna fil-Meta; null għal tweġiba pendenti qabel ma tintbagħat
comment.parentCommentId	ID tal-kumment tal-ġenitur. Assenti għal kumment tal-ogħla livell
comment.parentMetaId	ID tal-kumment estern tal-ġenitur. Assenti fl-ogħla livell
comment.parentCommentText	Test tal-kumment tal-ġenituri. Assenti fl-ogħla livell
comment.text	Test tal-kumment
comment.createdAt	Data tal-ħolqien
comment.updatedAt	L-aħħar aġġornament. Assenti jekk il-kumment qatt ma ġie editjat
comment.replyStatus	"pending" / "sent" / "failure". Assenti għal kumment ta’ utent deħlin
comment.author.type	"meta_user" jew "owner"
comment.author.name	Isem tal-awtur
comment.author.metaUserId	ID tal-awtur b’ambitu fil-Meta. Assenti għal "owner"
comment.mediaUrl	Kumment midja. Assenti meta ma jkunx hemm
post.id	ID tal-post intern
post.metaId	Post estern / Rukkell / Story ID fil-Meta
post.text	Post test
post.imageUrl	Ibgħat l-URL tal-immaġni, jew null
post.createdAt	Data ta’ wara l-ħolqien
post.mediaType	F’callbacks ta’ kummenti, post jew reel biss

6.6 Chat ġdid (source: 7)

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

6.7 Bidliet fl-istatus tal-messaġġi u taċ-chat (source: 6 / 5)

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

6.8 Messaġġ editjat jew imħassra (source: 9)

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

6.9 Indikatur tat-tajpjar (source: 8)

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

---

7. Votazzjoni tal-avveniment

Għal ambjenti li ma jistgħux jaċċettaw HTTP deħlin.

7.1 Ġib avvenimenti

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

Parametru	Deskrizzjoni
organizationId	Fakultattiv. Meħuda mit-token meta titħalla barra
page / perPage	Paġnar, defaults 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"
    }
  ]
}

Kull avveniment iġorr event_guid, timestamp, organization_id u callback_type — a string li taqbel mal-valuri source f’§8.2. L-oqsma li jifdal jaqblu mal-korrispondenti webhook fil-§6.

7.2 Irrikonoxxi l-avvenimenti pproċessati

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 }

L-avvenimenti li diġà tneħħew sempliċement ma jgħoddux għal deleted. L-ordnijiet u l-prova mill-ġdid huma tiegħek responsabbiltà tan-naħa.

7.3 Loop rakkomandat

1. Istħarriġ GET /api/chat/callback-events fuq skeda.
2. Ipproċessa l-avvenimenti fis-servizz tiegħek.
3. Ibgħat il-lista pproċessata event_guid lil /callback-events/processed.
4. Irrepeti.

---

8. Referenza tal-enum

8.1 ChatSource — kanal (0–9)

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

8.2 SendingSourceCallback — tip ta’ avveniment ta’ callback (0–13)

Kodiċi	Avveniment
3	Chat — messaġġ chat ġdid, inklużi tweġibiet għall-Istorja
5	L-istatus taċ-chat inbidel
6	L-istatus tal-messaġġ inbidel
7	Chat ġdid maħluqa
8	Indikatur tat-tajpjar
9	Messaġġ aġġornat jew imħassra
11	AnyChatMessage — kwalunkwe messaġġ taċ-chat
12	MetaNewComment — kumment ġdid ta’ Instagram / Facebook
13	MetaCommentStatus — l-istatus tal-kunsinna tat-tweġiba tal-kumment tagħna

L-enum jifrex 0–13; il-valuri li jifdal mhumiex meħtieġa għall-integrazzjonijiet ta ‘Instagram.

8.3 ChatStatus (0–4)

0 Ġdid, 1 Miftuħ, 2 Stennija, 3 OnPause, 4 Magħluq

8.4 MessageStatus (0–11)

Kodiċi	Isem
0	ĠODDA
1	SUĊĊESS
2	MIĊĦUT
3	AQRA
4	MHUX MAGĦRUF
5	PROĊESSAR
6	MOGĦTIJA
7	BLOCKED_BY_USER
8	USER_NOT_FUND

L-enum jifrex 0–11. Il-valuri 9, 10 u 11 jeżistu fl-API iżda għadhom mhumiex dokumentati — ittrattahom bħala UNKNOWN.

8.5 MediaType (1–10)

1 Ritratt, 2 Fajl, 3 Awdjo, 4 Vidjo, 5 Stiker, 6 StikerAnimated, 7 StikerVideo, 8 Animazzjoni, 9 Voice, 10 VideoNote

8.6 AuthorMessage — awtur fl-API taċ-Chat (0–4)

0 Operatur, 1 Klijent, 2 Bot, 3 ViberAccount

L-enum jifrex 0–4; valur 4 mhuwiex dokumentat. Is-callbacks ta’ “messaġġ ġdid” jużaw il- mapping oppost — ara §6.2.

8.7 ChatMessageType (0–2)

0 Test, 1 Ritratt, 2 Fajl

8.8 Kumment replyStatus

null kumment tal-utent deħlin, "pending" it-tweġiba tagħna hija fil-kju, "sent" ikkunsinnat, Il-kunsinna "failure" falliet.

---

Mistoqsijiet miftuħa

Tliet punti fejn l-ispeċifikazzjoni interna u s-Swagger iġġenerat mill-kodiċi ma jaqblux. Wieħed talba b’token reali ssolvihom kollha; sa dakinhar, ikteb lill-klijent b’mod difensiv.

#	Mistoqsija	Speċifikazzjoni	Swagger	Kif tiċċekkja
1	Header ta’ awtenzjoni għal /api/meta/*	X-Authorization-Key	Bearer biss iddikjarat	curl -i -H "X-Authorization-Key: <token>" ".../api/meta/posts?perPage=1" — jistennew 200, mhux 401
2	Counter field fit-tweġibiet Meta	totalCount	total	L-istess talba — aqra ċ-ċavetta JSON ta’ l-għerq
3	author.type tip u reply kodiċi tal-istatus	"meta_user" / "owner", 202 bil-korp	int [0,1], 200 mingħajr korp	curl -i .../api/meta/comments?perPage=1 flimkien ma’ tweġiba tat-test

Gwida interim:

• counter — aqra total ?? totalCount;
• author.type — aċċetta kemm string kif ukoll numru sħiħ (0 ↔ meta_user, 1 ↔ owner, l-immappjar irid jiġi kkonfermat);
• reply — ittratta kwalunkwe 2xx bħala suċċess, ma teħtieġ l-ebda korp, ħu l-istatus finali mill-callback source: 13.

---

Noti ta’ implimentazzjoni

• Awth tvarja għal kull grupp ta’ endpoint — /api/meta/* juża X-Authorization-Key, chats u operaturi jużaw Bearer, restapi jaċċetta jew.
• Paġinazzjoni hija miktuba b’żewġ modi — per_page fuq /api/chat/chats, perPage fuq /api/meta/* u /api/chat/callback-events.
• L-oqsma multipart/form-data huma PascalCase b’notazzjoni bil-punti (Media.File, Media.Type).
• L-oqsma nulli jitħallew barra minn callbacks — ċavetta assenti tfisser null.
• phone huwa normalment null fuq Instagram. Identifika l-klijent minn instagramUser.id / metaUserId u l-ħanut minn instaAccount.id (il-valur tal-filtru entityId).
• Story.Id minn callback jista’ jiġi mgħoddi dritt lura bħala id / postId lill-Meta API.
• Iċċekkja l-operatur JWT expiresAt qabel tużah f’deeplink jew fil-widget.