Help Center Integrace Meta a Instagram API

Integrace Meta a Instagram API

Reference pro vytvoření aplikace Instagram na platformě SMSBAT ChatHub: ověřování, Instagram Direct konverzace, komentáře k příspěvkům a kotoučům, odpovědi na příběhy, webhooky a hlasování.

Zdroje

Tato stránka spojuje interní specifikaci Meta Comments API s živým OpenAPI definice na https://chatapi.smsbat.com/swagger/v1/swagger.json a https://restapi.smsbat.com/swagger/v1/swagger.json. Kde se dva neshodnou, rozdíl je vyvolán inline a uveden v části Otevřené otázky.

1. Základní adresy URL

Účel	URL
Chat API + Meta API	`https://chatapi.smsbat.com`
Uživatelské rozhraní Swagger / OpenAPI	`https://chatapi.smsbat.com/index.html` · `…/swagger/v1/swagger.json`
REST API (organizace, URL zpětného volání)	`https://restapi.smsbat.com`
REST API Swagger	`https://restapi.smsbat.com/swagger/v1/swagger.json`
Webový panel operátora	`https://chat.smsbat.com`

2. Autentizace

Schéma ověřování závisí na skupině koncových bodů. Jejich smíchání je nejčastější příčinou 401.

Skupina	Záhlaví
`chatapi.smsbat.com/api/meta/*` (příspěvky, komentáře)	`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í ověření

Token organizace pro X-Authorization-Key je vydán v panelu pod Profil. JWT společnosti a operátora pocházejí z /api/company/get-token a /api/operator/get-token.

Rozpor

Dokument chatapi OpenAPI deklaruje jediné bezpečnostní schéma — Bearer — a aplikuje jej globálně. X-Authorization-Key tam není vůbec deklarováno, i když interní Meta Specifikace API pro komentáře jej pojmenovává jako /api/meta/*. S největší pravděpodobností to řeší middleware, který se v Swaggeru neodráží. Před odesláním empiricky potvrďte.

2.1 Token společnosti

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

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

200 OK vrací holý řetězec tokenů.

2.2 Organizace

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

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

2.3 Operátoři v organizaci

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 Aktivní, 1 Neaktivní, 2 Smazáno.

2.4 Přidat/synchronizovat operátory

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átí JWT jako řetězec.

2.6 Ověření 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
}

Když je neplatný: { "isValid": false, "error": "Invalid token" }.

2.7 Vložení panelu 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. Přímé odkazy do panelu chatu

Externí systém (CRM, ERP, web) může otevřít konkrétní konverzaci https://chat.smsbat.com/. Operátor je autorizován JWT předaným jako parametr dotazu.

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	Popis
`chat_raw_id`	ID chatu
`phone`	Telefonní číslo v mezinárodním formátu
`from`	Značka / identifikátor obchodního účtu (`bm_id`)
`source`	Zdroj chatu — `7` pro Instagram, viz §8.1
`token`	Platný, nevypršený operátor JWT s přístupem k chatům

Neplatný JWT přivede návštěvníka na přihlašovací obrazovku ovládacího panelu.

4. Instagram Přímé konverzace

4.1 Seznam chatů

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

Note

Stránkování zde je per_page (hadí_případ). Pod /api/meta/* a hlasování koncový bod je perPage (camelCase). Toto není překlep – API používá obojí.

Parametry dotazu, všechny volitelné:

Parametr	Typ	Popis
`source`	`ChatSource`	`7` omezuje výsledky na Instagram
`entityId`	`int`	ID firemního účtu. Platí pouze společně s `source`
`instagram_user_id`	`int`	ID uživatele Instagramu v ChatHubu
`facebook_user_id`	`int`	ID uživatele Facebooku v ChatHubu
`page` / `per_page`	`int`	Stránkování, výchozí `1` / `20`
`status`	`ChatStatus[]`	Stav chatu, opakovatelný
`search`	`string`	Vyhledávání pomocí libovolného textu (jméno, telefon, …)
`organizationId`	`int`	ID organizace
`operatorId`	`int[]`	Filtrovat podle přiřazených operátorů
`date`	`string[]`	Dvě hranice: `?date=…&date=…`
`isChain`	`bool`	Vrátit chaty jako řetězy, přenášející zprávy z předchozích chatů
`isUnread`, `starMark`, `isOperator`, `isAIAgent`	`bool`	Přídavné filtry
`phone`, `email`, `contactId`, `clientId`, `tagIds`, `rate`, `sortedBy`	—	Ostatní filtry

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

Pole, která jsou pro aplikaci Instagram důležitá:

Pole	Význam
`instaAccount`	Instagramový obchodní účet (obchod). `id` je hodnota filtru `entityId`; `name` je název účtu z Meta
`instagramUser`	Zákazník. `name` je popisovač Instagramu, `id` je hodnota filtru `instagram_user_id`
`metaUserId`	ID zákazníka v rozsahu na straně Meta (řetězec)
`messSource`	`7` pro Instagram
`phone`	Obvykle `null` pro Instagram — nepoužívejte jej jako klíč

ChatDTO také nese 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é zprávy

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

200 OK vrátí 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 je vyplněno, když se zpráva týká příspěvku na Instagramu nebo příběhu – předejte ji rovnou zpět jako id / postId do Meta API. media je ChatMediaDTO: { name, format, type, uri, raw, length, isUploaded }.

4.3 Odeslat zprávu (JSON)

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

Tělo — 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 zprávy. Může být prázdný, pokud je přítomen `media`
`author`	`AuthorMessage?`	`0` operátor, `1` klient
`isInternal`	`bool?`	`true` označuje interní poznámku, která není doručena zákazníkovi
`replyToMessageId`	`int?`	ID zprávy, na kterou se odpovídá
`appGuid`	`uuid?`	GUID doporučení
`media`	`MediaDTO?`	`{ name, format, dataBase64, thumbnail, duration, type }`

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

Referenční GUID lze také předat v cestě: POST /api/chat/{chatId}/{referralGuid}/message (stejně jako …/message/v1, …/message/v2).

4.4 Odeslání souboru nebo videa (multipart, v2)

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

Názvy polí formuláře jsou PascalCase s tečkovou notací

textMessage a media.file jsou tiše ignorovány. Použijte níže uvedená přesná jména.

Pole formuláře	Typ	Popis
`TextMessage`	`string`	Text zprávy
`Author`	`int`	`0` operátor, `1` klient
`IsInternal`	`bool`	Interní poznámka
`ReplyToMessageId`	`int`	Na zprávu odpovídáte
`AppGuid`	`uuid`	GUID doporučení
`Media.File`	`binary`	Samotný soubor
`Media.Name`	`string`	Název souboru
`Media.Format`	`string`	Typ MIME (`video/mp4`, `image/png`, `application/pdf`)
`Media.Type`	`MediaType`	Viz §8.5
`Media.DataBase64`	`string`	Alternativa k `Media.File`
`Media.Thumbnail`	`string`	Rámeček náhledu videa Base64
`Media.Duration`	`double`	Délka 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 Změna 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 Aktualizace stavů zpráv

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

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

4.7 Smazání chatu

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

5. Příspěvky, kotouče a příběhy

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

5.1 Seznam příspěvků, kotoučů a příběhů

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

Parametr	Typ	Povinné	Popis
`page`	`int`	ne	Stránka, výchozí `1`
`perPage`	`int`	ne	Počet položek na stránku, výchozí `20`
`id`	`int`	ne	Filtrovat podle interního ID příspěvku
`platform`	`string`	ne	`instagram` nebo `facebook`
`mediaType`	`string`	ne	`post`, `reel` nebo `story`. Všechny typy při vynechání

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

Neshoda — název pole počítadla

Schéma Swagger MetaCommentPostListItemDtoPaginationDTO definuje total. The dokumenty interní specifikace totalCount. Swagger je generován z kódu, takže total je pravděpodobnější pravda. Analyzujte total ?? totalCount, dokud se to nevyřeší.

Pole	Popis
`id`	ID interního příspěvku
`metaId`	Externí příspěvek / cívka / ID příběhu v Meta
`text`	Titulek příspěvku
`imageUrl`	Proxy média URL zadaná nesekvenčním `MetaPost.Guid` nebo `null`
`platform`	`facebook` nebo `instagram`
`mediaType`	`post`, `reel` nebo `story`
`createdAt`	Datum vytvoření (datum platformy nebo datum databáze)
`story`	Dárek pouze za `mediaType: "story"`
`story.id`	Interní ID příběhu; rovná se `post.id`
`story.metaId`	Externí ID příběhu v Meta
`story.url`	Stabilní proxy URL uloženého média Story; `null`, pokud média nelze uložit

Poštovní média jsou obsluhována dvěma cestami: GET /api/meta/post/media/{id:int} pro zpětný chod kompatibilita a GET /api/meta/post/media/{guid:guid}. Nové odpovědi API a zpětná volání vždy vygenerujte formulář GUID.

5.2 Seznam komentářů

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

Parametr	Typ	Povinné	Popis
`page`	`int`	ne	Stránka, výchozí `1`
`perPage`	`int`	ne	Počet položek na stránku, výchozí `20`
`postId`	`int`	ne	Filtrovat podle ID příspěvku
`parentCommentId`	`int`	ne	Podřízené komentáře (odpovědi) daného komentáře
`platform`	`string`	ne	`facebook` nebo `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áře
`metaId`	Externí ID v Meta. `null` za naši čekající odpověď, dokud nebude odeslána
`text`	Text komentáře
`createdAt`	Datum vytvoření
`platform`	`facebook` nebo `instagram`
`replyStatus`	`null` pro příchozí uživatelský komentář; `"pending"` / `"sent"` / `"failure"` za naši odpověď
`author.type`	`"meta_user"` externí uživatel, `"owner"` vlastník stránky
`author.name`	Jméno autora
`author.metaUserId`	ID uživatele s rozsahem v Meta; `null` za `"owner"`
`post`	Příspěvek, cívka nebo příběh, kterému komentář patří
`post.mediaType`	`post`, `reel` nebo `story`
`post.story`	Odkaz na příběh `{ id, metaId, url }`, pouze příběhy
`mediaUrl`	Média připojená ke komentáři nebo `null`
`replyTo`	Komentář rodiče `{ id, metaId, text }`; `null` na nejvyšší úrovni

