Help Center Integrácia rozhrania Meta & Instagram API

Integrácia rozhrania Meta & Instagram API

Referencia na vytvorenie aplikácie Instagram na platforme SMSBAT ChatHub: overenie, Instagram Direct konverzácie, komentáre k príspevkom a kotúčom, odpovede na príbehy, webhooky a prieskumy.

Zdroje

Táto stránka spája internú špecifikáciu Meta Comments API so živým OpenAPI definície na https://chatapi.smsbat.com/swagger/v1/swagger.json a https://restapi.smsbat.com/swagger/v1/swagger.json. Tam, kde sa dvaja nezhodnú, rozdiel je uvedený v texte a uvedený v časti Otvorené otázky.

1. Základné adresy URL

Účel	URL
Chat API + Meta API	`https://chatapi.smsbat.com`
Používateľské rozhranie Swagger / OpenAPI	`https://chatapi.smsbat.com/index.html` · `…/swagger/v1/swagger.json`
REST API (organizácie, adresy URL spätného volania)	`https://restapi.smsbat.com`
REST API Swagger	`https://restapi.smsbat.com/swagger/v1/swagger.json`
Webový panel operátora	`https://chat.smsbat.com`

2. Autentifikácia

Schéma overenia závisí od skupiny koncových bodov. Ich zmiešanie je najčastejšou príčinou 401.

Skupina	Hlavička
`chatapi.smsbat.com/api/meta/*` (príspevky, komentáre)	`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` · Základné overenie

Token organizácie pre X-Authorization-Key je vydaný na paneli pod Profil. JWT spoločnosti a operátora pochádzajú z /api/company/get-token a /api/operator/get-token.

Rozpor

