Channels

Show: All versions v2 only

The Channels API lets you connect Schift to messaging platforms such as KakaoTalk. You can receive user messages via webhook, run RAG queries against a bucket, and send notifications back to users.

Note: All endpoints that mutate or list channel configurations require API key authentication via Authorization: Bearer $SCHIFT_API_KEY. The Kakao webhook instead matches the top-level bot.id to a channel configuration and checks the static x-api-key header against that configuration’s secret.

POST /v1/channels/kakao/webhook

Receive a user message from KakaoTalk via a Kakao i Open Builder skill callback. This endpoint performs RAG: it embeds the user’s message, searches the bucket linked to the channel configuration, and returns the results in KakaoTalk simpleText format.

Authentication

Set up the webhook with the same static value in Schift and Kakao Open Builder:

1. Register the Kakao channel configuration with the Open Builder bot ID in bot_id and a private random value in secret.
2. In Kakao Open Builder, open the skill and add an x-api-key header whose value exactly matches secret.
3. After you add or change this header, deploy the bot again. Saving the skill alone does not apply the header to live requests.

Header	Description
x-api-key	Static secret configured on the Open Builder skill. It must exactly match the channel configuration’s secret.

A missing header, an unconfigured secret, or a mismatched value returns 403 Invalid webhook API key.

Request body

Field	Type	Required	Description
bot.id	string	Yes	Top-level Open Builder bot identifier registered as bot_id in the channel configuration.
userRequest.user.id	string	Yes	KakaoTalk user identifier scoped to the bot.
userRequest.utterance	string	Yes	User’s message text.
intent	object	No	Matched Open Builder block information.
action	object	No	Skill action and extracted parameters.

Response

Returns a KakaoTalk simpleText response:

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

Errors

Status	Description
400	Invalid JSON body.
403	Missing or unknown bot.id, missing channel secret, or missing/mismatched x-api-key.

Rate-limited requests (more than 30 requests per 60 seconds per bot_id) receive a 200 KakaoTalk-format message asking the user to retry later.

Example

curl -X POST https://api.schift.io/v1/channels/kakao/webhook \
  -H "Content-Type: application/json" \
  -H "x-api-key: $KAKAO_WEBHOOK_SECRET" \
  -d '{
    "bot": {
      "id": "bot-abc123",
      "name": "Legal RAG Bot"
    },
    "userRequest": {
      "block": {
        "id": "block-abc123",
        "name": "법인세 질문"
      },
      "user": {
        "id": "user-xyz789",
        "type": "botUserKey"
      },
      "utterance": "법인세 계산 방법",
      "lang": "ko",
      "timezone": "Asia/Seoul"
    },
    "intent": {
      "id": "intent-abc123",
      "name": "문서 검색"
    },
    "action": {
      "id": "action-abc123",
      "name": "Schift 검색",
      "params": {}
    }
  }'

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

Send an alimtalk (KakaoTalk notification) to a user. Requires API key authentication.

Request body

Field	Type	Required	Description
channel_config_id	string	Yes	Channel configuration ID from POST /v1/channels/configs.
phone	string	Yes	Recipient’s phone number.
template_code	string	Yes	Kakao template code from the Kakao Business dashboard.
template_args	object	No	Template variables as key-value strings.
user_id	string	No	KakaoTalk user ID (alternative to phone for direct messaging).
message	string	No	Free-form message text when not using a template.

Response

Field	Type	Description
status	string	"sent" on success.
result	object	Kakao API response details, including message_id and sent_at.

Errors

Status	Description
400	Missing template_code or phone.
404	Channel configuration not found.

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

Register a new channel configuration that stores provider-specific credentials and settings.

Request body

Field	Type	Required	Description
name	string	Yes	Display name for the configuration.
provider	string	Yes	Provider type, such as "kakao", "slack", or "discord".
config	object	Yes	Provider-specific configuration object.

For Kakao, the config object should contain:

Field	Type	Required	Description
rest_api_key	string	Yes	Kakao REST API key.
channel_id	string	Yes	Kakao channel ID.
admin_key	string	No	Kakao admin key.
collection	string	Yes	Bucket name used for RAG queries.
bot_id	string	Yes	Bot ID used for webhook authentication.
secret	string	Yes	Private static value that the Open Builder skill sends in x-api-key. Webhook calls without an exact match are rejected with 403.

Response

Field	Type	Description
id	string	Unique configuration ID.
name	string	Configuration name.
provider	string	Provider type.

Errors

Status	Description
400	Invalid or missing required fields.
401	Missing or invalid API key.

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",
      "secret": "kakao_skill_xxxxxxxxxxxxxxxx"
    }
  }'

Response:

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

GET /v1/channels/configs

Retrieve all channel configurations for your organization. API secrets are masked in the response.

Response

Returns an array of configuration objects:

[
  {
    "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	Missing or invalid API key.

Example

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

DELETE /v1/channels/configs/{config_id}

Remove a channel configuration permanently.

Path parameters

Parameter	Type	Description
config_id	string	Unique configuration ID.

Response

Field	Type	Description
deleted	boolean	true if deletion succeeded.

Errors

Status	Description
401	Missing or invalid API key.
404	Configuration not found.

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

All endpoints in this document are part of the v1 Channels API. There is no v2 version at this time.

See also

• Buckets