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 endpoint uses bot_id authentication instead.

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

This endpoint is authenticated with the bot_id included in the request body. The bot_id must match a registered channel configuration. When a secret is configured, the request must also include valid x-kakao-timestamp and x-kakao-signature headers.

Request body

Field	Type	Required	Description
bot_id	string	Yes	Bot identifier registered in a channel configuration.
user_id	string	Yes	KakaoTalk user ID.
utterance	string	Yes	User’s message text.

Response

Returns a KakaoTalk simpleText response:

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

Errors

Status	Description
400	Invalid JSON body.
403	Invalid or missing bot_id, unknown channel configuration, or invalid webhook signature.
429	Rate limit exceeded (30 requests per 60 seconds per bot_id).

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

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.

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

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