커뮤니티를 운영하거나 프로젝트 진행 상황을 관리하거나 구독자에게 정기적으로 콘텐츠를 보내야 한다면 수동 작업은 시간이 많이 걸리고 번거롭습니다. Potato가 제공하는 Bot API는 이런 반복 작업을 봇에게 맡겨 팀이 더 가치 있는 일에 집중할 수 있게 해줍니다. 이 글에서는 실제 시나리오를 통해 기본 사용법을 알아봅니다.
Bot API로 할 수 있는 일: 세 가지 대표 시나리오
봇이 자동 응답만 하는 것은 아닙니다. 아래 사용법은 팀과 크리에이터 사이에서 흔히 볼 수 있습니다:
- 정기 푸시 및 알림: 예를 들어 매주 월요일 오전 9시에 프로젝트 그룹에 할 일 목록을 보내거나, 수업 시작 30분 전에 수강생에게 개인 메시지로 알림을 보냅니다.
- 데이터 조회 및 피드백: 멤버가 그룹에서 “/status”를 입력하면 봇이 현재 작업 완료율을 반환하고, 크리에이터는 “/stats”로 어제 새로 추가된 구독자 수를 확인합니다.
- 콘텐츠 배포 및 수집: 봇이 새 글을 여러 채널에 자동으로 전달하거나, 사용자가 제출한 링크와 이미지를 수집해 표로 정리합니다.
이러한 작업의 이면에는 모두 같은 논리가 있습니다: 메시지 이벤트를 수신하고 API를 호출해 동작을 실행합니다. Potato의 Bot API는 HTTPS 요청을 기반으로 하며 JSON 데이터를 반환하므로 어떤 언어로도 연동할 수 있습니다.
처음부터 시작하기: Token 발급 및 첫 메시지 보내기
먼저 Potato에서 @BotFather를 검색해 봇을 만들면 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 같은 Token을 받습니다. 이 Token은 봇의 비밀번호와 같으니 유출하지 마세요.
메시지를 보내는 인터페이스는 https://api.potato.im/bot{token}/sendMessage이며, chat_id(대상 대화 ID)와 text(메시지 내용) 두 가지 매개변수가 필요합니다. curl로 테스트해 보세요:
curl -X POST https://api.potato.im/bot/sendMessage -d "chat_id=123456789&text=Hello"
{"ok":true}가 반환되면 봇이 메시지를 성공적으로 보낸 것입니다. 단, 봇은 먼저 자신과 대화한 사용자나 속한 그룹에만 메시지를 보낼 수 있으며, 모르는 사람에게 마음대로 메시지를 보낼 수 없습니다.
사용자 입력 처리: Webhook으로 업데이트 받기
봇이 사용자 메시지에 응답하게 하려면 폴링(getUpdates) 또는 Webhook 두 가지 방식이 있습니다. 폴링은 로컬 테스트에, Webhook은 온라인 서비스에 적합합니다. Webhook 설정은 한 번만 호출하면 됩니다:
curl -X POST https://api.potato.im/bot/setWebhook -d "url=https://yourdomain.com/potato-webhook"
이후 사용자가 봇에게 보내는 모든 메시지는 POST 요청으로 서버에 푸시됩니다. JSON의 message.text와 message.chat.id를 파싱하면 무엇을 답할지 결정할 수 있습니다. 흔한 함정 하나는 Webhook이 반드시 HTTPS를 사용해야 하고 인증서가 유효해야 한다는 점입니다. 그렇지 않으면 Potato가 푸시를 거부합니다.
속도 제한과 실용적인 조언
Potato는 봇 메시지 전송에 속도 제한이 있습니다: 단일 봇이 동일 대화에 초당 최대 1개 메시지, 전체적으로 초당 30개를 넘을 수 없습니다. 초과하면 인터페이스가 429 오류를 반환하며 retry_after초 후에 재시도해야 합니다. 대량 푸시 시에는 사용자를 소그룹으로 나누고 각 그룹 간격을 1초로 두어 제한을 피하는 것이 좋습니다.
또한 봇은 그룹의 과거 메시지를 읽을 수 없고 Webhook 설정 이후의 새 메시지만 받을 수 있습니다. 데이터를 영구 저장해야 한다면 자체 데이터베이스를 준비해 chat_id, 사용자 입력, 타임스탬프를 저장하세요.
크리에이터에게 매우 유용한 자동화 하나는 RSS 피드의 새 글을 Potato 채널에 자동 전달하는 것입니다. 10분마다 피드를 확인하고 새 링크가 있으면 sendMessage를 호출하는 정기 스크립트를 작성하세요. 전체 과정은 50줄 미만의 코드로, 매일 수동으로 복사해 붙여넣는 번거로움을 덜어줍니다.
팀 협업 측면에서는 간단한 당직 봇을 만들 수 있습니다: 멤버가 “/oncall”로 출근 체크를 하면 봇이 시간을 기록하고 응답 시간을 계산합니다. 이 데이터가 쌓이면 교대 근무 최적화에 도움이 됩니다.
아직 Potato의 봇 기능을 사용해 보지 않았다면 매일 정해진 시간에 날씨 알림을 보내는 것 같은 최소한의 요구부터 시작해 보세요. 인터페이스에 익숙해지면 점차 확장할 수 있습니다. Potato의 Bot API 문서는 공식 웹사이트에서 자세한 매개변수 설명을 제공하며, 문제가 있으면 공식 커뮤니티에 질문할 수도 있습니다.
