문의

손님 문의 대화를 조회하고 답장, 노트, 종료 처리를 합니다.

문의 목록 조회

GET

https://api.superplace.so

/inbox/v1/conversations

OAuth 2.0

카카오, 네이버, 웹챗, 전화 등 모든 채널의 손님 문의를 돌려줍니다. 우선 표시한 문의가 먼저 나오고, 정렬 기준은 sort로 바꿉니다. q로 이름, 전화번호, 미리보기 글을 검색하고 filter로 상태와 채널을 좁힙니다.

필요 권한: 채팅 기록 보기(inbox:records:read)

MCP 도구: inbox_get_conversations

문의 목록 조회 › query Parameters

page

integer

페이지 번호입니다. 1부터 시작합니다.

perPage

integer

한 페이지에 담을 건수입니다. 생략하면 서버 기본값이 적용됩니다.

start

integer · min: 0

범위 조회의 시작 위치입니다. end와 함께 보내며, page·perPage를 함께 보내면 무시됩니다.

end

integer · min: 0

범위 조회의 끝 위치입니다. 이 값은 포함되지 않습니다. 한 번에 200건까지 조회할 수 있습니다.

sort

string · enum

정렬 기준입니다. lastCustomerAt(손님이 마지막으로 말한 시각)만 지원합니다.

Enum values:

lastCustomerAt

order

string · enum

정렬 방향입니다. asc는 오름차순, desc는 내림차순입니다.

Enum values:

asc

desc

filter

string

조건 JSON입니다. status(OPEN, ASSIGNED, WAITING, CLOSED, MISSED), channel, unreadCount({"gt":0}), missed(true이면 부재중 전화가 남은 문의), priority(HIGH, NORMAL), category(booking, payment, access, product, hours, complaint, inquiry, other), customerPhone, openedAt({"gte":…,"lt":…}), placeId를 쓸 수 있습니다.

q

string

이름, 전화번호, 미리보기 글에서 찾을 검색어입니다.

문의 목록 조회 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean · enum · required

Enum values:

object[] · required

total

integer · int64 · required

문의 정보 수정

PATCH

https://api.superplace.so

/inbox/v1/conversations/{id}

OAuth 2.0

문의를 우선 문의로 표시하거나 해제합니다. 손님 이름과 연락처, 언어도 고칠 수 있고, null을 보내면 지웁니다. placeId를 보내면 같은 조직의 다른 매장으로 옮깁니다. 바꿀 항목이 하나도 없으면 400입니다. 응답은 수정된 문의 한 건입니다.

필요 권한: 채팅 응대(inbox:handle)

MCP 도구: inbox_patch_conversations_id

문의 정보 수정 › path Parameters

id

string · uuid · required

문의 ID입니다. 문의 목록의 id입니다.

문의 정보 수정 › Request Body

priority

string · enum

HIGH이면 우선 문의로 표시하고 NORMAL이면 해제합니다.

Enum values:

HIGH

NORMAL

customerName

string | null · maxLength: 40

손님 이름입니다. 40자 이하입니다. null이면 지웁니다.

customerPhone

string | null

손님 전화번호입니다. null이면 지웁니다.

customerEmail

string | null

손님 이메일입니다. null이면 지웁니다.

customerLang

string | null

손님 언어 코드입니다(예: ko, en). null이면 지웁니다.

placeId

string · uuid

옮길 매장 ID입니다. 같은 조직의 매장이어야 합니다.

문의 정보 수정 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

문의 종료

POST

https://api.superplace.so

/inbox/v1/conversations/{id}/close

OAuth 2.0

손님 요청이 끝난 문의를 종료합니다. farewell을 true로 보내면 손님에게 마무리 인사가 발송됩니다. 응답은 종료된 문의 한 건입니다.

필요 권한: 채팅 응대(inbox:handle)

MCP 도구: inbox_post_conversations_id_close

문의 종료 › path Parameters

id

string · uuid · required

문의 ID입니다.

문의 종료 › Headers

Idempotency-Key

string · uuid · required

요청마다 고유한 문자열입니다. 같은 값으로 다시 보내면 한 번만 처리되고 처음 결과가 돌아옵니다.

문의 종료 › Request Body

farewell

boolean

true이면 종료와 함께 손님에게 마무리 인사를 발송합니다.

문의 종료 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

문의 대화 조회

GET

https://api.superplace.so

/inbox/v1/conversations/{id}/messages

OAuth 2.0

문의 한 건의 메시지를 순서대로 돌려줍니다. 메시지마다 seq(순번), direction(IN은 손님, OUT은 매장), authorType(CUSTOMER, STAFF, NOTE 등), body, createdAt이 있습니다. 번역된 대화는 translatedBody가 함께 담깁니다. seq로 이후 메시지만 가져올 수 있습니다.

필요 권한: 채팅 기록 보기(inbox:records:read)

MCP 도구: inbox_get_conversations_id_messages

문의 대화 조회 › path Parameters

id

string · uuid · required

문의 ID입니다.

문의 대화 조회 › query Parameters

page

integer

페이지 번호입니다. 1부터 시작합니다.

perPage

integer

한 페이지에 담을 건수입니다. 생략하면 서버 기본값이 적용됩니다.

start

integer · min: 0

범위 조회의 시작 위치입니다. end와 함께 보내며, page·perPage를 함께 보내면 무시됩니다.

