채널

Show:

Channels API(채널 API)를 사용하면 카카오톡(KakaoTalk) 같은 메시징 플랫폼과 Schift를 연결할 수 있습니다. webhook(웹훅)으로 사용자 메시지를 수신하고, bucket(버킷)에 대해 RAG 검색을 실행한 뒤, 사용자에게 알림을 다시 보낼 수 있습니다.

참고: 채널 설정을 변경하거나 목록으로 조회하는 모든 엔드포인트는 Authorization: Bearer $SCHIFT_API_KEY 헤더를 통한 API key authentication(API 키 인증)이 필요합니다. 카카오 webhook(웹훅) 엔드포인트는 대신 bot_id 인증을 사용합니다.

POST /v1/channels/kakao/webhook

카카오 i 오픈빌더(Kakao i Open Builder) 스킬 콜백을 통해 KakaoTalk 사용자 메시지를 수신합니다. 이 엔드포인트는 RAG를 수행합니다: 사용자 메시지를 임베딩하고, 채널 설정에 연결된 bucket(버킷)을 검색한 후, 결과를 KakaoTalk simpleText 형식으로 반환합니다.

인증

이 엔드포인트는 요청 본문에 포함된 bot_id로 인증됩니다. bot_id는 등록된 channel configuration(채널 설정)과 일치해야 합니다. secret이 설정된 경우 요청에 유효한 x-kakao-timestamp 및 x-kakao-signature 헤더도 포함되어야 합니다.

요청 본문

필드	타입	필수	설명
`bot_id`	string	Yes	채널 설정에 등록된 봇 식별자입니다.
`user_id`	string	Yes	KakaoTalk 사용자 ID입니다.
`utterance`	string	Yes	사용자 메시지 텍스트입니다.

응답

KakaoTalk simpleText 응답을 반환합니다:

{
  "version": "2.0",
  "template": {
    "outputs": [
      {
        "simpleText": {
          "text": "Search results..."
        }
      }
    ]
  }
}

오류

상태	설명
`400`	잘못된 JSON 본문입니다.
`403`	잘못되거나 누락된 `bot_id`, 알 수 없는 채널 설정, 또는 잘못된 웹훅 서명입니다.
`429`	rate limit(속도 제한)을 초과했습니다(`bot_id`당 60초에 30회).

예제

curl -X POST ${API_BASE_URL:-https://api.example.com}/v1/channels/kakao/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "bot-abc123",
    "user_id": "user-xyz789",
    "utterance": "법인세 계산 방법"
  }'

응답:

{
  "version": "2.0",
  "template": {
    "outputs": [
      {
        "simpleText": {
          "text": "1. (score: 0.92)\n법인세는 기업의 순이익에 대해 부과되는 세금입니다.\n\n2. (score: 0.88)\n기본세율은 정상기업 기준 22%입니다."
        }
      }
    ]
  }
}

POST /v1/channels/kakao/send

사용자에게 alimtalk(알림톡)을 보냅니다. API 키 인증이 필요합니다.

요청 본문

필드	타입	필수	설명
`channel_config_id`	string	Yes	`POST /v1/channels/configs`에서 받은 채널 설정 ID입니다.
`phone`	string	Yes	수신자 전화번호입니다.
`template_code`	string	Yes	카카오 비즈니스 대시보드의 Kakao template code(카카오 템플릿 코드)입니다.
`template_args`	object	No	템플릿 변수로 구성된 키-값 문자열입니다.
`user_id`	string	No	KakaoTalk 사용자 ID입니다(직접 메시지 전송 시 `phone` 대안).
`message`	string	No	템플릿을 사용하지 않을 때의 자유 메시지 텍스트입니다.

응답

필드	타입	설명
`status`	string	성공 시 `"sent"`입니다.
`result`	object	`message_id`와 `sent_at`을 포함한 Kakao API 응답 상세 정보입니다.

오류

