이 글은 Claude Opus 4.8 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

Part 1에서는 Discord가 어떻게 태어나 성장했고 어떤 결정으로 지금의 모습이 되었는지를 살펴봤습니다. 이번 Part 2에서는 개발자 입장에서 Discord가 얼마나 대인배인지 를 이야기합니다.

결론부터 말하면, API·봇·Webhook·Gateway·Interactions·OAuth2·임베드·CDN 첨부·음성 채널·스레드·포럼 채널이 전부 무료입니다. 서버 크기 제한도 없습니다. 흔히 보이는 유료 구독 Nitro는 개인 사용자(엔드유저) 대상이지 개발자 기능이 아닙니다. 봇을 만들고 운영하는 데 Discord에 내는 비용은 0원이며, 드는 비용이 있다면 봇을 돌릴 본인 호스팅 비용뿐입니다.

참고: Discord 공식 개발자 문서는 현재 docs.discord.com/developers/... 도메인이 정본이며, 예전 discord.com/developers/docs/... 경로는 301 리다이렉트됩니다. 이 글의 링크는 신 도메인을 따릅니다.

하나씩 살펴보겠습니다.

1. Webhook — 가장 진입 장벽이 낮은 무료 기능#

가장 먼저 추천하는 것이 Webhook입니다. 공식 문서의 설명이 핵심을 찌릅니다.

“Webhooks are a low-effort way to post messages to channels in Discord. They do not require a bot user or authentication to use.” — Webhook Resource

즉 봇도, 인증 토큰도 필요 없습니다. 채널 설정에서 Webhook을 만들면 URL이 하나 발급되고, 그 URL로 JSON을 POST하면 끝입니다. URL 자체가 비밀(secret) 역할을 합니다.

실행 엔드포인트는 다음과 같습니다.

POST /webhooks/{webhook.id}/{webhook.token}

최소한의 예시는 이렇게 단순합니다.

curl -X POST "https://discord.com/api/webhooks/{ID}/{TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"content":"빌드 실패 ❌","username":"CI Bot"}'

보낼 수 있는 주요 필드는 content(최대 2000자), username/avatar_url(표시 이름·아바타를 메시지 단위로 덮어쓰기), embeds(최대 10개), 파일 업로드, thread_id/thread_name 등입니다. content·embeds·components·file·poll 중 최소 하나는 있어야 합니다.

특히 개발자에게 유용한 것은 호환 엔드포인트입니다.

  • /webhooks/{id}/{token}/slack — Slack 포맷 payload를 그대로 받음
  • /webhooks/{id}/{token}/github — GitHub 저장소 이벤트(push, pull_request, issues, release 등)를 받음. GitHub 레포 설정에 이 URL만 넣으면 별도 코드 없이 알림 연동이 됩니다.

활용처: CI 빌드 결과 알림, 모니터링·장애 알림, GitHub 활동 알림. 봇 작성과 토큰 관리 없이 URL 하나로 끝나니, “외부에서 채널로 메시지를 쏘기만 하면 되는” 모든 시나리오의 1순위 선택지입니다.

레이트 리밋 주의: 흔히 인용되는 “Webhook당 60초에 30건” 수치는 공식 문서 본문에 명시된 값이 아닙니다. 커뮤니티에서 관측된 동작에 가깝습니다 (참고: birdie0의 Webhook 가이드). 확실한 공식 사실은 429 응답 시 Retry-After 헤더를 존중해야 한다는 것, 그리고 같은 채널의 Webhook들이 레이트 리밋 버킷을 공유할 수 있다는 점입니다. 정확한 동작은 아래 8번 항목을 참고하세요.

2. Bot — 무료로 만드는 자동화의 핵심#

Webhook이 “보내기 전용"이라면, 양방향(메시지를 받고 반응하기)이 필요할 때는 봇이 답입니다.

Developer Portal에서 Application을 생성하고, Bot 페이지에서 토큰을 발급받으면 됩니다. 전부 무료입니다.

여기서 헷갈리기 쉬운 두 개념을 정리하면:

  • Application: Developer Portal 상의 전체 설정 단위(이름, 권한, OAuth2 설정 등)
  • Bot User: 서버에 실제로 들어가 다른 멤버처럼 보이고 행동하는 실체

