Slack Block Kit Builder 사용법: 템플릿, 미리 보기, 페이로드
Slack Block Kit Builder(app.slack.com/block-kit-builder)에서는 템플릿을 고르고 블록을 더해 Desktop과 Mobile로 미리 본 뒤, 웹후크나 chat.postMessage용 JSON을 복사합니다. 지금 빌더의 사용법, 실제로 작동하는 배포 알림 예시, 보내는 방법을 정리했습니다.
On this page
Slack의 Block Kit Builder는 Slack 메시지용 JSON을 눈으로 보면서 만드는 무료 편집기로, 주소는 app.slack.com/block-kit-builder 입니다. Slack에 로그인한 상태로 열고, Templates 탭에서 템플릿을 고르거나 Builder 탭을 연 뒤 왼쪽 패널에서 블록을 추가합니다. 가운데 열에 메시지 모양이, 오른쪽 열에 JSON이 나옵니다. 모양이 괜찮으면 Copy Payload 를 누르고, 그 JSON을 수신 웹후크(Incoming Webhook)나 chat.postMessage로 보냅니다. 앱도 유료 플랜도 필요 없습니다.
9월 28일에 지금의 빌더를 처음부터 끝까지 써 보고, 10월 4일에는 깨진 페이로드 16개를 빌더에서 시험했습니다. 아래 스크린샷은 그때 찍은 것입니다. 저희는 무료 Slack 도구도 만드는데, 마크다운을 Slack 형식으로 바꾸는 도구의 결과는 section 블록에 그대로 넣을 수 있습니다.
Block Kit Builder로 할 수 있는 일
Block Kit은 앱 메시지, 모달, App Home 탭을 위한 Slack의 JSON 형식입니다. 진행률 표시줄 블록은 없어서 Slack 진행률 표시줄은 앱이 chat.update로 다시 그리는 텍스트입니다. 메시지는 블록의 목록입니다. 헤더, 텍스트 섹션, 이미지, 버튼, 구분선, 그리고 표와 카드 같은 새 블록이 있습니다. 에이전트가 쓰는 plan과 task card 블록은 task card 테스트에서 각각 받는 상태와 표시 모습을 확인했습니다. 에이전트가 답하는 동안 뜨는 "is working..." 줄은 블록이 아니라 별도 API 호출로 띄우며, assistant.threads.setStatus와 agents.sessions.setStatus 비교에서 시험했습니다. 빌더는 이 JSON을 눈으로 보며 고치는 도구입니다. 채널에 메시지를 보내는 것은 빌더가 아니라 웹후크나 앱입니다. 또 한 메시지의 두 줄 사이에 그림을 넣는 방법은 이것뿐이고, 일반 메시지 입력란으로는 할 수 없습니다. Slack 인라인 이미지 테스트(영어)에서 확인했습니다. 텍스트 대신 미디어를 보여 주는 블록이 두 가지 있습니다. 동영상 블록은 YouTube 임베드나 앱이 등록한 도메인의 플레이어를 재생하고, 파일 블록은 원격 파일이나 업로드한 파일의 카드를 보여 줍니다.
Slack Block Kit Builder 사용법
- 빌더를 엽니다.
app.slack.com/block-kit-builder로 갑니다. 워크스페이스가 여러 개라면 오른쪽 위 메뉴에서 고릅니다. - 템플릿에서 시작합니다. Templates 탭에는 Alerts, Approval, Notification, Onboarding, Poll, Rich Markdown 같은 묶음이 있습니다. 하나를 누르면 빌더에서 열립니다.
- 블록을 추가하거나 바꿉니다. Builder 탭의 왼쪽 패널에 블록 종류가 있습니다. Agents, Markdown, Section, Actions, Condition, Input, Structure, Rich Text, Image, Card and Carousel, Callout, Table, Data Visualization, Container, Reference입니다. 누르면 추가됩니다. 오른쪽 Payload 패널에 직접 써도 되고, 고치는 대로 미리 보기가 바뀝니다.
- 표시할 곳을 고릅니다. 미리 보기 위의 첫 번째 메뉴에서 Message Preview, Attachment Preview, Modal Preview, App Home Preview 를 바꿉니다. 모달에서 되는 블록이 메시지에서는 안 될 수 있고, 빌더가 이를 보여 줍니다. 긴 글은 두 메시지 형식에서 다르게 처리됩니다. 더 보기 테스트(영어)에서 Slack은 attachment를 5줄 뒤 "Show more" 뒤로 접었고 블록은 전부 보여 줬습니다. attachment의 색 띠는 attachment 색 테스트에 Slack이 남기는
color값과 버리는 값을 정리했습니다. - Desktop과 Mobile을 확인합니다. 두 번째 메뉴로 미리 보기를 Desktop 과 Mobile 사이에서 바꿉니다. 긴 버튼 줄과 넓은 이미지는 휴대폰에서 다르게 보입니다.
- 버튼을 시험합니다. 미리 보기에서 버튼을 누르거나 메뉴 항목을 고른 뒤 Actions Preview 탭을 엽니다. 앱이 받을
block_actions페이로드가 나옵니다. 버튼 스타일 세 가지와 다른 색을 넣었을 때의 오류는 버튼 스타일 테스트에 있습니다. 선택 메뉴는external_select옵션 처리에 쓸 수 있는 시간까지 선택 메뉴 테스트를, 실제 클릭이 보내는 페이로드와response_url을 몇 번 쓸 수 있는지는 Slack 인터랙티브 페이로드 테스트를 보세요. 앱을 내 노트북에서 돌리면서 클릭을 받으려면 터널이나 Socket Mode가 필요합니다. ngrok, Cloudflare 터널, Socket Mode를 비교했습니다. - JSON을 복사합니다. Copy Payload(JSON 위의 복사 아이콘)를 누릅니다. 휴지통 아이콘인 Clear Blocks 는 캔버스를 비웁니다.

