チャンネル

Show: All versions v2 only

チャンネルAPIを使用すると、SchiftをKakaoTalkなどのメッセージングプラットフォームに接続できます。ユーザーメッセージをウェブフックで受信し、バケットに対してRAGクエリを実行し、ユーザーに通知を送信できます。

Note: チャンネル設定を変更または一覧表示するすべてのエンドポイントは、Authorization: Bearer $SCHIFT_API_KEYによるAPIキー認証が必要です。Kakaoのウェブフックエンドポイントはbot_id認証を使用します。

POST /v1/channels/kakao/webhook

Kakao i Open Builderスキルコールバックを介してKakaoTalkからユーザーメッセージを受信します。このエンドポイントはRAGを実行し、ユーザーのメッセージを埋め込み、チャンネル設定にリンクされたバケットを検索し、結果をKakaoTalkのsimpleText形式で返します。

Authentication

このエンドポイントは、リクエストボディに含まれるbot_idで認証されます。bot_idは登録されたチャンネル設定と一致する必要があります。secretが設定されている場合、リクエストには有効なx-kakao-timestampとx-kakao-signatureヘッダーも含める必要があります。

Request body

Field	Type	Required	Description
bot_id	string	Yes	チャンネル設定に登録されたボット識別子。
user_id	string	Yes	KakaoTalkユーザーID。
utterance	string	Yes	ユーザーのメッセージテキスト。

Response

KakaoTalkのsimpleTextレスポンスを返します:

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

Errors

Status	Description
400	無効なJSONボディ。
403	無効または欠落したbot_id、不明なチャンネル設定、または無効なウェブフック署名。
429	レート制限超過（bot_idごとに60秒間に30リクエスト）。

Example

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": "법인세 계산 방법"
  }'

Response:

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

POST /v1/channels/kakao/send

ユーザーにアリムトーク（KakaoTalk通知）を送信します。APIキー認証が必要です。

Request body

Field	Type	Required	Description
channel_config_id	string	Yes	POST /v1/channels/configsからのチャンネル設定ID。
phone	string	Yes	受取人の電話番号。
template_code	string	Yes	KakaoビジネスダッシュボードからのKakaoテンプレートコード。
template_args	object	No	テンプレート変数としてのキーと値の文字列。
user_id	string	No	KakaoTalkユーザーID（直接メッセージングのためのphoneの代替）。
message	string	No	テンプレートを使用しない場合の自由形式のメッセージテキスト。

Response

Field	Type	Description
status	string	成功時は"sent"。
result	object	Kakao APIのレスポンス詳細、message_idとsent_atを含む。

Errors

Status	Description
400	template_codeまたはphoneが欠落しています。
404	チャンネル設定が見つかりません。

Example

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

Response:

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

POST /v1/channels/configs

プロバイダー固有の資格情報と設定を保存する新しいチャンネル設定を登録します。

Request body

Field	Type	Required	Description
name	string	Yes	設定の表示名。
provider	string	Yes	プロバイダータイプ、例: "kakao", "slack", "discord"。
config	object	Yes	プロバイダー固有の設定オブジェクト。

Kakaoの場合、configオブジェクトには以下を含める必要があります:

Field	Type	Required	Description
rest_api_key	string	Yes	Kakao REST APIキー。
channel_id	string	Yes	KakaoチャンネルID。
admin_key	string	No	Kakao管理キー。
collection	string	Yes	RAGクエリに使用されるバケット名。
bot_id	string	Yes	ウェブフック認証に使用されるボットID。

Response

Field	Type	Description
id	string	一意の設定ID。
name	string	設定名。
provider	string	プロバイダータイプ。

Errors

Status	Description
400	無効または欠落した必須フィールド。
401	欠落または無効なAPIキー。

Example

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

Response:

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

GET /v1/channels/configs

組織のすべてのチャンネル設定を取得します。APIシークレットはレスポンスでマスクされます。

Response

設定オブジェクトの配列を返します:

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

Errors

Status	Description
401	欠落または無効なAPIキー。

Example

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

DELETE /v1/channels/configs/{config_id}

チャンネル設定を永久に削除します。

Path parameters

Parameter	Type	Description
config_id	string	一意の設定ID。

Response

Field	Type	Description
deleted	boolean	削除が成功した場合はtrue。

Errors

Status	Description
401	欠落または無効なAPIキー。
404	設定が見つかりません。

Example

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

Response:

{
  "deleted": true
}

API versions

このドキュメントのすべてのエンドポイントはv1チャンネルAPIの一部です。現在、v2バージョンはありません。

See also

• バケット