Help Center Meta- ja Instagram-sovellusliittymäintegraatio

Meta- ja Instagram-sovellusliittymäintegraatio

Viite Instagram-sovelluksen rakentamiseen SMSBAT ChatHub -alustalle: todennus, Instagram-suorat keskustelut, viestien kommentit ja rullat, tarinavastaukset, webhookit ja äänestykset.

Lähteet

Tämä sivu yhdistää sisäisen Meta Comments API -määrityksen live OpenAPI

määritelmät osoitteessa https://chatapi.smsbat.com/swagger/v1/swagger.json ja https://restapi.smsbat.com/swagger/v1/swagger.json. Jos nämä kaksi ovat eri mieltä, ero on lueteltu rivissä ja lueteltu kohdassa Avoimet kysymykset.

1. Perus-URL-osoitteet

Tarkoitus	URL
Chat API + Meta API	`https://chatapi.smsbat.com`
Swagger UI / OpenAPI	`https://chatapi.smsbat.com/index.html` · `…/swagger/v1/swagger.json`
REST API (organisaatiot, takaisinsoitto-URL-osoitteet)	`https://restapi.smsbat.com`
REST API Swagger	`https://restapi.smsbat.com/swagger/v1/swagger.json`
Käyttäjän verkkopaneeli	`https://chat.smsbat.com`

2. Todennus

Todennusmalli riippuu päätepisteryhmästä. Mixing them up is the most common cause of 401.

Ryhmä	Otsikko
`chatapi.smsbat.com/api/meta/*` (viestit, kommentit)	`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` · Perustodennus

Organisaation tunnus numerolle X-Authorization-Key myönnetään paneelissa kohdassa Profiili. Company and operator JWTs come from /api/company/get-token and /api/operator/get-token.

Poikkeus

The chatapi OpenAPI document declares a single security scheme — Bearer — and applies it maailmanlaajuisesti. X-Authorization-Key ei ole ilmoitettu siellä ollenkaan, vaikka sisäinen meta Comments API