예시: 버튼이 있는 배포 알림
빌더에서 이 메시지를 만들었습니다. 헤더, mrkdwn 텍스트와 링크가 있는 섹션, context 줄, 버튼 두 개가 있습니다.
{
"blocks": [
{
"type": "header",
"text": {
"type": "plain_text",
"text": "Deploy finished"
}
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*api-server* v2.14.0 is live on *production*.\nTook _4 min 12 s_. <https://slack.green|View the release notes>"
}
},
{
"type": "context",
"elements": [
{
"type": "mrkdwn",
"text": "Triggered by the nightly pipeline"
}
]
},
{
"type": "actions",
"elements": [
{
"type": "button",
"text": {
"type": "plain_text",
"text": "Open dashboard"
},
"url": "https://slack.green",
"action_id": "open_dashboard"
},
{
"type": "button",
"style": "danger",
"text": {
"type": "plain_text",
"text": "Roll back"
},
"value": "rollback_v2140",
"action_id": "rollback"
}
]
}
]
}
미리 보기에서 Roll back 을 누르고 Actions Preview 를 열자, 앱이 받는 페이로드에 "action_id": "rollback", "value": "rollback_v2140", "style": "danger"가 들어 있었습니다.
url이 있는 버튼은 그 링크를 엽니다. value만 있는 버튼의 클릭을 받으려면 인터랙티브 기능을 켠 앱이 필요하고, 수신 웹후크만으로는 처리할 수 없습니다. 그 앱이 ack()를 호출하지 않으면 Slack은 버튼 옆에 경고 삼각형을 띄웁니다. Bolt 오류 처리 테스트에서 시험한 경우 중 하나입니다. 버튼을 늘어놓는 대신 "..." 버튼 뒤에 동작을 5개까지 넣으려면 오버플로 메뉴를 쓰세요.
웹후크로 페이로드 보내기
수신 웹후크도 같은 JSON을 받습니다. 맨 바깥에 text도 넣으세요. 블록이 있는 메시지에서 Slack은 이 값을 알림과 화면 낭독기에 씁니다.
curl -X POST -H "Content-Type: application/json" \
-d '{"text": "Deploy finished: api-server v2.14.0",
"blocks": [{"type": "section", "text": {"type": "mrkdwn",
"text": "*api-server* v2.14.0 is live on *production*."}}]}' \
"$SLACK_WEBHOOK_URL"
여기 있는 blocks 배열 자리에 Copy Payload 로 복사한 배열을 통째로 넣습니다. 웹후크 준비는 Slack 웹후크 만드는 법에, 다른 요청 형태와 오류 코드는 Slack 웹후크 curl 예시에 있습니다. 봇 토큰을 쓴다면 같은 본문에 channel을 더해 chat.postMessage로 보냅니다. Slack이 invalid_blocks를 돌려주면 invalid_blocks 테스트에 한도별로 돌아오는 오류 문구를 정리해 두었습니다.
Slack에서 다시는 '자리 비움'으로 표시되지 마세요
클라우드 기반. 다운로드 불필요. 노트북이 꺼져 있어도 24시간 작동.
Block Kit Builder가 잡지 못하는 오류
10월 4일에 페이로드 16개를 빌더에서 열었습니다. 모두 Slack API에 이미 보내 본 경우였고, 빌더의 경고와 Slack의 응답을 비교했습니다. 빌더는 action_id와 block_id 중복, 블록 51개, 내려받을 수 없는 이미지 URL, 텍스트도 fields도 없는 섹션, 10개가 넘는 fields를 잡았습니다. 길이 오류일 때 빨간 띠에는 "failed to match all allowed schemas"만 나옵니다. 한도는 그 줄 옆 빨간 표시에 마우스를 올려야 보입니다.
| 페이로드 | Block Kit Builder | Slack API |
|---|---|---|
| 151자 헤더 | 띠: failed to match all allowed schemas. 마우스 올림: must be less than 151 characters | invalid_blocks, must be less than 151 characters |
actions 블록 하나에 같은 action_id | action_id "x" already exists | invalid_blocks |
| 블록 51개 | no more than 50 items allowed | invalid_blocks |
| 12,001자 markdown 블록 | 경고 없음 | msg_too_long(웹후크는 HTTP 500) |
| 12,000자 markdown 블록과 3,000자 섹션 | 경고 없음 | chat.postMessage: msg_blocks_too_long |
빌더는 블록만 보고, 맨 바깥의 text나 웹후크의 응답은 보지 않습니다. 저희 Block Kit 검사기는 Copy Payload 의 JSON을 받아 보내는 방법마다 Slack이 돌려주는 줄을 보여 주고, Open in Block Kit Builder 버튼으로 고친 블록을 빌더에 다시 불러옵니다.
Block Kit Builder 링크 공유하기
빌더는 페이로드를 페이지 주소에 담아 둡니다. # 뒤가 URL 인코딩된 JSON입니다. 주소창을 복사하면 Slack에 로그인한 사람은 누구나 같은 메시지를 봅니다. 이런 링크는 코드로도 만들 수 있습니다.
import json
import urllib.parse
blocks = {"blocks": [{"type": "section", "text": {"type": "mrkdwn", "text": "*Hello* from a link"}}]}
url = "https://app.slack.com/block-kit-builder#" + urllib.parse.quote(json.dumps(blocks, separators=(",", ":")))
print(url)
9월 28일에 이 스크립트가 출력한 링크를 열자 빌더가 메시지를 불러왔습니다.
Block Kit Builder 팁
mrkdwn을 씁니다. *굵게*, _기울임_, <https://example.com|링크 문구>입니다. **굵게**나 [문구](url) 같은 일반 마크다운은 글자 그대로 나옵니다. 규칙과, 일반 마크다운을 읽는 markdown 블록은 Slack Block Kit 마크다운에 있습니다. 갖고 있는 글을 바꾸거나 mrkdwn 문장 하나를 미리 보려면 마크다운을 Slack 형식으로 바꾸는 도구를 쓰세요.<@U0123ABCD>처럼 씁니다. Slack 웹후크에서 사용자 멘션하는 법을 보세요.<!date^1790553600^{date_short} at {time}|fallback>처럼 씁니다. Slack 타임스탬프 생성기가 이 문자열을 만들어 줍니다.자주 묻는 질문
Slack Block Kit Builder는 무료인가요?
네. 열려면 Slack 계정이 필요하지만 앱도 유료 플랜도 필요 없습니다.
Block Kit Builder로 채널에 메시지를 보낼 수 있나요?
아니요. JSON을 만들고 미리 볼 뿐입니다. 보내는 것은 웹후크, chat.postMessage, 워크플로입니다. C#에서는 SlackNet으로 같은 블록을 타입이 있는 클래스로 만들 수 있습니다. C# Slack API 테스트를 보세요.
Block Kit Builder에서 버튼은 어떻게 추가하나요?
왼쪽 패널에서 Actions 블록을 추가하거나, 섹션의 accessory로 버튼을 붙입니다. 링크를 열려면 url을, 앱에서 처리하려면 action_id와 value를 넣습니다. 앱이 Bolt의 respond()로 클릭에 답하면, replace_original=False를 넘기지 않는 한 답이 버튼이 있는 메시지를 대신합니다. say와 respond 테스트에서 확인했습니다.
모달과 App Home에도 Block Kit Builder를 쓸 수 있나요?
네. 미리 보기 위의 표시 위치 메뉴를 Modal Preview나 App Home Preview로 바꿉니다. 앱에서 모달을 열려면 클릭 후 약 3초 안에 views.open을 호출해야 하며, 이 시간은 expired_trigger_id 테스트에서 쟀습니다.
관련 기사
슬랙 xoxc·xoxd 토큰이란? 확인 방법까지 정리
xoxc는 슬랙 웹 클라이언트 토큰, xoxd는 세션 쿠키입니다. 둘 중 하나만으로는 동작하지 않습니다. 각 접두사의 의미, 확인 방법, 유효 기간을 정리했습니다.
Slack 메시지가 회색인 이유는?(직접 시험)
Slack 메시지가 회색이라면 아직 Slack에 닿지 않은 것입니다. 연결을 끊고 회색 글자를 측정했고, 문제없는 회색 줄도 확인했습니다.
Slack 표시 이름 바꾸는 법(직접 시험)
Slack 표시 이름은 프로필 편집에서 바꿀 수 있습니다. 어디에 보이는지, Slack이 어떤 이름을 거절하는지, 바꾼 이름이 반영되지 않는 이유를 시험했습니다.