Dokument chatapi OpenAPI deklaruje jedinú bezpečnostnú schému — Bearer — a aplikuje ju globálne. X-Authorization-Key tam nie je vôbec deklarované, hoci interná Meta Komentáre API špecifikácia pomenúva /api/meta/*. S najväčšou pravdepodobnosťou to rieši middleware, ktorý sa neodráža v Swagger. Pred odoslaním empiricky potvrďte.

2.1 Token spoločnosti

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

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

200 OK vráti holý reťazec tokenov.

2.2 Organizácie

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

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

2.3 Operátori v organizácii

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

Stavy operátora: 0 Aktívny, 1 Neaktívny, 2 Vymazané.

2.4 Pridávanie/synchronizácia operátorov

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 Operátor 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 vráti JWT ako reťazec.

2.6 Overenie tokenu operátora

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
}

Keď je neplatný: { "isValid": false, "error": "Invalid token" }.

2.7 Vložiť panel chatu operátora

<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. Priame odkazy na panel rozhovoru

Externý systém (CRM, ERP, webová stránka) môže otvoriť konkrétnu konverzáciu https://chat.smsbat.com/. Operátor je autorizovaný JWT odovzdaným ako parameter dopytu.

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>

Parameter	Popis
`chat_raw_id`	ID chatu
`phone`	Telefónne číslo v medzinárodnom formáte
`from`	Značka / identifikátor obchodného účtu (`bm_id`)
`source`	Zdroj rozhovoru — `7` pre Instagram, pozri § 8.1
`token`	Platný operátor JWT bez ukončenia platnosti s prístupom k chatom

Neplatný JWT privedie návštevníka na prihlasovaciu obrazovku ovládacieho panela.

4. Instagram Priame konverzácie

4.1 Zoznam rozhovorov

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

Note

Stránkovanie tu je per_page (prípad hada). Pod /api/meta/* a hlasovanie koncový bod je perPage (camelCase). Toto nie je preklep – API používa oboje.

Parametre dopytu, všetky voliteľné:

Parameter	Typ	Popis
`source`	`ChatSource`	`7` obmedzuje výsledky na Instagram
`entityId`	`int`	ID firemného účtu. Uplatňuje sa len spolu s `source`
`instagram_user_id`	`int`	ID používateľa Instagramu v ChatHub
`facebook_user_id`	`int`	ID používateľa Facebooku v ChatHub
`page` / `per_page`	`int`	Stránkovanie, predvolené `1` / `20`
`status`	`ChatStatus[]`	Stav chatu, opakovateľný
`search`	`string`	Vyhľadávanie ľubovoľným textom (meno, telefón, …)
`organizationId`	`int`	ID organizácie
`operatorId`	`int[]`	Filtrovať podľa priradených operátorov
`date`	`string[]`	Dve hranice: `?date=…&date=…`
`isChain`	`bool`	Vrátiť chaty ako reťazce, nesúce správy z predchádzajúcich chatov
`isUnread`, `starMark`, `isOperator`, `isAIAgent`	`bool`	Prídavné filtre
`phone`, `email`, `contactId`, `clientId`, `tagIds`, `rate`, `sortedBy`	—	Ostatné filtre

200 OK vráti 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": []
    }
  ]
}

Polia, na ktorých záleží pre aplikáciu Instagram:

Pole	Význam
`instaAccount`	Instagramový podnikateľský účet (obchod). `id` je hodnota filtra `entityId`; `name` je názov účtu z Meta
`instagramUser`	Zákazník. `name` je rukoväť Instagramu, `id` je hodnota filtra `instagram_user_id`
`metaUserId`	Identifikátor zákazníka v rozsahu na strane Meta (reťazec)
`messSource`	`7` pre Instagram
`phone`	Zvyčajne `null` pre Instagram — nepoužívajte ho ako kľúč

ChatDTO nesie aj 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 a taggedMessages.

4.2 Chatové správy

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

200 OK vráti pole 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 sa vyplní, keď sa správa týka príspevku na Instagrame alebo príbehu – pošlite to rovno späť ako id / postId do Meta API. media je ChatMediaDTO: { name, format, type, uri, raw, length, isUploaded }.

4.3 Odoslať správu (JSON)

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

Telo — 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	Typ	Popis
`textMessage`	`string?`	Text správy. Môže byť prázdny, ak je prítomný `media`
`author`	`AuthorMessage?`	`0` operátor, `1` klient
`isInternal`	`bool?`	`true` označuje internú poznámku, ktorá nie je doručená zákazníkovi
`replyToMessageId`	`int?`	ID správy, na ktorú sa odpovedá
`appGuid`	`uuid?`	GUID odporúčania
`media`	`MediaDTO?`	`{ name, format, dataBase64, thumbnail, duration, type }`

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

Referenčný GUID môže byť odovzdaný aj v ceste: POST /api/chat/{chatId}/{referralGuid}/message (rovnako …/message/v1, …/message/v2).

4.4 Odoslanie súboru alebo videa (viacdiel, v2)

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

Názvy polí formulára sú PascalCase s bodkovým zápisom

textMessage a media.file sú ticho ignorované. Použite nižšie uvedené presné názvy.

Pole formulára	Typ	Popis
`TextMessage`	`string`	Text správy
`Author`	`int`	`0` operátor, `1` klient
`IsInternal`	`bool`	Interná poznámka
`ReplyToMessageId`	`int`	Na správu sa odpovedá
`AppGuid`	`uuid`	GUID odporúčania
`Media.File`	`binary`	Samotný súbor
`Media.Name`	`string`	Názov súboru
`Media.Format`	`string`	Typ MIME (`video/mp4`, `image/png`, `application/pdf`)
`Media.Type`	`MediaType`	Pozri § 8.5
`Media.DataBase64`	`string`	Alternatíva k `Media.File`
`Media.Thumbnail`	`string`	Rámček náhľadu videa Base64
`Media.Duration`	`double`	Trvanie videa v sekundách

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 Zmena stavu chatu

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

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

200 OK opakuje aktualizovaný objekt.

4.6 Aktualizácia stavu správ

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

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

4.7 Odstránenie chatu

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

5. Príspevky, kotúče a príbehy

Základná dráha: https://chatapi.smsbat.com/api/meta Auth: X-Authorization-Key: <organization token>

5.1 Zoznam príspevkov, kotúčov a príbehov

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

Parameter	Typ	povinné	Popis
`page`	`int`	nie	Predvolená stránka `1`
`perPage`	`int`	nie	Počet položiek na stránku, predvolená hodnota `20`
`id`	`int`	nie	Filtrovať podľa interného ID príspevku
`platform`	`string`	nie	`instagram` alebo `facebook`
`mediaType`	`string`	nie	`post`, `reel` alebo `story`. Všetky typy pri vynechaní

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

Nezrovnalosť — názov poľa počítadla

Schéma Swagger MetaCommentPostListItemDtoPaginationDTO definuje total. The interné špecifikačné dokumenty totalCount. Swagger je generovaný z kódu, takže total je pravdepodobnejšia pravda. Analyzujte total ?? totalCount, kým sa to nevyrieši.

Pole	Popis
`id`	ID interného príspevku
`metaId`	Externý príspevok / cievka / ID príbehu v Meta
`text`	Titulok príspevku
`imageUrl`	Proxy mediálna URL zadaná nesekvenčným `MetaPost.Guid` alebo `null`
`platform`	`facebook` alebo `instagram`
`mediaType`	`post`, `reel` alebo `story`
`createdAt`	Dátum vytvorenia (dátum platformy alebo dátum databázy)
`story`	Darček len za `mediaType: "story"`
`story.id`	Interné ID príbehu; rovná sa `post.id`
`story.metaId`	Externé ID príbehu v Meta
`story.url`	Stabilná proxy adresa URL uloženého média Story; `null`, ak sa médiá nepodarilo uložiť

Poštové médiá sú podávané dvomi cestami: GET /api/meta/post/media/{id:int} pre spätný chod kompatibilita a GET /api/meta/post/media/{guid:guid}. Nové odpovede API a spätné volania vždy vygenerujte formulár GUID.

5.2 Zoznam komentárov

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

Parameter	Typ	povinné	Popis
`page`	`int`	nie	Predvolená stránka `1`
`perPage`	`int`	nie	Počet položiek na stránku, predvolená hodnota `20`
`postId`	`int`	nie	Filtrovať podľa ID príspevku
`parentCommentId`	`int`	nie	Detské komentáre (odpovede) na daný komentár
`platform`	`string`	nie	`facebook` alebo `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	Popis
`id`	Interné ID komentára
`metaId`	Externé ID v Meta. `null` za našu čakajúcu odpoveď až do jej odoslania
`text`	Text komentára
`createdAt`	Dátum vytvorenia
`platform`	`facebook` alebo `instagram`
`replyStatus`	`null` pre prichádzajúci komentár používateľa; `"pending"` / `"sent"` / `"failure"` za našu odpoveď
`author.type`	`"meta_user"` externý používateľ, `"owner"` vlastník stránky
`author.name`	Meno autora
`author.metaUserId`	ID používateľa s rozsahom v Meta; `null` za `"owner"`
`post`	Príspevok, kotúč alebo príbeh, ku ktorému komentár patrí
`post.mediaType`	`post`, `reel` alebo `story`
`post.story`	Odkaz na príbeh `{ id, metaId, url }`, iba príbehy
`mediaUrl`	Médiá pripojené ku komentáru alebo `null`
`replyTo`	Komentár rodiča `{ id, metaId, text }`; `null` na najvyššej úrovni

Nezhoda — typ `author.type`

Interná špecifikácia dokumentuje reťazce "meta_user" / "owner". Swagger typy MetaCommentAuthorType ako celé číslo s enum [0, 1]. A JsonStringEnumConverter by vysvetľovalo medzeru, ale to sa nepotvrdilo oproti skutočnej odpovedi. Napíšte a syntaktický analyzátor, ktorý akceptuje oboje.

5.3 Odpovedzte na komentár

Radí odpoveď na doručenie.

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"

Telo žiadosti: { "text": "Reply text" }

202 Accepted vráti objekt komentára — rovnaký tvar ako GET /api/meta/comments — s replyStatus: "pending" a metaId: null. Výsledok doručenia príde neskôr ako a source: 13 spätné volanie (§6.4).

Nezhoda — kód odpovede

Swagger vyhlási 200 bez tela; interná špecifikácia deklaruje 202 Accepted s komentárom ako telom. Ovládač s najväčšou pravdepodobnosťou nemá ProducesResponseType atribút, takže Swagger zostane na predvolenom nastavení. Prijmite akékoľvek 2xx a nespoliehajte sa na telo.

6. Webhooky

SMSBAT posiela POST požiadaviek s application/json na vašu URL a očakáva HTTP 200 späť.

Neplatné polia sú úplne vynechané

Pole, ktorého hodnota je null, nie je vôbec serializované do tela spätného volania. Pre a správa, ktorá neprišla z Facebooku alebo Instagramu, jednoducho neexistuje kľúč MetaUserId. Považujte „neprítomný“ a null za to isté.

6.1 Zaregistrujte URL spätného volania

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	Typ	Popis
`url`	`string`	Váš koncový bod
`source`	`SendingSourceCallback`	Typ udalosti, pozri § 8.2
`headerName` / `headerValue`	`string`	Ľubovoľná autorizačná hlavička, ktorú pripojíme k požiadavke (voliteľné)
`channelType`	`ChatSource`	Kanál. `7` pre Instagram. Voliteľné
`channelEntityId`	`int`	Konkrétny podnikateľský účet. Vyžaduje `channelType`

Bez channelType adresa URL prijíma udalosti z každého kanála.

Tip

Úplné pokrytie komentárov vyžaduje dve registrácie: source: 12 pre nové komentáre a source: 13 pre stavy odpovede. Pre priame odpovede a odpovede príbehu pridajte source: 3 (a 11, ak chcete každú chatovú správu).

Zostávajúce operácie:

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 sa vracia:

[
  {
    "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 Nová správa a odpoveď na príbeh Instagramu (`source: 3`, `11`)

Odpoveď používateľa na Instagram Story príde ako obyčajná správa v týchto spätných volaniach, s dodatočným blokom Story najvyššej úrovne:

{
  "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	Popis
`ChatId` / `MessageId`	Identifikátory chatu a správ
`Author`	`0` používateľ, `1` operátor
`Username`	Zobrazované meno alebo rukoväť na Instagrame / Facebooku
`UserId`	Interné číselné ID užívateľa v SMSBAT
`MetaUserId`	Identifikátor konverzačného partnera v Meta. V odchádzajúcej správe operátora to stále identifikuje meta používateľa chatu, nie operátora
`ShopId`	Interné ID obchodného účtu Instagram / Facebook
`ShopName`	Názov obchodného účtu prijatý z Meta v čase pripojenia
`MessageText`	Text správy
`MessageMedia`	Adresa URL média, keď je správa mediálna
`type_messenger`	Zdroj, `7` pre Instagram
`operator_name`	Meno operátora, keď `Author = 1`
`Story`	Prezentovať len pri prichádzajúcej odpovedi na príbeh
`Story.Id`	ID interného príbehu (`MetaPost`) — použiteľné priamo ako `id` / `postId` v Meta API
`Story.MetaId`	Externé ID príbehu v Meta
`Story.Url`	Stabilná proxy adresa URL uloženého média Story. Chýba, keď sa médiá nepodarilo uložiť — blok `Story` a správa sú stále doručené

`Author` je invertovaný vzhľadom na rozhranie Chat API

V ChatMessageDTO.author, 0 znamená operátor a 1 znamená klienta. V tomto spätnom volaní je to tak naopak: 0 je používateľ, 1 je operátor. Nezdieľajte mapovanie.

6.3 Nový komentár (`source: 12`)

Spustí sa, keď používateľ Meta komentuje príspevok na Facebooku alebo príspevok na Instagrame / Reel.

Note

Instagram Odpovede na príbehy sa nedoručujú cez source: 12. Prichádzajú ako obyčajné prichádzajúce správy na source: 3 a/alebo 11 s blokom Story – pozri § 6.2.

{
  "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 Stav odpovede na komentár (`source: 13`)

Spustí sa, keď sa pokúsime doručiť odpoveď, či už je úspešná alebo neúspešná.

{
  "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 Zdieľané polia spätného volania komentárov

Obe spätné volanie komentárov zdieľajú jeden tvar tela a líšia sa iba type.

Pole	Popis
`type`	`"new_comment"` alebo `"comment_status"`
`platform`	`"facebook"` alebo `"instagram"`
`comment.id`	Interné ID komentára
`comment.metaId`	Externé ID v Meta; `null` pre čakajúcu odpoveď pred jej odoslaním
`comment.parentCommentId`	ID rodičovského komentára. Neprítomný pre komentár na najvyššej úrovni
`comment.parentMetaId`	ID externého nadradeného komentára. Neprítomný na najvyššej úrovni
`comment.parentCommentText`	Text komentára rodiča. Neprítomný na najvyššej úrovni
`comment.text`	Text komentára
`comment.createdAt`	Dátum vytvorenia
`comment.updatedAt`	Posledná aktualizácia. Chýba, ak komentár nebol nikdy upravený
`comment.replyStatus`	`"pending"` / `"sent"` / `"failure"`. Neprítomný pre prichádzajúci komentár používateľa
`comment.author.type`	`"meta_user"` alebo `"owner"`
`comment.author.name`	Meno autora
`comment.author.metaUserId`	Identifikátor autora v meta. Neprítomný pre `"owner"`
`comment.mediaUrl`	Komentovať médiá. Neprítomný, keď nie je žiadny
`post.id`	ID interného príspevku
`post.metaId`	Externý príspevok / cievka / ID príbehu v Meta
`post.text`	Text príspevku
`post.imageUrl`	Adresa URL príspevku alebo `null`
`post.createdAt`	Dátum vytvorenia príspevku
`post.mediaType`	Pri spätných volaniach komentárov iba `post` alebo `reel`

6.6 Nový chat (`source: 7`)

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

6.7 Zmeny stavu správ a chatu (`source: 6` / `5`)

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

6.8 Správa upravená alebo vymazaná (`source: 9`)

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

6.9 Indikátor písania (`source: 8`)

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

7. Prieskum udalostí

Pre prostredia, ktoré nemôžu akceptovať prichádzajúce HTTP.

7.1 Načítavanie udalostí

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

Parameter	Popis
`organizationId`	Voliteľné. Prevzaté z tokenu pri vynechaní
`page` / `perPage`	Stránkovanie, predvolené `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ždá udalosť nesie event_guid, timestamp, organization_id a callback_type — a reťazec zodpovedajúci hodnotám source v §8.2. Zostávajúce polia zodpovedajú zodpovedajúcim webhook v §6.

7.2 Potvrdzovanie spracovaných udalostí

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 }

Už odstránené udalosti sa jednoducho nezapočítavajú do deleted. Objednávanie a opakované pokusy sú na vás zodpovednosť strany.

7.3 Odporúčaná slučka

Hlasujte o GET /api/chat/callback-events v pláne.
Spracujte udalosti vo svojej službe.
Pošlite spracovaný zoznam event_guid na /callback-events/processed.
Opakujte.

8. Enum odkaz

8.1 `ChatSource` — kanál (0–9)

Kód	Kanál
0	Viber
1	ViberBot
2	TelegramBot
3	Whatsapp
4	Widget
5	Rozetka
6	Facebook
*7	Instagram
8	Prom
9	Olx

8.2 `SendingSourceCallback` — typ udalosti spätného volania (0–13)

Kód	Udalosť
3	`Chat` — nová chatová správa vrátane odpovedí na príbeh
5	Stav chatu zmenený
6	Stav správy zmenený
7	Bol vytvorený nový chat
8	Indikátor písania
9	Správa aktualizovaná alebo vymazaná
11	`AnyChatMessage` — akákoľvek chatová správa
12	`MetaNewComment` — nový komentár na Instagrame / Facebooku
13	`MetaCommentStatus` — stav doručenia našej odpovede na komentár

Enum má rozsah 0–13; zostávajúce hodnoty nie sú potrebné pre integráciu Instagramu.

8,3 `ChatStatus` (0–4)

0 Nové, 1 Otvorené, 2 Čaká sa, 3 OnPause, 4 Zatvorené

8,4 `MessageStatus` (0–11)

Kód	Meno
0	NOVINKA
1	ÚSPECH
2	ZAMIETNUTÉ
3	ČÍTAJTE
4	NEZNÁMY
5	SPRACOVANIE
6	DODANÉ
7	BLOCKED_BY_USER
8	USER_NOT_FOUND

Enum má rozsah 0–11. Hodnoty 9, 10 a 11 existujú v API, ale ešte nie sú zdokumentované — zaobchádzať s nimi ako s UNKNOWN.

8,5 `MediaType` (1–10)

1 Fotografia, 2 Súbor, 3 Zvuk, 4 Video, 5 Nálepka, 6 Nálepka Animované, 7 StickerVideo, 8 Animácia, 9 Hlas, 10 VideoPoznámka

8.6 `AuthorMessage` — autor v rozhraní Chat API (0–4)

0 Operátor, 1 Klient, 2 Bot, 3 ViberAccount

Enum má rozsah 0–4; hodnota 4 nie je zdokumentovaná. Spätné volanie „novej správy“ používa opačné mapovanie — pozri § 6.2.

8,7 `ChatMessageType` (0–2)

0 text, 1 fotografia, 2 súbor

8.8 Komentár `replyStatus`

null prichádzajúci komentár používateľa, "pending" naša odpoveď je zaradená do frontu, "sent" doručená, "failure" doručenie zlyhalo.

Otvorené otázky

Tri body, v ktorých interná špecifikácia a kódom vygenerovaný Swagger nesúhlasia. Jeden žiadosť so skutočným žetónom ich vyrovná; dovtedy píšte klientovi defenzívne.

#	Otázka	Špecifikácia	Swagger	Ako skontrolovať
1	Hlavička overenia pre `/api/meta/*`	`X-Authorization-Key`	len `Bearer` deklarovaných	`curl -i -H "X-Authorization-Key: <token>" ".../api/meta/posts?perPage=1"` — očakávajte `200`, nie `401`
2	Pole počítadla v meta odpovediach	`totalCount`	`total`	Rovnaká požiadavka – prečítajte si koreňový kľúč JSON
3	`author.type` typ a `reply` stavový kód	`"meta_user"` / `"owner"`, `202` s telom	`int [0,1]`, `200` bez tela	`curl -i .../api/meta/comments?perPage=1` plus testovacia odpoveď

Dočasné usmernenie:

počítadlo — čítaj total ?? totalCount;
author.type — akceptujte reťazec aj celé číslo (0 ↔ meta_user, 1 ↔ owner, mapovanie bude potvrdené);
reply — považujte akékoľvek 2xx za úspech, nevyžadujte žiadne telo, získajte konečný stav zo spätného volania source: 13.

Poznámky k implementácii

Auth sa líši podľa skupiny koncových bodov — /api/meta/* používa X-Authorization-Key, chaty a operátori používajú Bearer, restapi akceptuje buď.
Paginácia sa píše dvoma spôsobmi — per_page na /api/chat/chats, perPage na /api/meta/* a /api/chat/callback-events.
multipart/form-data polia sú PascalCase s bodkovým zápisom (Media.File, Media.Type).
V spätných volaniach sú vynechané prázdne polia — chýbajúce tlačidlo znamená null.
phone je zvyčajne null na Instagrame. Identifikujte zákazníka podľa instagramUser.id / metaUserId a obchod podľa instaAccount.id (hodnota filtra entityId).
Story.Id zo spätného volania môže byť odovzdané priamo späť ako id / postId do Meta API.
Pred použitím expiresAt operátora JWT v priamom odkaze alebo v miniaplikácii.