봇이 이벤트를 받는 방식은 두 가지입니다. Gateway(WebSocket) 또는 HTTP Interactions입니다(각각 6번, 3번 항목 참고). 발급받는 자격 증명은 Application ID, Public Key(요청 검증용), 그리고 Bot Token인데, 이 토큰은 “highly sensitive” 한 값이라 절대 버전 관리에 커밋하면 안 됩니다. (보안 관련 best practice는 Part 3에서 자세히 다룹니다.)

3. Slash Command / Interactions — 서버리스로도 봇을 돌린다#

여기에 Discord의 대인배 면모가 하나 더 있습니다. Gateway(WebSocket) 연결을 상시 유지하지 않고도 봇을 운영할 수 있다는 점입니다.

“Interactions Endpoint URL is a public endpoint for your app where Discord can send your app HTTP-based interactions.” — Interactions Overview

즉, 당신이 WebSocket을 붙잡고 있는 것이 아니라 Discord가 당신의 HTTP 엔드포인트로 요청을 POST해 줍니다. 덕분에 AWS Lambda, Cloudflare Workers 같은 서버리스 환경에서 상시 연결 없이 슬래시 커맨드 봇을 구현할 수 있습니다. 항상 켜둔 서버가 부담스러운 개인 개발자에게 큰 선물입니다.

명령의 종류는 슬래시 커맨드(/로 호출), user/message 컨텍스트 메뉴 커맨드 등이 있고, 메시지 컴포넌트로 버튼, 셀렉트 메뉴, 모달(폼 입력) 을 붙일 수 있습니다.

다만 HTTP Interactions를 쓸 때 지켜야 할 규칙이 몇 가지 있습니다 (Receiving and Responding).

  • 서명 검증 필수: Discord가 X-Signature-Ed25519와 X-Signature-Timestamp 헤더를 함께 보냅니다. Ed25519 서명을 검증하지 못하면 401을 반환해야 합니다.
  • PING/PONG 핸드셰이크: 엔드포인트 등록 시 Discord가 type: 1(PING)을 보내며, 앱은 PONG으로 응답해야 합니다.
  • 3초 룰: “you must send an initial response within 3 seconds” — 3초 안에 최초 응답(ACK)을 보내야 합니다. 처리에 시간이 걸리면 일단 “defer”(로딩 표시)로 응답하고, 이후 interaction token이 유효한 15분 동안 follow-up 메시지를 보낼 수 있습니다.

4. Embed — 메시지를 리치하게#

밋밋한 텍스트 대신 제목·설명·필드·색상·이미지를 갖춘 카드 형태로 메시지를 꾸미는 것이 임베드(Embed) 입니다. 공식 문서(Message Resource)에 명시된 한계치는 다음과 같습니다.

항목 한계
title 256자
description 4096자
field 개수 최대 25개
field.name 256자
field.value 1024자
footer.text 2048자
author.name 256자
메시지당 embed 개수 10개

한 가지 자주 혼동되는 점이 있습니다. 공식 문서는 “한 메시지에 첨부된 모든 embed의 title·description·field.name·field.value·footer.text·author.name 글자 수 합계가 6000자를 넘으면 안 된다” 고 규정합니다. 6000자는 embed 1개당이 아니라 메시지의 모든 embed 합산 기준입니다 (이 점이 헷갈려 공식 이슈로도 제기된 바 있습니다).

5. OAuth2 — “Discord로 로그인"과 “서버에 추가”#

OAuth2도 무료로 제공됩니다. 대표적인 두 가지 활용은 다음과 같습니다.

  • “Discord로 로그인”: Authorization Code Grant + identify scope(필요 시 email). 별도 회원 시스템 없이 Discord 계정으로 사용자를 인증할 수 있습니다.
  • “서버에 추가”: bot scope에 permissions(비트와이즈 권한 플래그) 파라미터를 붙여 인증 URL을 만들면, 사용자가 서버를 선택하는 것만으로 봇이 자동으로 추가됩니다. 기본 봇 설정에는 콜백조차 필요 없습니다.

주요 scope를 공식 정의로 옮기면 다음과 같습니다.

  • identify — email 없이 /users/@me 호출 허용
  • email — /users/@me가 email을 반환하도록 허용
  • guilds — 사용자가 속한 길드의 기본 정보 조회 허용
  • bot — 봇을 사용자가 선택한 길드에 추가
  • applications.commands — 길드에 커맨드 추가 허용(bot scope에 기본 포함)

6. Gateway — 실시간 WebSocket API#

봇이 메시지·리액션·멤버 변동 같은 이벤트를 실시간으로 받아야 한다면 Gateway를 씁니다.

