개발자 시작 가이드

준비하기

콘솔에서 네 단계를 마치면 서버 코드 몇 줄로 메시지를 보낼 수 있습니다.

1. 톡방 연결

   내 톡방에서 연결 코드를 발급하고 안내대로 연결을 요청하세요. 운영자가 승인하면 방이 목록에 나타납니다.

2. 서비스와 API 키

   서비스를 만들고 API 키를 발급하세요. 방과 서비스는 같은 워크스페이스에 있어야 합니다.

3. 방에 서비스 연결

   내 톡방에서 서비스를 연결하고 활성화하세요. 키는 연결된 방에만 보낼 수 있습니다.

4. 방 주소 복사

   방 상세에서 고정 ID를 복사하거나 원하는 slug를 정하세요. 이 값을 서버 코드에 넣습니다.

서버에서 첫 메시지 보내기

npm install @noti-bot/sdk로 설치한 뒤 아래 예제를 사용하세요. 허브 주소는 https://api.notibot.xyz입니다.

NOTIBOT_URL=https://api.notibot.xyz   # 허브 주소
NOTIBOT_API_KEY=kb_...            # 서비스에서 발급한 API 키
KAKAO_ROOM_ID=...                       # 방 상세에서 복사한 고정 ID

import { NotiBot } from '@noti-bot/sdk';

const bot = new NotiBot({
  baseUrl: process.env.NOTIBOT_URL!,
  apiKey: process.env.NOTIBOT_API_KEY!,
});

// 키에 연결된 방의 id, slug, 발송 가능 상태를 확인합니다.
const rooms = await bot.listRooms();

const result = await bot.sendMessage({
  roomId: process.env.KAKAO_ROOM_ID!,
  text: '배포가 완료되었습니다.',
  requestId: 'deploy:release-001',
});

// 읽기 쉬운 주소를 쓰려면 roomId 대신 roomSlug: 'deploy-alerts'
console.log(result);

roomId

방의 고정 ID입니다. slug를 바꿔도 그대로 유지됩니다.

roomSlug

읽기 쉬운 주소입니다. 워크스페이스 안에서 고유하며, 바꾸면 이전 주소를 쓰던 코드도 함께 수정해야 합니다.

사람 태그하기

본문에 <@카톡ID>를 넣으면 진짜 카톡 멘션이 됩니다. ID는 방 상세의 참여자 탭이나 listRoomMembers로 찾습니다.

import { NotiBot, mention } from '@noti-bot/sdk';

// 방에 있는 사람 (rooms:read 권한)
const people = await bot.listRoomMembers({ roomSlug: 'deploy-alerts' });
const owner = people.find((p) => p.name === '김준민');

// 태그는 <@카톡ID>. 받는 사람에게 알림이 갑니다.
await bot.sendMessage({
  roomSlug: 'deploy-alerts',
  text: `${owner?.mention ?? ''} 배포 확인 부탁해요`,
});

// 웹훅 응답에서 말한 사람 태그: mention(event.senderId)

mentions

웹훅에 오는, 메시지가 태그한 사람 목록입니다.

{보낸사람}

키워드 자동응답에서 말한 사람을 태그합니다.

mention_unresolved

방에 없거나 이름을 아직 모르는 사람이라 보내지 않았습니다.

테스트 키로 먼저 검증하기

키를 발급할 때 테스트를 선택하면 같은 SDK 코드로 입력값과 방 연결 권한을 확인할 수 있습니다. 실제 발송과 사용량 차감은 없습니다.

테스트 요청은 메시지 로그에 남지 않습니다. 결과는 SDK 응답으로 확인하세요. 검증이 끝나면 운영 키를 따로 발급해 교체합니다.

발송 결과 확인하기

queued: true

접수 완료입니다. 실제 발송 결과는 방의 로그에서 확인하세요.

canReply: false

방 목록에서 이 값이 false라면 봇이 그 방의 메시지를 받은 적이 있는지 확인하세요.

requestId

같은 발송을 다시 요청할 때는 같은 ID를 쓰세요. 새 알림에는 새 ID가 필요합니다.

SDK는 자동으로 재시도하지 않습니다. 타임아웃이 발송 실패를 뜻하지는 않으니, 다시 보내기 전에 로그를 먼저 확인하세요.

연동이 막혔을 때

응답 상태 코드별로 먼저 확인할 곳입니다.

• 401
  인증 실패키가 폐기되지 않았는지, 서비스가 활성 상태인지 확인하세요.
• 402
  월 한도사용량에서 월 사용량을 확인하세요.
• 403
  권한 없음방 ID 또는 slug와 서비스 연결 권한을 확인하세요.
• 429
  요청 과다짧은 시간에 요청이 몰렸습니다. 발송 속도를 낮추세요.