봇 연결

POST/v1/bots/{id}/heartbeat

봇 코드에서 개발자 토큰으로 이 봇의 heartbeat를 한 번 보내면 봇이 한카리에 연결돼요. 봇 등록 5단계는 이 호출을 기다렸다가 다음 단계로 넘어가요. 연결에 따로 쓰는 주소는 없고, 그 뒤로 보내는 heartbeat가 곧 가동 상태 보고예요.

연결은 토큰을 가진 프로그램이 실제로 돌고 있다는 것까지만 확인해요. 봇이 정말 이 제작자의 것인지는 심사자가 테스트방에서 직접 확인해요.

연결 순서#

Hankari Devs에서 봇 정보, 명령어, 초대 설정, 테스트방을 입력해요.
5단계 봇 연결에서 봇 id를 확인해요. 개발자 토큰이 없으면 그 자리에서 만들어요. 토큰은 이때 한 번만 보이고, 이미 만든 토큰이 있으면 그대로 써도 돼요.
봇 코드에 토큰과 봇 id를 넣고 아래처럼 heartbeat를 보내요.
화면이 "봇이 연결됐어요"로 바뀌면 심사를 신청할 수 있어요.

경로 변수#

이름	설명
`id`	봇 id. `bot_`으로 시작해요. 봇 등록 5단계나 봇 관리 › 연동, 토큰 화면에서 복사할 수 있어요. 커스텀 URL은 받지 않아요.

요청 헤더#

이름	필수	설명
`Authorization`	필수	`Bearer {개발자 토큰}`

응답#

200 OK
{
  "status": "online",
  "reportedAt": "2026-09-14T06:02:11.000Z"
}

토큰이 잘못됐거나 폐기된 토큰이면 401을, 봇 id가 틀렸거나 토큰 주인이 그 봇을 다룰 수 없으면 404를 돌려줘요. 예전 주소 /v1/bots/heartbeat와 /v1/bots/verify는 410 Gone을 돌려줘요.

코드 예시#

메신저봇R#

// 봇이 켜질 때 한 번 호출
const HANKARI_TOKEN = "hkd_…";
const BOT_ID = "bot_…";

org.jsoup.Jsoup
  .connect("https://hankari.dev/v1/bots/" + BOT_ID + "/heartbeat")
  .header("Authorization", "Bearer " + HANKARI_TOKEN)
  .ignoreContentType(true)
  .method(org.jsoup.Connection.Method.POST)
  .execute();

Iris#

# 봇이 켜질 때 한 번 호출
import requests

requests.post(
    f"https://hankari.dev/v1/bots/{BOT_ID}/heartbeat",
    headers={"Authorization": "Bearer " + HANKARI_TOKEN},
    timeout=10,
)

curl#

curl -X POST "https://hankari.dev/v1/bots/$BOT_ID/heartbeat" \
  -H "Authorization: Bearer $HANKARI_TOKEN"