Discord 봇을 만들면서 PHP에서 직접 메시지를 보내거나 채널을 관리해야 할 상황을 경험해봤을까. 대부분의 개발자들은 Discord.py나 discord.js 같은 라이브러리는 알지만, PHP에서 순수 REST API로 연동하는 방법은 의외로 복잡하다고 생각한다. 하지만 cURL과 JSON을 이해하면 충분히 가능하다.
이번에는 Discord Bot Token으로 PHP에서 직접 API를 호출하는 방법, 메시지 전송, 임베드(Rich Embed) 메시지, 채널 목록 조회, 메시지 편집/삭제까지 실무에서 쓸 수 있는 완벽한 구현법을 정리해서 소개하겠다.
Discord API를 사용하려면 먼저 봇 토큰이 필요하다. Discord Developer Portal에서 애플리케이션을 만들고, 'Bot' 섹션에서 토큰을 복사해야 한다. 이 토큰은 절대 공개하면 안 되는 민감한 정보다.
Discord API는 모든 요청에 Authorization 헤더를 필요로 한다. 형식은 단순하다. "Bearer [토큰]" 또는 "Bot [토큰]" 형식인데, 대부분의 엔드포인트에서는 "Bot [토큰]" 형식을 사용한다. PHP에서 cURL로 요청할 때는 다음처럼 헤더를 설정한다.
✓ 올바른 코드: Authorization 헤더에 "Bot" 접두사 포함
<?php
$botToken = 'YOUR_BOT_TOKEN_HERE';
$headers = [
'Authorization: Bot ' . $botToken,
'Content-Type: application/json',
'User-Agent: Discord-PHP-Bot/1.0'
];
?>
✗ 잘못된 코드: 토큰을 평문으로 노출하거나 헤더 형식이 틀린 경우
<?php
// 잘못된 예 1: 헤더 형식 오류
$headers = [
'Authorization: ' . $botToken, // 'Bot' 접두사 누락
'Content-Type: application/json'
];
// 잘못된 예 2: 토큰을 하드코딩
echo 'Your token: YOUR_BOT_TOKEN_HERE'; // 절대 금지
?>
가장 안전한 방식은 환경 변수나 설정 파일에서 토큰을 읽어오는 것이다.
<?php
// .env 또는 환경 변수에서 읽기
$botToken = getenv('DISCORD_BOT_TOKEN');
if (!$botToken) {
throw new Exception('DISCORD_BOT_TOKEN 환경 변수가 설정되지 않았습니다.');
}
$headers = [
'Authorization: Bot ' . $botToken,
'Content-Type: application/json',
'User-Agent: Discord-PHP-Bot/1.0'
];
?>
모든 Discord API 요청은 비슷한 구조를 가진다. 토큰 인증, HTTP 메서드, JSON 바디, 오류 처리. 이 반복을 줄이기 위해 헬퍼 함수를 만들면 코드가 훨씬 간결해진다.
다음은 모든 API 요청을 처리하는 기본 함수다.
<?php
class DiscordAPI {
private $baseUrl = 'https://discord.com/api/v10';
private $botToken;
public function __construct($botToken) {
$this->botToken = $botToken;
}
private function request($method, $endpoint, $data = null) {
$url = $this->baseUrl . $endpoint;
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_TIMEOUT => 10,
CURLOPT_HTTPHEADER => [
'Authorization: Bot ' . $this->botToken,
'Content-Type: application/json',
'User-Agent: Discord-PHP-Bot/1.0'
]
]);
if ($data !== null) {
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
}
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlError = curl_error($ch);
curl_close($ch);
if ($curlError) {
throw new Exception('cURL 오류: ' . $curlError);
}
$decoded = json_decode($response, true);
// Discord API는 2xx 성공, 4xx/5xx 에러 반환
if ($httpCode < 200 || $httpCode >= 300) {
$error = $decoded['message'] ?? 'Unknown error';
throw new Exception("Discord API 오류 ({$httpCode}): {$error}");
}
return $decoded;
}
public function sendMessage($channelId, $content, $embeds = []) {
$data = ['content' => $content];
if (!empty($embeds)) {
$data['embeds'] = $embeds;
}
return $this->request('POST', "/channels/{$channelId}/messages", $data);
}
}
?>
가장 기본이 되는 메시지 전송부터 시작하자. Discord의 채널 ID를 알아야 메시지를 보낼 수 있다. 채널 ID는 Discord의 개발자 모드를 켜고 채널을 우클릭하면 ID를 복사할 수 있다.
<?php
require_once 'DiscordAPI.php';
$discord = new DiscordAPI(getenv('DISCORD_BOT_TOKEN'));
$channelId = '1234567890123456789';
try {
$response = $discord->sendMessage(
$channelId,
'안녕하세요, Discord 봇 테스트입니다.'
);
echo 'Message sent! ID: ' . $response['id'];
} catch (Exception $e) {
echo '오류: ' . $e->getMessage();
}
?>
출력 결과: Message sent! ID: 1123581321345589144
단순한 텍스트보다는 시각적으로 꾸민 임베드 메시지가 훨씬 멋진 모습을 보여준다. 임베드는 색상, 제목, 설명, 필드, 이미지 등을 포함할 수 있다.
<?php
require_once 'DiscordAPI.php';
$discord = new DiscordAPI(getenv('DISCORD_BOT_TOKEN'));
$channelId = '1234567890123456789';
$embed = [
'title' => '서버 상태 보고',
'description' => '현재 서버의 상태를 보여줍니다.',
'color' => 3447003, // 파란색
'fields' => [
[
'name' => 'CPU 사용률',
'value' => '45%',
'inline' => true
],
[
'name' => '메모리',
'value' => '8GB / 16GB',
'inline' => true
],
[
'name' => '가동 시간',
'value' => '7일 12시간',
'inline' => false
]
],
'footer' => [
'text' => '마지막 갱신: 2024-01-15 14:30:00'
],
'thumbnail' => [
'url' => 'https://example.com/server-icon.png'
]
];
try {
$response = $discord->sendMessage($channelId, '', [$embed]);
echo '임베드 메시지 전송 완료';
} catch (Exception $e) {
echo '오류: ' . $e->getMessage();
}
?>
출력 결과: 임베드 메시지 전송 완료 (Discord에서 시각적으로 꾸민 메시지가 표시됨)
메시지 전송뿐만 아니라 채널 목록 조회, 메시지 편집, 삭제 등도 같은 방식으로 구현한다.
<?php
class DiscordAPI {
// 기존 코드...
public function getChannel($channelId) {
return $this->request('GET', "/channels/{$channelId}");
}
public function getMessages($channelId, $limit = 50) {
return $this->request('GET', "/channels/{$channelId}/messages?limit={$limit}");
}
public function editMessage($channelId, $messageId, $content, $embeds = []) {
$data = ['content' => $content];
if (!empty($embeds)) {
$data['embeds'] = $embeds;
}
return $this->request('PATCH', "/channels/{$channelId}/messages/{$messageId}", $data);
}
public function deleteMessage($channelId, $messageId) {
return $this->request('DELETE', "/channels/{$channelId}/messages/{$messageId}");
}
public function getGuildChannels($guildId) {
return $this->request('GET', "/guilds/{$guildId}/channels");
}
}
?>
<?php
require_once 'DiscordAPI.php';
$discord = new DiscordAPI(getenv('DISCORD_BOT_TOKEN'));
$channelId = '1234567890123456789';
$messageId = '1123581321345589144';
try {
// 채널 정보 조회
$channel = $discord->getChannel($channelId);
echo '채널명: ' . $channel['name'] . PHP_EOL;
// 최근 메시지 10개 조회
$messages = $discord->getMessages($channelId, 10);
echo '최근 메시지 수: ' . count($messages) . PHP_EOL;
// 메시지 편집
$discord->editMessage($channelId, $messageId, '수정된 메시지 내용');
echo '메시지 편집 완료' . PHP_EOL;
// 메시지 삭제 (3초 후)
sleep(3);
$discord->deleteMessage($channelId, $messageId);
echo '메시지 삭제 완료';
} catch (Exception $e) {
echo '오류: ' . $e->getMessage();
}
?>
출력 결과: 채널명: general, 최근 메시지 수: 10, 메시지 편집 완료, 메시지 삭제 완료
✗ 잘못된 사용: Rate Limit 무시하고 메시지 폭주
<?php
// 위험: Discord는 Rate Limit이 있음
for ($i = 0; $i < 100; $i++) {
$discord->sendMessage($channelId, 'Message ' . $i);
}
?>
Discord API는 요청 개수를 제한한다. 초 단위로 최대 요청 수가 정해져 있고, 초과하면 429 에러(Too Many Requests)를 받는다.
✓ 올바른 사용: Rate Limit을 고려한 타임아웃 추가
<?php
private function request($method, $endpoint, $data = null) {
// 기존 cURL 코드...
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$headers = curl_getinfo($ch);
curl_close($ch);
// Rate Limit 처리
if ($httpCode === 429) {
$decoded = json_decode($response, true);
$retryAfter = $decoded['retry_after'] ?? 1;
sleep($retryAfter); // Discord가 지정한 시간만큼 대기
return $this->request($method, $endpoint, $data); // 재시도
}
// 나머지 코드...
}
?>
✗ 잘못된 코드: 오류 처리 없이 ID 사용
<?php
$channelId = $_GET['channel_id']; // 사용자 입력을 그대로 사용
$discord->sendMessage($channelId, 'Test');
?>
✓ 올바른 코드: 채널 존재 여부 확인
<?php
try {
$channelId = $_GET['channel_id'];
if (!preg_match('/^\d{18}$/', $channelId)) {
throw new Exception('유효하지 않은 채널 ID 형식');
}
$channel = $discord->getChannel($channelId);
$discord->sendMessage($channelId, 'Test');
} catch (Exception $e) {
http_response_code(400);
echo json_encode(['error' => $e->getMessage()]);
}
?>
✗ 절대 금지: 소스 코드에 토큰 하드코딩
<?php
$botToken = 'MTA5NzI4NDk0MjA3NTQ2Nzg2NQ.GxY...';
?>
✓ 필수: 환경 변수에서 읽기
<?php
// .env 파일
DISCORD_BOT_TOKEN=MTA5NzI4NDk0MjA3NTQ2Nzg2NQ.GxY...
// PHP 코드
require 'vendor/autoload.php';
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
$botToken = $_ENV['DISCORD_BOT_TOKEN'];
?>
실제로 쓸 수 있는 예제를 만들어보자. 1시간마다 서버 상태를 Discord 채널에 보내는 모니터링 봇이다.
<?php
require 'vendor/autoload.php';
require_once 'DiscordAPI.php';
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
class ServerMonitor {
private $discord;
private $channelId;
public function __construct($botToken, $channelId) {
$this->discord = new DiscordAPI($botToken);
$this->channelId = $channelId;
}
public function getSystemStats() {
// 서버 상태 정보 수집
$load = sys_getloadavg();
$memUsage = shell_exec('free -h | awk \'NR==2 {print $3 "/" $2}\'');
$uptime = shell_exec('uptime -p | sed \'s/^up //\'');
$timestamp = date('Y-m-d H:i:s');
return [
'load' => $load[0],
'memory' => trim($memUsage),
'uptime' => trim($uptime),
'timestamp' => $timestamp
];
}
public function sendMonitoringReport() {
$stats = $this->getSystemStats();
$embed = [
'title' => '서버 모니터링 리포트',
'color' => ($stats['load'] > 2.0) ? 15158332 : 3447003, // 빨강 또는 파랑
'fields' => [
[
'name' => 'CPU Load',
'value' => number_format($stats['load'], 2),
'inline' => true
],
[
'name' => '메모리 사용',
'value' => $stats['memory'],
'inline' => true
],
[
'name' => '가동 시간',
'value' => $stats['uptime'],
'inline' => false
]
],
'footer' => [
'text' => $stats['timestamp']
]
];
try {
$this->discord->sendMessage($this->channelId, '', [$embed]);
echo '[' . date('Y-m-d H:i:s') . '] 모니터링 리포트 전송 완료' . PHP_EOL;
} catch (Exception $e) {
echo '[' . date('Y-m-d H:i:s') . '] 오류: ' . $e->getMessage() . PHP_EOL;
}
}
}
// 크론 작업으로 매시간 실행
$monitor = new ServerMonitor(
$_ENV['DISCORD_BOT_TOKEN'],
$_ENV['DISCORD_CHANNEL_ID']
);
$monitor->sendMonitoringReport();
?>
이 스크립트를 crontab에 등록하면 자동으로 실행된다.
0 * * * * /usr/bin/php /path/to/monitor.php >> /var/log/discord-monitor.log 2>&1
Discord Bot REST API는 처음엔 복잡해 보이지만, 토큰 인증 헤더와 cURL 기초만 이해하면 충분히 활용할 수 있다. Rate Limit 처리와 환경 변수 관리는 선택이 아니라 필수다. 작은 모니터링 봇부터 시작해 복잡한 상호작용 기능까지 확장할 수 있다는 점이 REST API의 가장 큰 장점이다. 이 글의 DiscordAPI 클래스를 참고해 자신의 프로젝트에 맞게 커스터마이징하면, Discord를 PHP 백엔드와 완벽하게 연동할 수 있을 것이다.