Help Center 메타 & 인스타그램 API 통합

메타 & 인스타그램 API 통합

SMSBAT ChatHub 플랫폼에서 Instagram 앱을 구축하기 위한 참조: 인증, Instagram Direct 대화, 게시물 및 릴에 대한 댓글, 스토리 답글, 웹후크 및 설문조사.

출처

이 페이지는 내부 Meta Comments API 사양을 라이브 OpenAPI와 병합합니다. https://chatapi.smsbat.com/swagger/v1/swagger.json의 정의 및 https://restapi.smsbat.com/swagger/v1/swagger.json. 두 사람의 의견이 일치하지 않는 곳에서는 차이점은 인라인으로 호출되어 공개 질문 아래에 나열됩니다.

1. 기본 URL

목적	URL
채팅 API + 메타 API	`https://chatapi.smsbat.com`
Swagger UI/OpenAPI	`https://chatapi.smsbat.com/index.html` · `…/swagger/v1/swagger.json`
REST API(조직, 콜백 URL)	`https://restapi.smsbat.com`
REST API 스웨거	`https://restapi.smsbat.com/swagger/v1/swagger.json`
운영자 웹 패널	`https://chat.smsbat.com`

2. 인증

인증 체계는 엔드포인트 그룹에 따라 다릅니다. 이들을 혼동하는 것이 401의 가장 일반적인 원인입니다.

그룹	헤더
`chatapi.smsbat.com/api/meta/*` (게시물, 댓글)	`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` · 기본 인증

X-Authorization-Key의 조직 토큰은 프로필 패널에서 발급됩니다. 회사 및 운영자 JWT는 /api/company/get-token 및 /api/operator/get-token에서 왔습니다.

불일치