상태	설명
`400`	`template_code` 또는 `phone`이 누락되었습니다.
`404`	채널 설정을 찾을 수 없습니다.

예제

curl -X POST ${API_BASE_URL:-https://api.example.com}/v1/channels/kakao/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "channel_config_id": "config-abc123",
    "phone": "01012345678",
    "template_code": "template_001",
    "template_args": {
      "product_name": "Schift API",
      "discount_percent": "20%"
    }
  }'

응답:

{
  "status": "sent",
  "result": {
    "message_id": "msg-abc123",
    "sent_at": 1609459200000
  }
}

POST /v1/channels/configs

새로운 channel configuration(채널 설정)을 등록합니다. 이 설정은 provider(제공자)별 credentials(인증 정보)와 설정 값을 저장합니다.

요청 본문

필드	타입	필수	설명
`name`	string	Yes	설정의 표시 이름입니다.
`provider`	string	Yes	제공자 유형입니다. 예: `"kakao"`, `"slack"`, `"discord"`.
`config`	object	Yes	제공자별 설정 객체입니다.

카카오의 경우 config 객체는 다음을 포함해야 합니다:

필드	타입	필수	설명
`rest_api_key`	string	Yes	카카오 REST API 키입니다.
`channel_id`	string	Yes	카카오 채널 ID입니다.
`admin_key`	string	No	카카오 admin key(관리자 키)입니다.
`collection`	string	Yes	RAG 검색에 사용할 bucket name(버킷 이름)입니다.
`bot_id`	string	Yes	webhook(웹훅) 인증에 사용할 봇 ID입니다.

응답

필드	타입	설명
`id`	string	고유한 설정 ID입니다.
`name`	string	설정 이름입니다.
`provider`	string	제공자 유형입니다.

오류

상태	설명
`400`	필수 필드가 잘못되었거나 누락되었습니다.
`401`	API 키가 누락되었거나 잘못되었습니다.

예제

curl -X POST ${API_BASE_URL:-https://api.example.com}/v1/channels/configs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "name": "Legal RAG Bot",
    "provider": "kakao",
    "config": {
      "rest_api_key": "xxxxxxxxxxxxxxxx",
      "channel_id": "channel-123",
      "bot_id": "bot-abc123",
      "collection": "legal-docs"
    }
  }'

응답:

{
  "id": "config-abc123",
  "name": "Legal RAG Bot",
  "provider": "kakao"
}

GET /v1/channels/configs

조직의 모든 채널 설정을 조회합니다. 응답에서 API secret(시크릿) 값은 마스킹됩니다.

응답

설정 객체 배열을 반환합니다:

[
  {
    "id": "config-abc123",
    "name": "Legal RAG Bot",
    "provider": "kakao",
    "config": {
      "rest_api_key": "xxxxxx...xxxx",
      "channel_id": "channel-123",
      "collection": "legal-docs"
    }
  }
]

오류

상태	설명
`401`	API 키가 누락되었거나 잘못되었습니다.

예제

curl ${API_BASE_URL:-https://api.example.com}/v1/channels/configs \
  -H "Authorization: Bearer $SCHIFT_API_KEY"

DELETE /v1/channels/configs/{config_id}

채널 설정을 영구적으로 삭제합니다.

경로 매개변수

Parameter	Type	Description
`config_id`	string	고유한 설정 ID입니다.

응답

필드	타입	설명
`deleted`	boolean	삭제에 성공하면 `true`입니다.

오류

상태	설명
`401`	API 키가 누락되었거나 잘못되었습니다.
`404`	설정을 찾을 수 없습니다.

예제

curl -X DELETE ${API_BASE_URL:-https://api.example.com}/v1/channels/configs/config-abc123 \
  -H "Authorization: Bearer $SCHIFT_API_KEY"

응답:

{
  "deleted": true
}

API 버전

이 문서의 모든 엔드포인트는 v1 Channels API(채널 API)의 일부입니다. 현재 v2 버전은 없습니다.

참고

Buckets(버킷)