개발자 API 문서

아이비봇과 이 사이트를 잇는 API 예요. 직접 봇을 만드시거나, 아이비봇의 상태를 다른 곳에서 쓰고 싶으실 때 보세요.

1. 인증

헤더 두 개를 붙이세요.

키는 관리자 → 봇 연동 → 새 키 만들기 에서 받습니다. 만들 때 한 번만 보여 주고 저장은 해시로만 하니, 잃어버리면 새로 만드세요.

권한

2. 호출 제한

• 키 하나당 1분에 240회까지. 넘기면 429 too_many 예요.
• 1분 신호 + 여유를 잡은 값이라 정상적으로 쓰시면 걸릴 일이 없어요.
• 모든 호출은 관리자 → 봇 연동 의 호출 기록에 남습니다.

3. 동작

GET ?a=ping 없어도 됨

서버가 살아 있는지 봅니다. 키 없이 부를 수 있는 유일한 동작이에요.

돌아오는 것

{"ok":true,"pong":true,"time":"2026-09-27 01:00:00","rev":"6114d4b107de"}

POST ?a=heartbeat bot

봇이 살아 있다고 알립니다. 1분마다 보내세요. 가동률이 이 신호로 계산돼요.

보내는 것

{
  "device":  "phone-01",
  "label":   "아이비봇 폰",
  "version": "1.7.0",
  "uptime":  9000,
  "rooms":   ["1234567890", "9876543210"],
  "cpu":     "12.4%",
  "mem":     "2.1GB / 5.8GB (36%)",
  "ping":    38
}

돌아오는 것

{
  "ok": true,
  "server_time": "2026-09-27 01:00:00",
  "rev": "6114d4b107de",
  "online": true,
  "uptime_24h": 99.8
}

GET ?a=plans bot

플랜, 기능 허용표, 제한값, 방별 플랜을 한 번에 받습니다. heartbeat 의 rev 가 바뀌었을 때만 다시 부르세요.

돌아오는 것

{
  "ok": true,
  "rev": "6114d4b107de",
  "plans": [
    {"code":"free","name":"무료","price":"0원","price_won":0,
     "final_won":0,"discount":null,"summary":"..."},
    {"code":"pro","name":"프로","price":"20,000원","price_won":20000,
     "final_won":16000,
     "discount":{"type":"percent","value":20,"label":"가을 할인","until":"2026-10-31 23:59:59"},
     "summary":"..."}
  ],
  "features": {"translate":{"name":"번역","group":"lookup","always":false}, "...": {}},
  "matrix":   {"free":["calc","weather"], "pro":["..."]},
  "limits":   {"free":{"notes_max":20}, "pro":{"notes_max":-1}},
  "limit_meta": {"notes_max":{"name":"노트 저장 개수","unit":"개","higher":true}},
  "always":   ["system","admin_tools"],
  "rooms":    {"1234567890":{"plan":"pro","active":true,"name":"컨볼 소통방"}},
  "default_plan": "free"
}

GET ?a=room bot

방 하나의 플랜과 열린 기능을 봅니다. 주소에 &key=방식별값 을 붙이세요.

돌아오는 것

{
  "ok": true,
  "rev": "6114d4b107de",
  "registered": true,
  "room": {"key":"1234567890","name":"컨볼 소통방","plan":"pro",
           "manager_link":true,"active":true},
  "plan": "pro",
  "features": ["translate","points","games","..."],
  "limits":   {"notes_max":-1,"gift_daily":10000}
}

POST ?a=setup admin

방을 등록하거나 플랜을 바꿉니다. $setup 이 쓰는 곳이에요. 방이 없으면 새로 만듭니다.

보내는 것

{
  "room_key":     "1234567890",
  "room_name":    "컨볼 소통방",
  "plan":         "standard",
  "manager_link": true,
  "by":           "아이비"
}

돌아오는 것

{
  "ok": true,
  "created": false,
  "rev": "8d62bb0012d4",
  "room": {"key":"1234567890","name":"컨볼 소통방","plan":"standard","manager_link":true},
  "features": ["translate","points","..."],
  "limits":   {"notes_max":200,"gift_daily":3000}
}

GET ?a=rooms admin

등록된 방을 전부 봅니다.

돌아오는 것