Nesoulad – typ `author.type`

Interní specifikace dokumentuje řetězce "meta_user" / "owner". Swagger typy MetaCommentAuthorType jako celé číslo s enum [0, 1]. A JsonStringEnumConverter by vysvětlovalo mezeru, ale to nebylo potvrzeno proti skutečné odpovědi. Napište a parser, který přijímá obojí.

5.3 Odpovědět na komentář

Pořadí odpověď na doručení.

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"

Tělo požadavku: { "text": "Reply text" }

202 Accepted vrátí objekt komentáře — stejný tvar jako GET /api/meta/comments — s replyStatus: "pending" a metaId: null. Výsledek doručení se dostaví později jako a source: 13 zpětné volání (§6.4).

Nesoulad — kód odpovědi

Swagger deklaruje 200 bez těla; interní specifikace deklaruje 202 Accepted s komentářem jako tělem. Ovladač s největší pravděpodobností postrádá ProducesResponseType atribut, takže Swagger zůstane ve výchozím nastavení. Přijměte jakékoli 2xx a nezávisejte na těle.

6. Webhooky

SMSBAT odešle POST požadavků s application/json na vaši URL a očekává HTTP 200 zpět.

Nová pole jsou zcela vynechána

Pole, jehož hodnota je null, není vůbec serializováno do těla zpětného volání. Pro a zpráva, která nepřišla z Facebooku nebo Instagramu, prostě žádný klíč MetaUserId neexistuje. Považujte „nepřítomný“ a null za totéž.

