문제 해결

자주 막히는 곳을 모았어요. 여기서 풀리지 않으면 운영진에게 문의해 주세요.

봇이 오프라인으로 보여요#

마지막 heartbeat 뒤 10분이 지나면 오프라인이 돼요. 타이머가 1~5분마다 돌고 있는지 확인해 주세요.
응답이 401이면 토큰 문제예요. 아래 401 unauthorized가 와요를 봐 주세요.
응답이 404면 봇 id나 권한 문제예요. 아래 404 not_found가 와요를 봐 주세요.
휴대폰에서 도는 봇이면 절전 모드나 배터리 최적화가 앱을 멈추지 않는지 봐 주세요. 앱이 멈추면 타이머도 멈춰요.
예전 주소 /v1/bots/heartbeat나 /v1/bots/stats로 보내고 있다면 410이 와요. /v1/bots/{id}/heartbeat로 바꿔 주세요.

401 unauthorized가 와요#

Authorization: Bearer hkd_… 모양인지 봐 주세요. Bearer가 빠지거나 앞뒤에 공백·줄바꿈이 섞이면 받지 않아요.
hk_로 시작하는 예전 봇 토큰은 더 쓸 수 없어요. 토큰에서 개발자 토큰을 만들어 바꿔 주세요.
폐기한 토큰은 바로 끊겨요. 토큰 목록에 아직 있는지 봐 주세요.
탈퇴했거나 정지된 계정의 토큰은 쓸 수 없어요.

404 not_found가 와요#

주소의 봇 id를 확인해 주세요. bot_으로 시작하는 id여야 하고, 커스텀 URL은 받지 않아요.
토큰 주인이 그 봇의 소유자이거나 '개발 도구' 권한을 받은 공동 제작자여야 해요. 공동 제작자에서 빠졌거나 권한이 바뀌지 않았는지 봐 주세요.
삭제한 봇에는 보낼 수 없어요.

410 Gone이 와요#

POST /v1/bots/heartbeat, POST /v1/bots/stats, POST /v1/bots/verify는 없어진 주소예요. 모두 개발자 토큰과 POST /v1/bots/{id}/heartbeat로 바꿔 주세요. 본문은 없어도 돼요. 무엇이 바뀌었는지는 변경 기록에 있어요.

봇 등록 5단계가 넘어가지 않아요#

5단계 화면에 보이는 봇 id로 heartbeat를 한 번 보내야 넘어가요. 화면은 3초마다 확인해요.
다른 봇의 id를 넣지 않았는지 봐 주세요. 코드 예시에는 이 봇의 id가 이미 들어 있어요.
토큰은 여러 개 만들어도 모두 살아 있어요. 폐기한 토큰만 끊겨요.
curl로 먼저 보내 보면 봇 코드 문제인지 토큰 문제인지 가를 수 있어요. 봇 연결 › 코드 예시

방 수가 0이거나 늘지 않아요#

방 수는 봇이 보고하는 값이 아니라, 한카리 초대 신청으로 입장이 끝난 방의 수예요. 제작자가 '입장시켰어요'를, 신청자가 '봇이 들어왔어요'를 둘 다 눌러야 하나로 세요. 수락 뒤 7일 안에 둘 다 누르지 않으면 신청이 입장 확인 없이 끝나고 세지 않아요. 같은 방에 다시 들어가도 한 번만 세요.

웹훅 서명이 맞지 않아요#

받은 본문을 그대로(바이트 그대로) 서명해야 해요. JSON으로 읽었다가 다시 만들면 띄어쓰기와 순서가 달라져 서명이 달라져요.
비교할 값은 sha256=까지 붙은 헤더 값 전체예요.
키를 다시 발급했다면 서버에도 새 키를 넣었는지 봐 주세요.
키는 whsec_까지 포함한 문자열 전체예요.

웹훅이 실패로 남아요#

5초 안에 답하지 않으면 시간 초과로 적어요. 먼저 2xx로 답하고 일은 따로 처리해 주세요.
3xx로 답하면 따라가지 않고 실패로 남아요. 옮겨 간 주소를 저장해 주세요.
4xx는 받는 쪽이 거절한 것으로 보고 다시 보내지 않아요(429만 다시 보내요).
인증서가 만료됐거나 올바르지 않으면 연결 실패로 남아요.
전송 기록에서 한 줄을 펼치면 응답 코드와 응답 본문 앞부분을 볼 수 있어요. 웹훅 설정 › 전송 기록

배지가 '없는 봇'으로 나와요#

공개된 봇만 배지를 그려요. 심사 중이거나 비공개인 봇은 '없는 봇'으로 나와요.
주소의 봇 id를 확인해 주세요. 커스텀 URL은 신뢰된 봇인 동안에만 쓸 수 있어요.
값은 rooms와 hearts 두 가지예요. README 위젯