chatapi OpenAPI 문서는 단일 보안 체계(Bearer)를 선언하고 이를 적용합니다. 전 세계적으로. X-Authorization-Key는 전혀 선언되지 않았지만 내부 메타는 Comments API 사양에서는 이를 /api/meta/*로 명명합니다. 다음에서 처리할 가능성이 높습니다. Swagger에 반영되지 않는 미들웨어입니다. 배송하기 전에 경험적으로 확인하십시오.

2.1 회사 토큰

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

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

200 OK 기본 토큰 문자열을 반환합니다.

2.2 조직

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

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

2.3 조직 내 운영자

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

운영자 상태: 0 활성, 1 비활성, 2 삭제됨.

2.4 운영자 추가/동기화

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 연산자 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는 JWT를 문자열로 반환합니다.

2.6 운영자 토큰 검증

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
}

유효하지 않은 경우: { "isValid": false, "error": "Invalid token" }.

2.7 운영자 채팅 패널 삽입

<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. 채팅 패널에 대한 딥링크

외부 시스템(CRM, ERP, 웹사이트)은 특정 대화를 열 수 있습니다. https://chat.smsbat.com/. 운영자는 쿼리 매개변수로 전달된 JWT에 의해 승인됩니다.

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>

매개변수	설명
`chat_raw_id`	채팅 ID
`phone`	국제 형식의 전화번호
`from`	브랜드/비즈니스 계정 식별자(`bm_id`)
`source`	채팅 소스 — Instagram의 경우 `7`, §8.1
`token`	채팅에 액세스할 수 있는 유효하고 만료되지 않은 운영자 JWT

잘못된 JWT는 방문자를 운영자 패널의 로그인 화면으로 안내합니다.

4. 인스타그램 다이렉트 대화

4.1 채팅 나열

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

Note

여기의 페이지 매김은 per_page (snake_case)입니다. /api/meta/* 및 여론조사에서 엔드포인트는 perPage(camelCase)입니다. 이것은 오타가 아닙니다. API는 두 가지를 모두 사용합니다.

쿼리 매개변수(모두 선택사항):

매개변수	유형	설명
`source`	`ChatSource`	`7` 결과는 Instagram으로 제한됩니다
`entityId`	`int`	비즈니스 계정 ID입니다. `source` 와 함께만 적용
`instagram_user_id`	`int`	ChatHub의 Instagram 사용자 ID
`facebook_user_id`	`int`	ChatHub의 Facebook 사용자 ID
`page` / `per_page`	`int`	페이지 매김, 기본값 `1` / `20`
`status`	`ChatStatus[]`	채팅 상태, 반복 가능
`search`	`string`	자유 텍스트 검색(이름, 전화번호, …)
`organizationId`	`int`	조직 ID
`operatorId`	`int[]`	할당된 운영자별로 필터링
`date`	`string[]`	두 가지 경계: `?date=…&date=…`
`isChain`	`bool`	이전 채팅의 메시지를 전달하여 채팅을 체인으로 반환
`isUnread`, `starMark`, `isOperator`, `isAIAgent`	`bool`	추가 필터
`phone`, `email`, `contactId`, `clientId`, `tagIds`, `rate`, `sortedBy`	—	기타 필터

200 OK는 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 앱에 중요한 필드는 다음과 같습니다.

필드	의미
`instaAccount`	인스타그램 비즈니스 계정(상점). `id`은 `entityId` 필터 값입니다. `name`은 Meta
`instagramUser`	고객입니다. `name`는 Instagram 핸들이고, `id`은 `instagram_user_id` 필터 값입니다
`metaUserId`	Meta 측의 고객 범위 ID(문자열)
`messSource`	`7` 인스타그램용
`phone`	일반적으로 Instagram의 경우 `null` — 키로 사용하지 마세요

ChatDTO에는 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 및 taggedMessages.

4.2 채팅 메시지

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

200 OK는 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는 메시지가 Instagram 게시물이나 스토리와 관련된 경우 채워집니다. 전달하세요. id / postId로 Meta API로 바로 돌아갑니다. media는 ChatMediaDTO입니다. { name, format, type, uri, raw, length, isUploaded }.

4.3 메시지 보내기(JSON)

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

본문 — 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
  }
}

필드	유형	설명
`textMessage`	`string?`	메시지 텍스트. `media`가 있는 경우 비어 있을 수 있음
`author`	`AuthorMessage?`	`0` 운영자, `1` 클라이언트
`isInternal`	`bool?`	`true` 고객에게 전달되지 않는 내부 메모 표시
`replyToMessageId`	`int?`	회신되는 메시지의 ID
`appGuid`	`uuid?`	추천 GUID
`media`	`MediaDTO?`	`{ name, format, dataBase64, thumbnail, duration, type }`

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

추천 GUID는 다음 경로로 전달될 수도 있습니다. POST /api/chat/{chatId}/{referralGuid}/message (마찬가지로 …/message/v1, …/message/v2).

4.4 파일 또는 비디오 보내기(멀티파트, v2)

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

양식 필드 이름은 점 표기법이 적용된 PascalCase입니다.

textMessage 및 media.file는 자동으로 무시됩니다. 아래의 정확한 이름을 사용하세요.

양식 필드	유형	설명
`TextMessage`	`string`	메시지 텍스트
`Author`	`int`	`0` 운영자, `1` 클라이언트
`IsInternal`	`bool`	내부 메모
`ReplyToMessageId`	`int`	회신되는 메시지
`AppGuid`	`uuid`	추천 GUID
`Media.File`	`binary`	파일 자체
`Media.Name`	`string`	파일 이름
`Media.Format`	`string`	MIME 유형(`video/mp4`, `image/png`, `application/pdf`)
`Media.Type`	`MediaType`	§8.5
`Media.DataBase64`	`string`	`Media.File`의 대안
`Media.Thumbnail`	`string`	Base64 비디오 미리보기 프레임
`Media.Duration`	`double`	비디오 길이(초)

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 채팅 상태 변경

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

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

200 OK는 업데이트된 개체를 에코합니다.

4.6 메시지 상태 업데이트

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

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

4.7 채팅 삭제

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

5. 게시물, 릴 및 스토리

기본 경로: https://chatapi.smsbat.com/api/meta 인증: X-Authorization-Key: <organization token>

5.1 게시물, 릴, 스토리 나열

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

매개변수	유형	필수	설명
`page`	`int`	아니	페이지, 기본값 `1`
`perPage`	`int`	아니	페이지당 항목 수, 기본값 `20`
`id`	`int`	아니	내부 게시물 ID로 필터링
`platform`	`string`	아니	`instagram` 또는 `facebook`
`mediaType`	`string`	아니	`post`, `reel` 또는 `story`. 생략 시 모든 유형

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

불일치 — 카운터 필드 이름

Swagger 스키마 MetaCommentPostListItemDtoPaginationDTO는 **total**을 정의합니다. 는 내부 사양 문서 totalCount. Swagger는 코드에서 생성되므로 total가 진실일 가능성이 더 높습니다. 이것이 해결될 때까지 total ?? totalCount를 구문 분석하세요.

필드	설명
`id`	내부 게시물 ID
`metaId`	메타의 외부 게시물/릴/스토리 ID
`text`	게시물 캡션
`imageUrl`	비순차적 `MetaPost.Guid` 또는 `null`로 키가 지정된 프록시 미디어 URL
`platform`	`facebook` 또는 `instagram`
`mediaType`	`post`, `reel` 또는 `story`
`createdAt`	생성 날짜(플랫폼 날짜 또는 데이터베이스 날짜)
`story`	`mediaType: "story"`에게 만 선물
`story.id`	내부 스토리 ID `post.id`와 같음
`story.metaId`	메타의 외부 스토리 ID
`story.url`	저장된 Story 미디어의 안정적인 프록시 URL입니다. `null` 미디어를 저장할 수 없는 경우

포스트 미디어는 두 가지 경로로 제공됩니다: GET /api/meta/post/media/{id:int} 역방향 호환성 및 GET /api/meta/post/media/{guid:guid}. 새로운 API 응답 및 콜백 항상 GUID 양식을 생성하십시오.

5.2 댓글 나열

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

매개변수	유형	필수	설명
`page`	`int`	아니	페이지, 기본값 `1`
`perPage`	`int`	아니	페이지당 항목 수, 기본값 `20`
`postId`	`int`	아니	게시물 ID로 필터링
`parentCommentId`	`int`	아니	해당 댓글의 하위 댓글(답글)
`platform`	`string`	아니	`facebook` 또는 `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..."
      }
    }
  ]
}

필드	설명
`id`	내부댓글ID
`metaId`	메타의 외부 ID. `null` 전송될 때까지 대기 중인 답변
`text`	댓글 텍스트
`createdAt`	작성일
`platform`	`facebook` 또는 `instagram`
`replyStatus`	`null` 인바운드 사용자 댓글의 경우; `"pending"` / `"sent"` / `"failure"` 답변
`author.type`	`"meta_user"` 외부 사용자, `"owner"` 페이지 소유자
`author.name`	저자 이름
`author.metaUserId`	메타의 범위가 지정된 사용자 ID. `"owner"`를 위한 `null`
`post`	댓글이 속한 게시물, 릴, 스토리
`post.mediaType`	`post`, `reel` 또는 `story`
`post.story`	스토리 참조 `{ id, metaId, url }`, 스토리만
`mediaUrl`	댓글에 첨부된 미디어 또는 `null`
`replyTo`	학부모 댓글 `{ id, metaId, text }`; `null` 최상위

불일치 — `author.type` 유형

내부 사양에는 "meta_user" / "owner" 문자열이 문서화되어 있습니다. 스웨거 유형 MetaCommentAuthorType 열거형 [0, 1]가 포함된 정수입니다. JsonStringEnumConverter 격차를 설명할 수 있지만 실제 응답에 비해 확인되지 않았습니다. 쓰기 둘 다 허용하는 파서.

5.3 댓글에 답글 달기

전달을 위해 응답을 대기열에 넣습니다.

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"

요청 본문: { "text": "Reply text" }

202 Accepted는 GET /api/meta/comments과 같은 모양의 주석 개체를 반환합니다. replyStatus: "pending" 및 metaId: null. 배송 결과는 나중에 source: 13 콜백(§6.4).

불일치 — 응답 코드

Swagger는 본문 없이 200를 선언합니다. 내부 사양에서는 202 Accepted을 선언합니다. 주석을 본문으로 사용합니다. 컨트롤러에 ProducesResponseType가 없을 가능성이 높습니다. 속성을 사용하여 Swagger를 기본값으로 둡니다. 어떤 2xx도 받아들이고 신체에 의존하지 마세요.

6. 웹훅

SMSBAT는 application/json이 포함된 POST 요청을 귀하의 URL로 보내고 HTTP 200이 돌아올 것으로 예상합니다.

Null 필드는 완전히 생략됩니다.

값이 null인 필드는 콜백 본문에 전혀 직렬화되지 않습니다. 에 대한 Facebook이나 Instagram에서 오지 않은 메시지에는 MetaUserId 키가 없습니다. “결석”과 null을 같은 것으로 취급하세요.

6.1 콜백 URL 등록

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

필드	유형	설명
`url`	`string`	귀하의 엔드포인트
`source`	`SendingSourceCallback`	이벤트 유형, §8.2
`headerName` / `headerValue`	`string`	요청에 첨부하는 임의의 인증 헤더(선택 사항)
`channelType`	`ChatSource`	채널. 인스타그램용 `7`. 선택사항
`channelEntityId`	`int`	특정 비즈니스 계정. `channelType` 필요

channelType가 없으면 URL은 모든 채널에서 이벤트를 수신합니다.

Tip

전체 댓글 범위에는 두 가지 등록이 필요합니다. 새 댓글의 경우 source: 12 및 source: 13 회신 상태입니다. 다이렉트 및 스토리 답변을 원하시면 source: 3를 추가하세요. (그리고 모든 채팅 메시지를 원한다면 11).

남은 작업:

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 반환:

[
  {
    "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 새 메시지 및 인스타그램 스토리 답글 (`source: 3`, `11`)

Instagram Story에 대한 사용자의 응답은 이러한 콜백에서 일반 메시지로 도착합니다. 추가 최상위 Story 블록 포함:

{
  "ChatId": 123,
  "MessageId": 456,
  "MessageText": "😍",
  "Username": "Jane Smith",
  "UserId": 789,
  "MetaUserId": "1585775752382460",
  "ShopId": 12,
  "ShopName": "instagram shop name",
  "Author": 0,
  "type_messenger": 7,
  "Story": {
    "Id": 42,
    "MetaId": "18113450675314072",
    "Url": "https://dashboard.smsbat.com/api/meta/post/media/7d124c36-1711-4aa8-b21d-f6dbf8f347ef"
  }
}

필드	설명
`ChatId` / `MessageId`	채팅 및 메시지 식별자
`Author`	`0` 사용자, `1` 운영자
`Username`	Instagram/Facebook 표시 이름 또는 핸들
`UserId`	SMSBAT의 내부 숫자 사용자 ID
`MetaUserId`	Meta에서 대화 파트너의 범위 ID입니다. 발신 교환원 메시지에서 이는 여전히 교환원이 아닌 채팅의 메타 사용자를 식별합니다
`ShopId`	인스타그램/페이스북 비즈니스 계정 내부ID
`ShopName`	연결 시 Meta로부터 받은 비즈니스 계정 이름
`MessageText`	메시지 텍스트
`MessageMedia`	메시지가 미디어인 경우 미디어 URL
`type_messenger`	출처, 인스타그램용 `7`
`operator_name`	`Author = 1`일 때 연산자 이름
`Story`	수신 스토리 답글에만 만 표시
`Story.Id`	내부 스토리(`MetaPost`) ID — Meta API에서 `id` / `postId`로 직접 사용 가능
`Story.MetaId`	메타의 외부 스토리 ID
`Story.Url`	저장된 Story 미디어의 안정적인 프록시 URL입니다. 미디어를 저장할 수 없을 때 부재 — `Story` 블록과 메시지는 계속 전달됩니다

`Author`은 Chat API에 비해 반전되었습니다.

ChatMessageDTO.author에서 0는 운영자를 의미하고 1은 클라이언트를 의미합니다. 이 콜백에서는 반대의 경우: 0는 사용자이고 1는 운영자입니다. 매핑을 공유하지 마십시오.

6.3 새 댓글 (`source: 12`)

메타 사용자가 Facebook 게시물이나 Instagram 게시물/릴에 댓글을 달 때 실행됩니다.

Note

인스타그램 스토리 답글은 source: 12로는 전달되지 않습니다. 정상적으로 도착합니다. source: 3 및/또는 Story 블록이 있는 11의 인바운드 메시지 — §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 댓글 답글 상태 (`source: 13`)

성공이든 실패든 응답을 전달하려고 시도한 후에 발생합니다.

{
  "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 공유 댓글 콜백 필드

두 댓글 콜백 모두 하나의 몸체 모양을 공유하며 type만 다릅니다.

필드	설명
`type`	`"new_comment"` 또는 `"comment_status"`
`platform`	`"facebook"` 또는 `"instagram"`
`comment.id`	내부댓글ID
`comment.metaId`	메타의 외부 ID; `null` 전송되기 전에 보류 중인 응답
`comment.parentCommentId`	상위 댓글 ID입니다. 최상위 댓글의 경우 부재
`comment.parentMetaId`	외부 상위 댓글 ID입니다. 최상위 수준에 없음
`comment.parentCommentText`	상위 댓글 텍스트입니다. 최상위 수준에 없음
`comment.text`	댓글 텍스트
`comment.createdAt`	작성일
`comment.updatedAt`	마지막 업데이트. 댓글이 편집된 적이 없으면 부재
`comment.replyStatus`	`"pending"` / `"sent"` / `"failure"`. 인바운드 사용자 댓글에 부재
`comment.author.type`	`"meta_user"` 또는 `"owner"`
`comment.author.name`	저자 이름
`comment.author.metaUserId`	메타의 범위가 지정된 작성자 ID입니다. `"owner"` 동안 결석
`comment.mediaUrl`	댓글미디어. 없을 때 부재
`post.id`	내부 게시물 ID
`post.metaId`	메타의 외부 게시물/릴/스토리 ID
`post.text`	게시물 텍스트
`post.imageUrl`	게시물 이미지 URL 또는 `null`
`post.createdAt`	게시물 작성일
`post.mediaType`	댓글 콜백에서는 `post` 또는 `reel`

6.6 새로운 채팅 (`source: 7`)

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

6.7 메시지 및 채팅 상태 변경 (`source: 6` / `5`)

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

6.8 메시지 수정 또는 삭제됨 (`source: 9`)

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

6.9 입력 표시 (`source: 8`)

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

7. 이벤트 폴링

인바운드 HTTP를 허용할 수 없는 환경의 경우.

7.1 이벤트 가져오기

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

매개변수	설명
`organizationId`	선택 과목. 생략된 경우 토큰에서 가져옴
`page` / `perPage`	페이지 매김, 기본값 `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"
    }
  ]
}

모든 이벤트에는 event_guid, timestamp, organization_id 및 callback_type가 포함됩니다. §8.2의 source 값과 일치하는 문자열입니다. 나머지 필드는 해당 필드와 일치합니다. §6의 웹훅.

7.2 처리된 이벤트 확인

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 }

이미 제거된 이벤트는 deleted에 포함되지 않습니다. 주문과 재시도는 귀하의 몫입니다 쪽의 책임.

7.3 권장 루프

일정에 따라 GET /api/chat/callback-events 설문조사를 실시합니다.
서비스의 이벤트를 처리합니다.
처리된 event_guid 목록을 /callback-events/processed로 보냅니다.
반복합니다.

8. 열거형 참조

8.1 `ChatSource` — 채널(0–9)

코드	채널
0	바이버
1	바이버봇
2	텔레그램봇
3	왓츠앱
4	위젯
5	로제트카
6	페이스북
7	인스타그램
8	프롬
9	올스

8.2 `SendingSourceCallback` — 콜백 이벤트 유형(0–13)

코드	이벤트
3	`Chat` — 스토리 답글을 포함한 새로운 채팅 메시지
5	채팅 상태가 변경됨
6	메시지 상태가 변경됨
7	새 채팅이 생성되었습니다
8	입력 표시
9	메시지가 업데이트되거나 삭제되었습니다
11	`AnyChatMessage` — 모든 채팅 메시지
12	`MetaNewComment` — 새로운 인스타그램/페이스북 댓글
13	`MetaCommentStatus` — 댓글 답변 전달 상태

열거형의 범위는 0–13; Instagram 통합에는 나머지 값이 필요하지 않습니다.

8.3 `ChatStatus` (0–4)

0 신규, 1 공개, 2 대기 중, 3 일시중지 중, 4 종료

8.4 `MessageStatus` (0–11)

코드	이름
0	신규
1	성공
2	거부됨
3	읽기
4	알 수 없음
5	처리
6	전달됨
7	BLOCKED_BY_USER
8	USER_NOT_FOUND

열거형의 범위는 0–11입니다. 9, 10 및 11 값이 API에 존재하지만 아직 문서화되지 않았습니다. UNKNOWN로 취급하세요.

8.5 `MediaType` (1–10)

1 사진, 2 파일, 3 오디오, 4 비디오, 5 스티커, 6 스티커 애니메이션, 7 스티커동영상, 8 애니메이션, 9 음성, 10 동영상노트

8.6 `AuthorMessage` — Chat API의 작성자(0–4)

0 운영자, 1 클라이언트, 2 봇, 3 Viber계정

열거형의 범위는 0–4; 값 4은 문서화되지 않았습니다. “새 메시지” 콜백은 반대 매핑 — §6.2를 참조하세요.

8.7 `ChatMessageType` (0–2)

0 텍스트, 1 사진, 2 파일

8.8 댓글 `replyStatus`

null 인바운드 사용자 댓글, "pending" 답변이 대기 중, "sent" 전달됨, "failure" 배송에 실패했습니다.

공개 질문

내부 사양과 코드 생성 Swagger가 일치하지 않는 세 가지 지점이 있습니다. 하나 실제 토큰을 요청하면 모든 것이 해결됩니다. 그때까지는 클라이언트를 방어적으로 작성하십시오.

#	질문	사양	스웨거	확인 방법
1	`/api/meta/*`에 대한 인증 헤더	`X-Authorization-Key`	`Bearer`만 선언됨	`curl -i -H "X-Authorization-Key: <token>" ".../api/meta/posts?perPage=1"` — `200`이 아닌 `401`을 기대하세요
2	메타 응답의 카운터 필드	`totalCount`	`total`	동일한 요청 - 루트 JSON 키 읽기
3	`author.type` 유형 및 `reply` 상태 코드	`"meta_user"` / `"owner"`, `202` 본체 포함	`int [0,1]`, `200` 몸체 없음	`curl -i .../api/meta/comments?perPage=1` 및 테스트 답변

임시 지침:

카운터 — 읽기 total ?? totalCount;
author.type — 문자열과 정수를 모두 허용합니다(0 ← meta_user, 1 owner, 매핑 확인 필요)
reply — 모든 2xx를 성공으로 처리하고 본문이 필요하지 않으며 source: 13 콜백에서 최종 상태를 가져옵니다.

구현 참고사항

인증은 엔드포인트 그룹에 따라 다릅니다 — /api/meta/*는 X-Authorization-Key, 채팅 및 연산자는 Bearer, restapi 중 하나를 사용합니다.
페이지 매김은 두 가지 방식으로 철자됩니다 — per_page on /api/chat/chats, perPage on /api/meta/* 및 /api/chat/callback-events.
multipart/form-data 필드는 점 표기법을 사용한 PascalCase입니다(Media.File, Media.Type).
콜백에서 Null 필드는 생략됩니다 — 키가 없으면 null를 의미합니다.
Instagram에서는 일반적으로 phone가 null입니다. instagramUser.id로 고객을 식별하세요. / metaUserId 및 상점은 instaAccount.id(entityId 필터 값)로 표시됩니다.
콜백의 Story.Id는 id / postId로 Meta API에 바로 다시 전달될 수 있습니다.
딥링크나 위젯에서 사용하기 전에 JWT 연산자의 expiresAt를 확인하세요.