end

integer · min: 0

범위 조회의 끝 위치입니다. 이 값은 포함되지 않습니다. 한 번에 200건까지 조회할 수 있습니다.

filter

string

조건 JSON입니다. 특정 순번 뒤의 메시지만 보려면 {"seq":{"gt":10}}, 순번을 지정하려면 {"seq":{"in":[3,4]}}를 보냅니다.

문의 대화 조회 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

total

integer

GET/inbox/v1/conversations/{id}/messages

curl https://api.superplace.so/inbox/v1/conversations/:id/messages \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "success": true,
  "data": [
    {
      "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800082",
      "seq": 1,
      "direction": "IN",
      "authorType": "CUSTOMER",
      "body": "오늘 7시 예약 변경하고 싶어요",
      "translationFailed": false,
      "createdAt": "2026-11-03T04:50:00Z"
    },
    {
      "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800083",
      "seq": 2,
      "direction": "OUT",
      "authorType": "STAFF",
      "body": "몇 시로 옮길까요?",
      "translationFailed": false,
      "createdAt": "2026-11-03T04:52:00Z"
    }
  ],
  "total": 2
}

json

application/json

문의 답장 보내기

POST

https://api.superplace.so

/inbox/v1/conversations/{id}/messages

OAuth 2.0

손님에게 문의가 들어온 채널로 답장을 발송합니다. 답장을 보내면 호출한 사람이 그 문의의 담당자가 됩니다. 같은 Idempotency-Key로 다시 보내면 중복 발송하지 않습니다. 성공하면 201과 발송한 메시지가 돌아옵니다.

필요 권한: 채팅 응대(inbox:handle)

MCP 도구: inbox_post_conversations_id_messages

문의 답장 보내기 › path Parameters

id

string · uuid · required

문의 ID입니다.

문의 답장 보내기 › Headers

Idempotency-Key

string · uuid · required

요청마다 고유한 문자열입니다. 같은 값으로 다시 보내면 한 번만 처리되고 처음 결과가 돌아옵니다.

문의 답장 보내기 › Request Body

text

string · maxLength: 2000 · required

손님에게 발송할 글입니다.

문의 답장 보내기 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

POST/inbox/v1/conversations/{id}/messages

curl https://api.superplace.so/inbox/v1/conversations/:id/messages \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "text": "7시 예약을 8시로 변경해 드릴까요?"
}'

Example Request Body

{
  "text": "7시 예약을 8시로 변경해 드릴까요?"
}

json

application/json

Example Responses

{
  "success": true,
  "data": {
    "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800084",
    "seq": 3,
    "direction": "OUT",
    "authorType": "STAFF",
    "body": "7시 예약을 8시로 변경해 드릴까요?",
    "authorUserId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800001",
    "translationFailed": false,
    "createdAt": "2026-11-03T04:55:00Z"
  }
}

json

application/json

문의 노트 남기기

POST

https://api.superplace.so

/inbox/v1/conversations/{id}/notes

OAuth 2.0

직원에게만 보이는 내부 노트를 남깁니다. 손님에게는 발송되지 않습니다. mentions에 직원 ID를 넣으면 그 직원이 언급됩니다.

필요 권한: 채팅 응대(inbox:handle)

MCP 도구: inbox_post_conversations_id_notes

문의 노트 남기기 › path Parameters

id

string · uuid · required

문의 ID입니다.

문의 노트 남기기 › Headers

Idempotency-Key

string · uuid · required

요청마다 고유한 문자열입니다. 같은 값으로 다시 보내면 한 번만 처리되고 처음 결과가 돌아옵니다.

문의 노트 남기기 › Request Body

text

string · maxLength: 2000 · required

노트 내용입니다.

mentions

string[] · maxItems: 20

언급할 직원 ID 목록입니다.

문의 노트 남기기 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

POST/inbox/v1/conversations/{id}/notes

curl https://api.superplace.so/inbox/v1/conversations/:id/notes \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "text": "손님이 8시 변경을 원함. 확인 후 연락 예정."
}'

Example Request Body

{
  "text": "손님이 8시 변경을 원함. 확인 후 연락 예정."
}

json

application/json

Example Responses

{
  "success": true,
  "data": {
    "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800085",
    "seq": 4,
    "direction": "OUT",
    "authorType": "NOTE",
    "body": "손님이 8시 변경을 원함. 확인 후 연락 예정.",
    "authorUserId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800001",
    "createdAt": "2026-11-03T04:56:00Z"
  }
}

json

application/json

지식 문서 목록 조회

GET

https://api.superplace.so

/inbox/v1/kb-docs

OAuth 2.0

AI 응대가 답변의 근거로 삼는 지식 문서를 돌려줍니다. 문서마다 제목, 본문, 사용 여부(enabled)가 있습니다. 매장당 최대 50개입니다.

필요 권한: 채팅 기록 보기(inbox:records:read)

MCP 도구: inbox_get_kb_docs

지식 문서 목록 조회 › query Parameters

filter

string

조직 계정으로 연결한 경우 매장 하나를 고르는 JSON입니다. 예: {"placeId":"01932b1e-4c3a-7f10-9a2b-5d6e7f800010"}. 매장 계정에서는 생략합니다.

지식 문서 목록 조회 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

total

integer

손님 메시지