6.1 Zaregistrujte URL zpětného volání

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 události, viz §8.2
`headerName` / `headerValue`	`string`	Libovolná autentizační hlavička, kterou připojíme k požadavku (volitelné)
`channelType`	`ChatSource`	Kanál. `7` pro Instagram. Volitelné
`channelEntityId`	`int`	Konkrétní obchodní účet. Vyžaduje `channelType`

Bez channelType přijímá URL události z každého kanálu.

Tip

Úplné pokrytí komentářů vyžaduje dvě registrace: source: 12 pro nové komentáře a source: 13 pro stavy odpovědí. Pro přímé odpovědi a odpovědi příběhu přidejte source: 3 (a 11, pokud chcete každou chatovou zprávu).

Zbývající operace:

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 se vrací:

[
  {
    "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á zpráva a odpověď na příběh Instagramu (`source: 3`, `11`)

Odpověď uživatele na Instagram Story přijde jako běžná zpráva v těchto zpětných voláních, s dalším blokem Story nejvyšší úrovně:

{
  "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`	Chat a identifikátory zpráv
`Author`	`0` uživatel, `1` operátor
`Username`	Zobrazované jméno nebo popisovač na Instagramu / Facebooku
`UserId`	Interní číselné uživatelské ID v SMSBAT
`MetaUserId`	ID konverzačního partnera v Meta. Na odchozí zprávě operátora to stále identifikuje uživatele Meta chatu, nikoli operátora
`ShopId`	Interní ID obchodního účtu Instagram / Facebook
`ShopName`	Název obchodního účtu tak, jak byl přijat z Meta v době připojení
`MessageText`	Text zprávy
`MessageMedia`	Adresa URL média, když je zpráva mediální
`type_messenger`	Zdroj, `7` pro Instagram
`operator_name`	Jméno operátora, když `Author = 1`
`Story`	Prezentovat pouze v příchozí odpovědi na příběh
`Story.Id`	ID interního příběhu (`MetaPost`) — použitelné přímo jako `id` / `postId` v Meta API
`Story.MetaId`	Externí ID příběhu v Meta
`Story.Url`	Stabilní proxy URL uloženého média Story. Chybí, když média nelze uložit — blok `Story` a zpráva jsou stále doručeny

`Author` je převráceno vzhledem k rozhraní Chat API

V ChatMessageDTO.author, 0 znamená operátor a 1 znamená klient. V tomto zpětném volání je naopak: 0 je uživatel, 1 je operátor. Nesdílejte mapování.

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

Spustí se, když uživatel Meta okomentuje příspěvek na Facebooku nebo Instagramu / Reel.

Note

Instagram Odpovědi na příběhy se nedoručují prostřednictvím source: 12. Přicházejí jako běžné příchozí zprávy na source: 3 a/nebo 11 s blokem Story — viz §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 odpovědi na komentář (`source: 13`)

Spustí se poté, co se pokusíme doručit odpověď, ať už je úspěšná, nebo selže.

{
  "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 Sdílená pole zpětného volání komentáře

Obě zpětná volání komentáře sdílejí jeden tvar těla a liší se pouze o type.

Pole	Popis
`type`	`"new_comment"` nebo `"comment_status"`
`platform`	`"facebook"` nebo `"instagram"`
`comment.id`	Interní ID komentáře
`comment.metaId`	Externí ID v Meta; `null` pro čekající odpověď před jejím odesláním
`comment.parentCommentId`	ID komentáře rodiče. Nepřítomný pro komentář nejvyšší úrovně
`comment.parentMetaId`	ID externího nadřazeného komentáře. Chybí na nejvyšší úrovni
`comment.parentCommentText`	Text komentáře rodiče. Chybí na nejvyšší úrovni
`comment.text`	Text komentáře
`comment.createdAt`	Datum vytvoření
`comment.updatedAt`	Poslední aktualizace. Chybí, pokud komentář nebyl nikdy upraven
`comment.replyStatus`	`"pending"` / `"sent"` / `"failure"`. Nepřítomný pro příchozí komentář uživatele
`comment.author.type`	`"meta_user"` nebo `"owner"`
`comment.author.name`	Jméno autora
`comment.author.metaUserId`	ID autora s rozsahem v Meta. Nepřítomen pro `"owner"`
`comment.mediaUrl`	Média komentářů. Chybí, když žádná není
`post.id`	ID interního příspěvku
`post.metaId`	Externí příspěvek / cívka / ID příběhu v Meta
`post.text`	Text příspěvku
`post.imageUrl`	Adresa URL příspěvku nebo `null`
`post.createdAt`	Datum vytvoření příspěvku
`post.mediaType`	Při zpětných voláních komentářů pouze `post` nebo `reel`

6.6 Nový chat (`source: 7`)

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

6.7 Změny stavu zpráv a chatu (`source: 6` / `5`)

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

6.8 Zpráva upravena nebo smazána (`source: 9`)

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

6.9 Indikátor psaní (`source: 8`)

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

7. Dotazování událostí

Pro prostředí, která nemohou přijímat příchozí HTTP.

7.1 Načítání událostí

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

Parametr	Popis
`organizationId`	Volitelný. Převzato z tokenu při vynechání
`page` / `perPage`	Stránkování, výchozí `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á událost nese event_guid, timestamp, organization_id a callback_type — a řetězec odpovídající hodnotám source v §8.2. Zbývající pole odpovídají odpovídajícím webhook v §6.

7.2 Potvrzení zpracovaných událostí

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 }

Již odstraněné události se jednoduše nezapočítávají do deleted. Objednávání a opakování jsou vaše odpovědnost strany.

7.3 Doporučená smyčka

Hlasujte o GET /api/chat/callback-events podle plánu.
Zpracujte události ve vaší službě.
Odešlete zpracovaný seznam event_guid na /callback-events/processed.
Opakujte.

8. Enum reference

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 události zpětného volání (0–13)

Kód	Akce
3	`Chat` — nová chatová zpráva, včetně odpovědí na příběh
5	Stav chatu změněn
6	Stav zprávy změněn
7	Vytvořen nový chat
8	Indikátor psaní
9	Zpráva aktualizována nebo smazána
11	`AnyChatMessage` — jakákoli chatová zpráva
12	`MetaNewComment` — nový komentář na Instagramu / Facebooku
13	`MetaCommentStatus` — stav doručení naší odpovědi na komentář

Enum zahrnuje 0–13; zbývající hodnoty nejsou potřeba pro integrace Instagramu.

8,3 `ChatStatus` (0–4)

0 Nové, 1 Otevřeno, 2 Čekání, 3 OnPause, 4 Zavřeno

8,4 `MessageStatus` (0–11)

Kód	Jméno
0	NOVINKA
1	ÚSPĚCH
2	ODMÍTNUTO
3	ČTĚTE
4	NEZNÁMÝ
5	ZPRACOVÁNÍ
6	DODÁNO
7	BLOCKED_BY_USER
8	USER_NOT_FOUND

Enum zahrnuje 0–11. Hodnoty 9, 10 a 11 existují v API, ale ještě nejsou zdokumentovány — zacházet s nimi jako s UNKNOWN.

8,5 `MediaType` (1–10)

1 Fotografie, 2 Soubor, 3 Zvuk, 4 Video, 5 Nálepka, 6 Nálepka Animovaný, 7 StickerVideo, 8 Animace, 9 Voice, 10 VideoNote

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

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

Enum zahrnuje 0–4; hodnota 4 není zdokumentována. ** Zpětná volání “nová zpráva” používají opačné mapování** — viz §6.2.

8,7 `ChatMessageType` (0–2)

0 Text, 1 Fotografie, 2 Soubor

8.8 Komentář `replyStatus`

null příchozí uživatelský komentář, "pending" naše odpověď je zařazena do fronty, "sent" doručena, "failure" doručení se nezdařilo.

Otevřené otázky

Tři body, kde se interní specifikace a kódem vygenerovaný Swagger neshodují. Jeden žádost se skutečným žetonem vypořádá všechny; do té doby pište klienta defenzivně.

#	Otázka	Specifikace	Swagger	Jak zkontrolovat
1	Auth záhlaví pro `/api/meta/*`	`X-Authorization-Key`	pouze `Bearer` deklarováno	`curl -i -H "X-Authorization-Key: <token>" ".../api/meta/posts?perPage=1"` — očekávejte `200`, ne `401`
2	Pole čítače v odpovědích Meta	`totalCount`	`total`	Stejný požadavek — přečtěte si kořenový klíč JSON
3	`author.type` typ a `reply` stavový kód	`"meta_user"` / `"owner"`, `202` s tělem	`int [0,1]`, `200` bez těla	`curl -i .../api/meta/comments?perPage=1` plus testovací odpověď

Prozatímní návod:

počítadlo — čtení total ?? totalCount;
author.type — přijímá řetězec i celé číslo (0 ↔ meta_user, 1 ↔ owner, mapování bude potvrzeno);
reply — považujte jakékoli 2xx za úspěch, nevyžadujte žádné tělo, převezměte konečný stav ze zpětného volání source: 13.

Poznámky k implementaci

Auth se liší podle skupiny koncových bodů — /api/meta/* používá X-Authorization-Key, chaty a operátoři používají Bearer, restapi přijímá buď.
Paginace se píše dvěma způsoby — per_page na /api/chat/chats, perPage na /api/meta/* a /api/chat/callback-events.
multipart/form-data pole jsou PascalCase s tečkovou notací (Media.File, Media.Type).
Nulová pole jsou ze zpětných volání vynechána — chybějící klíč znamená null.
phone je na Instagramu obvykle null. Identifikujte zákazníka podle instagramUser.id / metaUserId a obchod podle instaAccount.id (hodnota filtru entityId).
Story.Id ze zpětného volání může být předáno přímo zpět jako id / postId do Meta API.
Před použitím v přímém odkazu nebo widgetu zkontrolujte expiresAt operátora JWT.