spesifikaatio antaa sille nimen /api/meta/*. Sen hoitaa todennäköisesti väliohjelmisto, joka ei näy Swaggerissa. Vahvista empiirisesti ennen lähettämistä.

2.1 Yrityksen tunnus

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

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

200 OK palauttaa paljaan merkkijonon.

2.2 Organisaatiot

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

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

2.3 Toimijat organisaatiossa

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

Operaattorin tilat: 0 aktiivinen, 1 ei-aktiivinen, 2 poistettu.

2.4 Lisää / synkronoi operaattoreita

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 Käyttäjä 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 palauttaa JWT

merkkijonona.

2.6 Vahvista operaattoritunnus

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
}

Kun virheellinen: { "isValid": false, "error": "Invalid token" }.

2.7 Upota käyttäjän chat-paneeli

<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. Syvälinkit chat-paneeliin

An external system (CRM, ERP, website) can open a specific conversation in https://chat.smsbat.com/. The operator is authorized by a JWT passed as a query parameter.

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	Kuvaus
`chat_raw_id`	Chat ID
`phone`	Puhelinnumero kansainvälisessä muodossa
`from`	Brändin/yritystilin tunniste (`bm_id`)
`source`	Chat source — `7` for Instagram, see §8.1
`token`	Valid, unexpired operator JWT with access to chats

An invalid JWT lands the visitor on the operator panel’s login screen.

4. Instagram Direct -keskustelut

4.1 Listaa keskustelut

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

Note

Sivutus tässä on per_page (käärme_tapaus). Alle /api/meta/* ja äänestys päätepiste on perPage (camelCase). Tämä ei ole kirjoitusvirhe – API käyttää molempia.

Kyselyparametrit, kaikki valinnaiset:

Parametri	Tyyppi	Kuvaus
`source`	`ChatSource`	`7` rajoittaa tulokset Instagramiin
`entityId`	`int`	Yritystilin tunnus. Käytetään vain yhdessä `source`
`instagram_user_id`	`int`	Instagram-käyttäjätunnus ChatHubissa
`facebook_user_id`	`int`	Facebook-käyttäjätunnus ChatHubissa
`page` / `per_page`	`int`	Sivutus, oletusarvot `1` / `20`
`status`	`ChatStatus[]`	Chatin tila, toistettava
`search`	`string`	Vapaa tekstihaku (nimi, puhelin, …)
`organizationId`	`int`	Organisaation tunnus
`operatorId`	`int[]`	Suodata määritettyjen operaattoreiden mukaan
`date`	`string[]`	Kaksi rajaa: `?date=…&date=…`
`isChain`	`bool`	Return chats as chains, carrying messages from previous chats
`isUnread`, `starMark`, `isOperator`, `isAIAgent`	`bool`	Lisäsuodattimet
`phone`, `email`, `contactId`, `clientId`, `tagIds`, `rate`, `sortedBy`	—	Muut suodattimet

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

Instagram-sovelluksen kannalta tärkeät kentät:

Kenttä	Merkitys
`instaAccount`	Instagram-yritystili (kauppa). `id` on `entityId` suodattimen arvo; `name` on Meta
`instagramUser`	asiakas. `name` is the Instagram handle, `id` is the `instagram_user_id` filter value
`metaUserId`	The customer’s scoped ID on Meta’s side (string)
`messSource`	`7` Instagramille
`phone`	Yleensä `null` Instagramille – älä käytä sitä avaimena

ChatDTO also carries 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 ja taggedMessages.

4.2 Chat-viestit

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

200 OK palauttaa taulukon 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 is populated when the message relates to an Instagram post or Story — pass it straight back as id / postId to the Meta API. media on ChatMediaDTO: { name, format, type, uri, raw, length, isUploaded }.

4.3 Lähetä viesti (JSON)

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

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

Kenttä	Tyyppi	Kuvaus
`textMessage`	`string?`	Viestin teksti. Saattaa olla tyhjä, kun `media` on läsnä
`author`	`AuthorMessage?`	`0` operaattori, `1` asiakas
`isInternal`	`bool?`	`true` merkitsee sisäistä muistiinpanoa, jota ei toimiteta asiakkaalle
`replyToMessageId`	`int?`	Vastattavan viestin tunnus
`appGuid`	`uuid?`	Viittauksen GUID
`media`	`MediaDTO?`	`{ name, format, dataBase64, thumbnail, duration, type }`

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

Viittaus-GUID voidaan myös välittää polussa: POST /api/chat/{chatId}/{referralGuid}/message (samoin …/message/v1, …/message/v2).

4.4 Lähetä tiedosto tai video (moniosainen, v2)

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

Lomakekenttien nimet ovat PascalCase-kirjaimia pistemerkinnällä

textMessage ja media.file ohitetaan hiljaa. Käytä tarkkoja nimiä alla.

Lomakekenttä	Tyyppi	Kuvaus
`TextMessage`	`string`	Viestin teksti
`Author`	`int`	`0` operaattori, `1` asiakas
`IsInternal`	`bool`	Sisäinen huomautus
`ReplyToMessageId`	`int`	Viestiin vastataan
`AppGuid`	`uuid`	Viittauksen GUID
`Media.File`	`binary`	Itse tiedosto
`Media.Name`	`string`	Tiedoston nimi
`Media.Format`	`string`	MIME-tyyppi (`video/mp4`, `image/png`, `application/pdf`)
`Media.Type`	`MediaType`	Katso §8.5
`Media.DataBase64`	`string`	Vaihtoehto numerolle `Media.File`
`Media.Thumbnail`	`string`	Base64-videon esikatselukehys
`Media.Duration`	`double`	Videon kesto sekunneissa

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 Muuta chatin tilaa

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

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

200 OK toistaa päivitetyn objektin.

4.6 Päivitä viestien tilat

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

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

4.7 Poista keskustelu

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

5. Viestit, rullat ja tarinat

Peruspolku: https://chatapi.smsbat.com/api/meta Todennus: X-Authorization-Key: <organization token>

5.1 Listaa viestit, rullat ja tarinat

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

Parametri	Tyyppi	Pakollinen	Kuvaus
`page`	`int`	ei	Sivu, oletus `1`
`perPage`	`int`	ei	Kohteita sivulla, oletusarvo `20`
`id`	`int`	ei	Suodata sisäisen viestitunnuksen mukaan
`platform`	`string`	ei	`instagram` tai `facebook`
`mediaType`	`string`	ei	`post`, `reel` tai `story`. Kaikki tyypit, kun jätetään pois

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

Poikkeus — laskurikentän nimi

Swagger-skeema MetaCommentPostListItemDtoPaginationDTO määrittää total. The sisäiset erittelyasiakirjat totalCount. Swagger luodaan koodista, joten total on todennäköisempi totuus. Jäsennä total ?? totalCount, kunnes tämä on ratkaistu.

Kenttä	Kuvaus
`id`	Sisäinen viestitunnus
`metaId`	Ulkoinen viesti / kela / tarinatunnus meta
`text`	Viestin kuvateksti
`imageUrl`	Välityspalvelimen median URL-osoite, joka on näppäilty ei-peräkkäisellä `MetaPost.Guid` tai `null`
`platform`	`facebook` tai `instagram`
`mediaType`	`post`, `reel` tai `story`
`createdAt`	Luontipäivämäärä (alustan päivämäärä tai tietokannan päivämäärä)
`story`	Lahja vain hintaan `mediaType: "story"`
`story.id`	Sisäinen tarinatunnus; yhtä suuri kuin `post.id`
`story.metaId`	Ulkoinen tarinatunnus Meta
`story.url`	Tallennetun Story-median vakaa välityspalvelimen URL-osoite; `null` jos mediaa ei voitu tallentaa

Postitusmediaa palvelee kaksi reittiä: GET /api/meta/post/media/{id:int} taaksepäin yhteensopivuus ja GET /api/meta/post/media/{guid:guid}. Uusia API-vastauksia ja takaisinsoittoja luo aina GUID-lomake.

5.2 Listaa kommentit

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

Parametri	Tyyppi	Pakollinen	Kuvaus
`page`	`int`	ei	Sivu, oletus `1`
`perPage`	`int`	ei	Kohteita sivulla, oletusarvo `20`
`postId`	`int`	ei	Suodata postitunnuksen mukaan
`parentCommentId`	`int`	ei	Tietyn kommentin lapsikommentit (vastaukset)
`platform`	`string`	ei	`facebook` tai `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..."
      }
    }
  ]
}

Kenttä	Kuvaus
`id`	Sisäinen kommentin tunnus
`metaId`	Ulkoinen tunnus metassa. `null` odottavasta vastauksestamme, kunnes se lähetetään
`text`	Kommentin teksti
`createdAt`	Luontipäivä
`platform`	`facebook` tai `instagram`
`replyStatus`	`null` saapuvan käyttäjän kommentille; `"pending"` / `"sent"` / `"failure"` vastauksellemme
`author.type`	`"meta_user"` ulkoinen käyttäjä, `"owner"` sivun omistaja
`author.name`	Tekijän nimi
`author.metaUserId`	Rajattu käyttäjätunnus metassa; `null` arvolle `"owner"`
`post`	Viesti, kela tai tarina, jolle kommentti kuuluu
`post.mediaType`	`post`, `reel` tai `story`
`post.story`	Tarinan viite `{ id, metaId, url }`, vain tarinat
`mediaUrl`	Kommentin liitteenä oleva media tai `null`
`replyTo`	Vanhemman kommentti `{ id, metaId, text }`; `null` huipputasolla

Poikkeama – tyyppi `author.type`

Sisäinen eritelmä dokumentoi merkkijonot "meta_user" / "owner". Swagger-tyypit MetaCommentAuthorType kokonaislukuna, jonka numero on [0, 1]. A JsonStringEnumConverter selittäisi aukon, mutta sitä ei ole vahvistettu todellista vastausta vastaan. Kirjoita a jäsentäjä, joka hyväksyy molemmat.

5.3 Vastaa kommenttiin

Jonottaa vastausta toimitusta varten.

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"

Pyynnön teksti: { "text": "Reply text" }

202 Accepted palauttaa kommenttiobjektin — saman muodon kuin GET /api/meta/comments — ja replyStatus: "pending" ja metaId: null. Toimitustulos saapuu myöhemmin a source: 13 takaisinsoitto (§6.4).

Poikkeus - vastauskoodi

Swagger ilmoittaa 200 ilman ruumista; sisäinen eritelmä ilmoittaa 202 Accepted kommentin runkoon. Ohjaimesta puuttuu todennäköisesti ProducesResponseType attribuutti, jättäen Swaggerin oletusarvoksi. Hyväksy mikä tahansa 2xx äläkä ole riippuvainen kehosta.

6. Webhooks

SMSBAT lähettää POST pyyntöä application/json URL-osoitteeseesi ja odottaa HTTP 200 takaisin.

Tyhjät kentät jätetään kokonaan pois

Kenttää, jonka arvo on null, ei sarjoiteta takaisinsoittotekstiin ollenkaan. a Viesti, joka ei ole tullut Facebookista tai Instagramista, avainta MetaUserId ei yksinkertaisesti ole. Käsittele “poissa” ja null samana asiana.

6.1 Rekisteröi takaisinsoitto-URL-osoite

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

Kenttä	Tyyppi	Kuvaus
`url`	`string`	Päätepisteesi
`source`	`SendingSourceCallback`	Tapahtuman tyyppi, katso §8.2
`headerName` / `headerValue`	`string`	Pyyntöön liitettävä mielivaltainen todennusotsikko (valinnainen)
`channelType`	`ChatSource`	Kanava. `7` Instagramille. Valinnainen
`channelEntityId`	`int`	Tietty yritystili. Vaatii `channelType`

Ilman channelType-osoitetta URL vastaanottaa tapahtumia kaikilta kanavilta.

Tip

Täysi kommenttikattavuus vaatii kaksi rekisteröintiä: source: 12 uusia kommentteja ja source: 13 vastaustiloihin. Lisää suoria ja tarinavastauksia varten source: 3 (ja 11, jos haluat jokaisen chat-viestin).

Jäljellä olevat toiminnot:

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

[
  {
    "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 Uusi viesti ja Instagram Story -vastaus (`source: 3`, `11`)

Käyttäjän vastaus Instagram-tarinaan saapuu tavallisena viestinä näissä takaisinsoittoissa, ylimääräisellä ylätason Story-lohkolla:

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

Kenttä	Kuvaus
`ChatId` / `MessageId`	Chat- ja viestitunnisteet
`Author`	`0` käyttäjä, `1` operaattori
`Username`	Instagram / Facebook näyttönimi tai kahva
`UserId`	Sisäinen numeerinen käyttäjätunnus SMSBAT
`MetaUserId`	Meta-keskustelukumppanin laajennettu tunnus. Lähtevässä operaattoriviestissä tämä tunnistaa silti chatin metakäyttäjän, ei operaattorin
`ShopId`	Instagram-/Facebook-yritystilin sisäinen tunnus
`ShopName`	Yritystilin nimi sellaisena kuin se vastaanotettiin Metalta yhteyshetkellä
`MessageText`	Viestin teksti
`MessageMedia`	Median URL-osoite, kun viesti on media
`type_messenger`	Lähde, `7` Instagramille
`operator_name`	Operaattorin nimi, kun `Author = 1`
`Story`	Esitä vain saapuvan tarinan vastauksessa
`Story.Id`	Sisäinen tarina (`MetaPost`) -tunnus — käytettävä suoraan nimellä `id` / `postId` Meta API
`Story.MetaId`	Ulkoinen tarinatunnus Meta
`Story.Url`	Tallennetun Story-median vakaa välityspalvelimen URL-osoite. Poissa, kun mediaa ei voitu tallentaa — `Story`-lohko ja viesti toimitetaan edelleen

`Author` on käänteinen suhteessa Chat-sovellusliittymään

Kohdassa ChatMessageDTO.author 0 tarkoittaa operaattoria ja 1 tarkoittaa asiakasta. Tässä takaisinsoitossa se on toisin päin: 0 on käyttäjä, 1 on operaattori. Älä jaa karttaa.

6.3 Uusi kommentti (`source: 12`)

Syttyy, kun Meta-käyttäjä kommentoi Facebook-julkaisua tai Instagram-julkaisua/rullaa.

Note

Instagram Tarinavastauksia ei toimiteta numeroon source: 12. Ne saapuvat tavalliseen tapaan saapuvat viestit numeroissa source: 3 ja/tai 11, joissa on Story-esto – katso §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 Kommentin vastauksen tila (`source: 13`)

Syttyy, kun yritämme toimittaa vastauksen, onnistuipa se tai epäonnistuu.

{
  "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 Jaetut kommenttien takaisinsoittokentät

Molemmilla kommenttien takaisinkutsuilla on yksi vartalon muoto ja ero on vain type.

Kenttä	Kuvaus
`type`	`"new_comment"` tai `"comment_status"`
`platform`	`"facebook"` tai `"instagram"`
`comment.id`	Sisäinen kommentin tunnus
`comment.metaId`	Ulkoinen tunnus metassa; `null` odottavalle vastaukselle ennen sen lähettämistä
`comment.parentCommentId`	Vanhemman kommentin tunnus. Poissa huipputason kommentille
`comment.parentMetaId`	Ulkoisen vanhemman kommentin tunnus. Poissa huipputasolla
`comment.parentCommentText`	Vanhemman kommenttiteksti. Poissa huipputasolla
`comment.text`	Kommentin teksti
`comment.createdAt`	Luontipäivä
`comment.updatedAt`	Viimeisin päivitys. Poissa, jos kommenttia ei ole koskaan muokattu
`comment.replyStatus`	`"pending"` / `"sent"` / `"failure"`. Poissa saapuvan käyttäjän kommentin vuoksi
`comment.author.type`	`"meta_user"` tai `"owner"`
`comment.author.name`	Tekijän nimi
`comment.author.metaUserId`	Rajattu tekijän tunnus metassa. Poissa `"owner"`
`comment.mediaUrl`	Kommentoi mediaa. Poissa, kun ei ole
`post.id`	Sisäinen viestitunnus
`post.metaId`	Ulkoinen viesti / kela / tarinatunnus meta
`post.text`	Viestiteksti
`post.imageUrl`	Lähetä kuvan URL-osoite tai `null`
`post.createdAt`	Viestin luomispäivämäärä
`post.mediaType`	Kommenttien takaisinkutsuissa vain `post` tai `reel`

6.6 Uusi chat (`source: 7`)

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

6.7 Viestien ja chatin tilan muutokset (`source: 6` / `5`)

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

6.8 Viestiä muokattu tai poistettu (`source: 9`)

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

6.9 Kirjoitusosoitin (`source: 8`)

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

7. Tapahtumaäänestys

Ympäristöille, jotka eivät voi hyväksyä saapuvaa HTTP

7.1 Hae tapahtumat

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

Parametri	Kuvaus
`organizationId`	Valinnainen. Otettu tunnuksesta, kun se jätetään pois
`page` / `perPage`	Sivutus, oletukset `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"
    }
  ]
}

Jokainen tapahtuma sisältää event_guid, timestamp, organization_id ja callback_type — merkkijono, joka vastaa kohdan 8.2 arvoja source. Loput kentät vastaavat vastaavaa webhook kohdassa 6.

7.2 Kuittaa käsitellyt tapahtumat

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 }

Jo poistettuja tapahtumia ei yksinkertaisesti lasketa mukaan numeroon deleted. Tilaus ja uudelleenyritykset ovat sinun puolen vastuulla.

7.3 Suositeltu silmukka

Kysely GET /api/chat/callback-events aikataulun mukaan.
Käsittele tapahtumat palvelussasi.
Lähetä käsitelty event_guid-luettelo numeroon /callback-events/processed.
Toista.

8. Enum-viite

8.1 `ChatSource` — kanava (0–9)

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

8.2 `SendingSourceCallback` — takaisinsoittotapahtuman tyyppi (0–13)

Koodi	Tapahtuma
3	`Chat` — uusi chat-viesti, mukaan lukien tarinan vastaukset
5	Chatin tila muutettu
6	Viestin tila muutettu
7	Uusi chat luotu
8	Kirjoitusilmaisin
9	Viesti päivitetty tai poistettu
11	`AnyChatMessage` — mikä tahansa chat-viesti
12	`MetaNewComment` — uusi Instagram-/Facebook-kommentti
13	`MetaCommentStatus` — kommenttivastauksemme toimitustila

Enum kattaa 0–13; jäljellä olevia arvoja ei tarvita Instagram-integraatioissa.

8.3 `ChatStatus` (0–4)

0 Uusi, 1 auki, 2 odottaa, 3 OnPause, 4 suljettu

8.4 `MessageStatus` (0–11)

Koodi	Nimi
0	UUSI
1	MENESTYS
2	hylätty
3	LUE
4	TUNTEMATON
5	KÄSITTELY
6	TOIMITETTU
7	BLOCKED_BY_USER
8	USER_NOT_FOUND

Enum kattaa 0–11. Arvot 9, 10 ja 11 ovat sovellusliittymässä, mutta niitä ei ole vielä dokumentoitu — kohtele niitä nimellä UNKNOWN.

8.5 `MediaType` (1–10)

1 valokuva, 2 tiedosto, 3 ääni, 4 video, 5 tarra, 6 tarraanimoitu, 7 TarraVideo, 8 Animaatio, 9 Ääni, 10 VideoNote

8.6 `AuthorMessage` — kirjoittaja Chat APIssa (0–4)

0 Operaattori, 1 Asiakas, 2 Botti, 3 ViberAccount

Enum kattaa 0–4; arvo 4 on dokumentoimaton. ** “Uusi viesti” -soitot käyttävät vastakkainen kartoitus** — katso §6.2.

8.7 `ChatMessageType` (0–2)

0 teksti, 1 valokuva, 2 tiedosto

8.8 Kommentti `replyStatus`

null saapuva käyttäjän kommentti, "pending" vastauksemme on jonossa, "sent" toimitettu, "failure" toimitus epäonnistui.

Avoimet kysymykset

Kolme kohtaa, joissa sisäinen eritelmä ja koodin luoma Swagger ovat eri mieltä. Yksi pyyntö oikealla tunnuksella ratkaisee ne kaikki; siihen asti kirjoita asiakkaalle puolustavasti.

#	Kysymys	Erittely	Swagger	Kuinka tarkistaa
1	Todennusotsikko kohteelle `/api/meta/*`	`X-Authorization-Key`	vain `Bearer` ilmoitettu	`curl -i -H "X-Authorization-Key: <token>" ".../api/meta/posts?perPage=1"` — odota `200`, ei `401`
2	Laskurikenttä metavastauksissa	`totalCount`	`total`	Sama pyyntö — lue JSON-juuren avain
3	`author.type` tyyppi ja `reply` tilakoodi	`"meta_user"` / `"owner"`, `202` rungolla	`int [0,1]`, `200` ilman runkoa	`curl -i .../api/meta/comments?perPage=1` plus testivastaus

Väliaikainen ohje:

laskuri — lue total ?? totalCount;
author.type — hyväksyy sekä merkkijonon että kokonaisluvun (0 ↔ meta_user, 1 ↔ owner, yhdistäminen vahvistetaan);
reply — pidä mitä tahansa 2xx onnistuneena, ei vaadi kehoa, ota lopullinen tila source: 13 takaisinsoittosta.

Käyttöönottotiedot

Todennus vaihtelee päätepisteryhmän mukaan — /api/meta/* käyttää numeroa X-Authorization-Key, keskusteluja ja operaattorit käyttävät numeroa Bearer, restapi hyväksyy jommankumman.
Sivutus kirjoitetaan kahdella tavalla — per_page /api/chat/chats, perPage /api/meta/* ja /api/chat/callback-events.
multipart/form-data-kentät ovat PascalCase ja pistemerkintä (Media.File, Media.Type).
Tyhjäkentät jätetään pois takaisinkutsuista — poissa oleva avain tarkoittaa null.
phone on yleensä null Instagramissa. Tunnista asiakas numerolla instagramUser.id / metaUserId ja osta instaAccount.id (suodattimen arvo entityId).
Story.Id takaisinsoittosta voidaan siirtää suoraan takaisin numerolla id / postId Meta API
.
Tarkista operaattorin JWT
expiresAt ennen kuin käytät sitä syvälinkissä tai widgetissä.