“The Gateway API lets apps open secure WebSocket connections with Discord to receive events about actions that take place in a server/guild.” — Gateway

연결 흐름을 요약하면: WSS URL을 받아 연결 → Hello(heartbeat 주기 포함) 수신 → 주기적으로 heartbeat 송신 → Identify 송신 → Ready(여기에 재연결용 resume_gateway_url과 session_id가 담겨 옴) 수신. 이후 길드의 각종 액션이 Dispatch 이벤트로 전달됩니다.

두 가지 운영 포인트를 알아두면 좋습니다.

  • 샤딩(Sharding): “각 shard는 최대 2500개의 길드만 지원하며, 2500개 이상의 길드에 들어간 앱은 반드시 샤딩을 활성화해야 한다” 고 규정합니다.
  • Intents(인텐트): 받고 싶은 이벤트 카테고리를 명시해야 하며, 지정하지 않으면 해당 이벤트를 아예 받지 못합니다. 특히 GUILD_PRESENCES, GUILD_MEMBERS, MESSAGE_CONTENT는 privileged intent로 분류되어 Developer Portal에서 명시적으로 켜야 하고, 봇이 일정 규모(보통 100개 서버) 이상이 되면 별도의 검증(verification)이 필요합니다.

7. 그 밖의 대인배 무료 기능들#

위 핵심 외에도 개발자가 공짜로 누릴 수 있는 것들이 많습니다.

  • 음성·영상 채널 무료: API 채널 타입에 GUILD_VOICE(type 2), 청중을 두고 진행하는 GUILD_STAGE_VOICE(type 13)가 있습니다 (Channel Resource).
  • 스레드: PUBLIC_THREAD(11), PRIVATE_THREAD(12), ANNOUNCEMENT_THREAD(10).
  • 포럼·미디어 채널: GUILD_FORUM(15)은 스레드만 담을 수 있는 게시판형 채널, GUILD_MEDIA(16)는 미디어 중심 채널입니다.
  • Discord CDN 첨부 호스팅: Webhook·봇 메시지에 파일을 첨부하면 Discord CDN이 호스팅해 줍니다.
  • 서버 크기 무관 무료: 커뮤니티 규모와 상관없이 비용 게이트가 없습니다.
  • 무제한 메시지 히스토리: 널리 알려진 정책입니다(단일 공식 문서 페이지로 인용하기는 어려워, “일반적으로 알려진 동작"으로 받아들이는 편이 안전합니다).

8. Rate Limit — 공짜라고 무한은 아니다#

대인배라도 무제한은 아닙니다. API를 쓴다면 레이트 리밋을 반드시 이해해야 합니다 (Rate Limits).

  • 글로벌 리밋: “All bots can make up to 50 requests per second to our API.” — 봇당 초당 50건. 단, Interaction 엔드포인트는 글로벌 리밋에서 면제됩니다.
  • Per-route 버킷: 엔드포인트별로 별도 버킷이 있고, channel_id·guild_id·webhook_id 같은 top-level 리소스 단위로 구분됩니다.
  • 응답 헤더: X-RateLimit-Limit(허용량), X-RateLimit-Remaining(잔여), X-RateLimit-Reset(리셋 시각), X-RateLimit-Reset-After(리셋까지 남은 초), X-RateLimit-Bucket(버킷 식별자), X-RateLimit-Scope(user/global/shared) 등을 활용해 클라이언트가 스스로 속도를 조절할 수 있습니다.
  • 429 처리: 한도를 넘으면 429와 함께 retry_after(초)가 내려옵니다. 이 값을 존중해 재시도해야 합니다.
  • 무효 요청 제한: 잘못된 HTTP 요청을 너무 많이 보내면(10분에 1만 건) IP가 일시적으로 차단됩니다.

정리하며#

Discord는 개발자에게 인증·비용 장벽 없이 강력한 원시 도구(primitive)를 풀어줍니다. 가볍게 알림만 쏘고 싶으면 Webhook, 양방향 자동화가 필요하면 봇, 상시 서버가 부담되면 HTTP Interactions로 서버리스 봇을 만들면 됩니다. 그리고 그 한계선은 레이트 리밋입니다.

다음 Part 3에서는 이 무료 기능들을 조합해 Discord를 원격 control plane으로 쓰는 실전 사례 — AI 코딩 에이전트 원격 제어, ChatOps, 홈랩 모니터링 — 와 그 best practice를 다루겠습니다.

References#