MoMoTalk Bot Developer Guide | 봇 개발 가이드

Last updated: 2026-06-07

Bot API base: https://bot.mmrnd.net/api · Console: https://mmrnd.net/

Webhook callback HMAC signature Bot token Room messages

English

The MoMoTalk Bot Platform lets approved developers, operators, and admins register external services as chat bots. MoMoTalk sends room events to your callback URL, and your service can answer by calling the bot message API with its bot token.

1. Create a bot

  1. Sign in to the main console with developer, operator, or admin access.
  2. Open the Bot Platform card.
  3. Enter a HTTPS callback URL. The platform sends webhook events to this URL.
  4. Store the returned bot_token. It is shown only once.
  5. Use the webhook test button before exposing the bot to users.

Bot visibility

Value Meaning Typical use
private Only the owner/operator can manage or test the bot. Initial development, internal testing.
unlisted The bot is not shown in a public directory, but can be added through a direct reference or operator flow. Partner pilots, limited release.
public The bot is ready to be listed for users after app-side directory support is enabled. General user-facing bots.
review_required The bot should remain pending until an operator reviews safety, callback behavior, and policy fit. New 3rd-party submissions.

Webhook event example

When a subscribed room receives a user message, MoMoTalk sends a JSON body like this to the bot callback URL. The request includes X-MoMoTalk-Bot-Id, X-MoMoTalk-Event-Id, and X-MoMoTalk-Bot-Signature. 

{
  "event_id": "evt_...",
  "event_type": "talk.message_created",
  "bot_id": "bot_...",
  "timestamp": 1780833600,
  "message": {
    "room_id": 123,
    "message_id": 456,
    "sender_user_id": "user_...",
    "body": "hello",
    "message_type": "TEXT",
    "created_at": 1780833600
  }
}

Verify the webhook signature

The signature is an HMAC-SHA256 hex digest over the raw request body using the bot webhook secret. Keep the secret on your server and never put it in a mobile or browser client. 

import crypto from "node:crypto";
import express from "express";

const app = express();
const webhookSecret = process.env.MOMOTALK_WEBHOOK_SECRET;
const botToken = process.env.MOMOTALK_BOT_TOKEN;
const botId = process.env.MOMOTALK_BOT_ID;

app.use(express.raw({ type: "application/json" }));

app.post("/momotalk/webhook", async (req, res) => {
  const expected = crypto
    .createHmac("sha256", webhookSecret)
    .update(req.body)
    .digest("hex");
  const actual = req.get("X-MoMoTalk-Bot-Signature") || "";
  const expectedBytes = Buffer.from(expected, "hex");
  const actualBytes = Buffer.from(actual, "hex");
  if (actualBytes.length !== expectedBytes.length || !crypto.timingSafeEqual(expectedBytes, actualBytes)) {
    return res.status(401).send("invalid signature");
  }

  const event = JSON.parse(req.body.toString("utf8"));
  if (event.event_type === "talk.message_created") {
    await fetch(`https://bot.mmrnd.net/api/bots/${botId}/messages`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${botToken}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        room_id: event.message.room_id,
        reply_to_message_id: event.message.message_id,
        body: `Echo: ${event.message.body}`,
        metadata: { source: "example" }
      })
    });
  }

  res.json({ ok: true });
});

app.listen(3000);

Send a bot message with curl

curl -X POST "https://bot.mmrnd.net/api/bots/bot_xxx/messages" \
  -H "Authorization: Bearer bot_token_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "room_id": 123,
    "reply_to_message_id": 456,
    "body": "Thanks. I received your message.",
    "metadata": { "intent": "ack" }
  }'

Operational notes

한국어

MoMoTalk Bot Platform은 승인된 개발자, 운영자, 관리자가 외부 서비스를 채팅 봇으로 등록할 수 있게 해줍니다. MoMoTalk은 채팅방 이벤트를 봇의 콜백 URL로 보내고, 봇 서버는 bot token으로 메시지 API를 호출해 답장할 수 있습니다.

1. 봇 생성

  1. developer, operator, admin 권한으로 main 콘솔에 로그인합니다.
  2. Bot Platform 카드를 엽니다.
  3. HTTPS 콜백 URL을 입력합니다. 플랫폼은 이 URL로 웹훅 이벤트를 보냅니다.
  4. 생성 응답의 bot_token을 저장합니다. 토큰은 한 번만 표시됩니다.
  5. 사용자에게 노출하기 전에 웹훅 테스트 버튼으로 콜백 동작을 확인합니다.

Bot visibility 의미

값 의미 권장 용도
private 소유자와 운영자만 관리/테스트할 수 있는 상태입니다. 초기 개발, 내부 테스트.
unlisted 공개 디렉터리에는 표시하지 않지만 직접 참조나 운영자 흐름으로 추가할 수 있는 상태입니다. 파트너 파일럿, 제한 공개.
public 앱의 봇 디렉터리 기능이 활성화되면 사용자에게 노출할 수 있는 상태입니다. 일반 사용자 대상 봇.
review_required 안전성, 콜백 동작, 정책 적합성을 운영자가 검토하기 전까지 대기시키는 상태입니다. 신규 3rd-party 등록.

구현 흐름

  1. 봇 서버에서 POST /momotalk/webhook 같은 콜백 엔드포인트를 준비합니다.
  2. X-MoMoTalk-Bot-Signature를 검증합니다.
  3. talk.message_created 이벤트가 들어오면 필요한 로직을 수행합니다.
  4. POST /bots/{bot_id}/messages를 bot token으로 호출해 채팅방에 답장합니다.
  5. 콘솔의 최근 전달 목록에서 실패 여부를 확인합니다.

주의 사항