{
  "ok": true, "rev": "...", "count": 3,
  "rooms": [
    {"key":"1234567890","name":"컨볼 소통방","plan":"pro",
     "manager_link":true,"active":true,"last_seen":"2026-09-27 00:59:12"}
  ]
}

4. rev 로 바뀐 것만 받기

모든 응답에는 rev 가 들어 있어요. 플랜, 기능 허용표, 제한값, 할인, 방 목록 중 무엇이든 바뀌면 이 값이 달라집니다.

봇은 이렇게 쓰면 됩니다.

1. 1분마다 heartbeat 를 보낸다
2. 응답의 rev 가 갖고 있던 값과 같으면 아무것도 하지 않는다
3. 다르면 plans 를 한 번 불러 캐시를 갈아 끼운다

이러면 설정이 그대로인 동안에는 1분에 한 번의 작은 요청만 오갑니다.

5. 기능 키 목록 · 30종

matrix 와 features 에 나오는 키예요.

6. 제한 키 목록 · 10종

limits 에 나오는 키예요. 값은 정수이고, -1 은 무제한, 0 은 항목마다 뜻이 다릅니다.

7. 오류

실패하면 이렇게 돌아옵니다. HTML 이 튀어나오는 일은 없어요.

{"ok":false,"error":"bad_key","message":"키가 맞지 않습니다."}

8. 붙여 쓰는 예시

curl

curl -s "https://ibcytb.com/bot/api.php?a=ping"

curl -s -X POST "https://ibcytb.com/bot/api.php?a=heartbeat" \
  -H "X-Ivy-Key: ivy_ab12cd.xxxxxxxxxxxx" \
  -H "X-Ivy-Ts: $(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{"device":"phone-01","version":"1.7.0","uptime":9000}'

메신저봇R (Rhino ES5)

네트워크는 반드시 별도 스레드에서 부르세요. 메인에서 부르면 봇이 멈춥니다.

function callIvy(action, body) {
    var conn = new java.net.URL("https://ibcytb.com/bot/api.php?a=" + action).openConnection();
    conn.setConnectTimeout(8000);
    conn.setReadTimeout(8000);
    conn.setRequestProperty("X-Ivy-Key", API_KEY);
    conn.setRequestProperty("X-Ivy-Ts", String(Math.floor(new Date().getTime() / 1000)));

    if (body) {
        var payload = new java.lang.String(JSON.stringify(body)).getBytes("UTF-8");
        conn.setRequestMethod("POST");
        conn.setDoOutput(true);
        conn.setRequestProperty("Content-Type", "application/json; charset=UTF-8");
        var os = conn.getOutputStream();
        os.write(payload); os.flush(); os.close();
    }

    var code = conn.getResponseCode();
    var br = new java.io.BufferedReader(new java.io.InputStreamReader(
        code >= 400 ? conn.getErrorStream() : conn.getInputStream(), "UTF-8"));
    var sb = new java.lang.StringBuilder(), line;
    while ((line = br.readLine()) !== null) { sb.append(line); }
    br.close();
    conn.disconnect();
    return JSON.parse(String(sb.toString()));
}

파이썬

import json, time, urllib.request

API = "https://ibcytb.com/bot/api.php"
KEY = "ivy_ab12cd.xxxxxxxxxxxx"

def call(action, body=None, **query):
    url = API + "?a=" + action
    for k, v in query.items():
        url += "&" + k + "=" + urllib.parse.quote(str(v))
    data = json.dumps(body, ensure_ascii=False).encode() if body else None
    req = urllib.request.Request(url, data=data, method="POST" if data else "GET")
    req.add_header("X-Ivy-Key", KEY)
    req.add_header("X-Ivy-Ts", str(int(time.time())))
    if data:
        req.add_header("Content-Type", "application/json")
    with urllib.request.urlopen(req, timeout=20) as r:
        return json.loads(r.read().decode())

print(call("ping"))
print(call("room", key="1234567890")["plan"])

도움이 필요하시면

막히는 곳이 있으면 부방장 아이비의 1:1 채팅으로 알려주세요. 키는 절대 다른 사람에게 보내지 마세요. 키가 있으면 플랜을 바꿀 수 있어요.

이 문서는 지금 돌아가는 서버 설정에서 바로 만들어져요. 기능이 늘면 표도 함께 늘어나요.