Build a bot

A bot is an app your organization makes. Installed in a workspace, it gets a token. Added to a channel, it can post there and, if you let it, hear the channel’s new messages at a URL you choose. That makes it two-way: a bot can answer a question, react to a deploy message, or keep a thread up to date. A bot’s posts show the app’s name with an APP badge. They never appear under the name of the person who installed it.

A bot that only posts can be simpler as an incoming webhook: one secret URL for one channel, no token. Make a bot when it should post to several channels, reply in threads, or hear what people write.

Make and install a bot

Make an app

In your organization’s settings, open Developer, then the Apps tab, and select New app. Give it the name its posts should show, such as Deploy bot. Organization owners and admins make apps.

Install it in a workspace

Select the app, and under the workspace choose what it can do: Post messages (chat:write), and Hear messages (messages:read) if it should get each new message in its channels. Select Install. Workspace owners and admins install apps.

Copy its token

Mantle shows the bot token once. Store it right away in your bot’s secret manager, for example as MANTLE_BOT_TOKEN.

Add it to channels

In a channel, open the ··· menu and choose Integrations, then Add source. Under Bots, select the app. A bot can only post to, and hear, the channels it has been added to.

To add a bot to a channel, you need to be able to manage the channel: you created it, or you’re a workspace admin or owner.

If you lose the token, open the app on the Developer page and select Rotate token…. The old token stops working at once.

Check the token

GET /v1/me answers with the app, its workspace, and what it may do. Every request sends the token as a bearer token:

curl https://api.mantle.chat/v1/me \
  -H "Authorization: Bearer $MANTLE_BOT_TOKEN"

{
  "app": { "id": "4d2c…", "name": "Deploy bot" },
  "installationId": "9a1e…",
  "workspaceId": "b7f3…",
  "userId": "app-bot:9a1e…",
  "scopes": ["chat:write", "messages:read"]
}

userId is the id the bot’s own posts carry as their author. GET /v1/channels lists the channels it has been added to, as { "data": [{ "id", "name", "archived" }] }.

Post a message

Send a POST to /v1/channels/{channelId}/messages with a JSON body that has a text field:

curl -X POST "https://api.mantle.chat/v1/channels/$CHANNEL_ID/messages" \
  -H "Authorization: Bearer $MANTLE_BOT_TOKEN" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: deploy-1042-finished' \
  -d '{"text":"Deploy 1042 finished"}'

import { MantleBotClient } from '@mantlechat/sdk';

const bot = new MantleBotClient({ token: process.env.MANTLE_BOT_TOKEN });

await bot.messages.post(channelId, {
  text: 'Deploy 1042 finished',
  idempotencyKey: 'deploy-1042-finished',
});

Field	Required	What it does
`text`	Yes	The message, in Mantle’s markdown. Up to 40,000 characters.
`threadKey`	No	Posts that share a key go into one thread. The first post with a new key starts it. 1–200 characters.
`replyToMessageId`	No	Replies in that message’s thread. Not with `threadKey`.

An Idempotency-Key header makes a retry safe: a repeat of the key answers with the first post and posts nothing new. A post that went through answers 200:

{ "messageId": "6f0c…", "duplicate": false, "threadRootMessageId": "2b8d…" }

duplicate is true when the request repeated an earlier Idempotency-Key. threadRootMessageId is there when the post went into a thread. The markdown follows the incoming webhooks rules: mentions don’t notify anyone, images show as links, and HTML shows as text.

Hear messages

A bot installed with Hear messages gets a message.created event for each new message in its channels, signed so it can tell the event came from Mantle.

Give it an event URL

Open the app on the Developer page and, under Events, enter a public https:// URL on port 443. Select Save event URL.

Copy its signing secret

Mantle shows the signing secret once. Store it next to the token, for example as MANTLE_WEBHOOK_SECRET.

Send a test event

Select Send test event. Mantle sends an app.test event and shows how your URL answered.

Each event is a POST with a JSON body:

{
  "schemaVersion": "mantle-webhook-event.v1",
  "id": "c3f1…",
  "type": "message.created",
  "version": 1,
  "occurredAt": "2026-10-19T12:00:00Z",
  "workspaceId": "b7f3…",
  "data": {
    "message": {
      "id": "6f0c…",
      "channelId": "0d9e…",
      "threadRootMessageId": null,
      "text": "Can someone ship the hotfix?",
      "createdAt": "2026-10-19T12:00:00.123Z",
      "author": { "kind": "person", "id": "user_01J…", "name": "Ada Lovelace" }
    }
  }
}

threadRootMessageId is the message whose thread this one is in, or null for a message in the channel itself.
author.kind is person or app. author is null once the author’s account is gone.
A bot never gets its own posts. It does get other apps’ posts, so a bot that answers bots should make sure two of them can’t answer each other forever.
Agent replies, Linear, Stripe and Notion posts, and direct messages aren’t sent. Incoming webhooks’ posts are, as an app’s.
The text is read when the event is sent: a message edited first is sent as it is then, and one deleted first isn’t sent.

Answer with any 2xx within 10 seconds. Do slow work after you answer.

Check the signature

Every event has these headers:

Header	What it holds
`mantle-webhook-id`	The event’s id, the same as the body’s `id`
`mantle-webhook-timestamp`	When it was signed, in Unix seconds
`mantle-webhook-signature`	`v1=` and an HMAC-SHA256, in hex, of `{timestamp}.{id}.{body}`
`mantle-webhook-event`	The event’s type, such as `message.created`

Check the signature against the exact body you received, before parsing it, and refuse events more than 5 minutes old. The SDK does all of this:

import { verifyAndParseMantleWebhookEvent } from '@mantlechat/sdk';

const event = await verifyAndParseMantleWebhookEvent({
  eventId: request.headers.get('mantle-webhook-id'),
  timestamp: Number(request.headers.get('mantle-webhook-timestamp')),
  signature: request.headers.get('mantle-webhook-signature'),
  rawBody: await request.text(),
  secret: process.env.MANTLE_WEBHOOK_SECRET,
});

import hashlib
import hmac
import os
import time

def verify(headers, raw_body: bytes) -> bool:
    timestamp = headers["mantle-webhook-timestamp"]
    event_id = headers["mantle-webhook-id"]
    if abs(time.time() - int(timestamp)) > 300:
        return False
    signed = f"{timestamp}.{event_id}.".encode() + raw_body
    expected = hmac.new(os.environ["MANTLE_WEBHOOK_SECRET"].encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"v1={expected}", headers["mantle-webhook-signature"])

A small echo bot

This bot answers “pong” in the thread of any message that says “ping”. It runs on Bun: save it as bot.js, set the two environment variables, and run bun bot.js. Then use its public https:// address as the event URL.

import { MantleBotClient, verifyAndParseMantleWebhookEvent } from '@mantlechat/sdk';

const bot = new MantleBotClient({ token: process.env.MANTLE_BOT_TOKEN });

export default {
  async fetch(request) {
    let event;
    try {
      event = await verifyAndParseMantleWebhookEvent({
        eventId: request.headers.get('mantle-webhook-id') ?? '',
        timestamp: Number(request.headers.get('mantle-webhook-timestamp')),
        signature: request.headers.get('mantle-webhook-signature') ?? '',
        rawBody: await request.text(),
        secret: process.env.MANTLE_WEBHOOK_SECRET,
      });
    } catch {
      return new Response('Not from Mantle', { status: 401 });
    }

    if (event.type === 'message.created') {
      const { message } = event.data;
      if (message.author?.kind === 'person' && /\bping\b/i.test(message.text)) {
        await bot.messages.post(message.channelId, {
          text: 'pong',
          replyToMessageId: message.id,
          // The event's id, so a retried event answers once.
          idempotencyKey: event.id,
        });
      }
    }
    return new Response(null, { status: 204 });
  },
};

Retries and pausing

An event that fails is sent again after 10 seconds, 1 minute, 5 minutes, and 30 minutes. After the fifth failure, Mantle gives up on it.

Retried: network errors, timeouts, and the answers 408, 409, 425, 429, and any 5xx.
Not retried: any other 4xx, and a URL that isn’t a public https:// address.

If a bot’s events keep failing for an hour, they pause. The app’s page on the Developer page says so. Fix the receiver, send a test event, then select Resume events. Messages posted while events were paused aren’t sent.

Errors

A refused request answers with an error body:

{ "error": { "code": "not_in_channel", "message": "…", "requestId": "…" } }

Status	`code`	What happened	What to do
`400`	`invalid_request`	The body isn’t valid, or has both `threadKey` and `replyToMessageId`	Fix the body
`400`	`empty_text`	`text` is empty or only spaces	Send some text
`400`	`text_too_long`	`text` is over 40,000 characters	Shorten it or split it
`400`	`invalid_thread_key`	`threadKey` is empty or over 200 characters	Use a shorter key
`401`	`invalid_token`	The token is wrong, was rotated, or the app was uninstalled or deleted	Use the current token
`403`	`app_paused`	The app is paused in its workspace	Ask an admin to install it again
`403`	`insufficient_scope`	It wasn’t installed with Post messages	Install it again with that permission
`403`	`not_in_channel`	It hasn’t been added to the channel	Add it in the channel’s Integrations
`403`	`workspace_not_enabled`	The Mantle API is turned off for the workspace	Contact us
`404`	`channel_not_found`	No such channel	Check the channel’s id
`404`	`message_not_found`	`replyToMessageId` isn’t a message in the channel	Check the message’s id
`409`	`channel_archived`	The channel is archived	Unarchive it, or post somewhere else
`429`	`rate_limited`	Too many requests in the last minute	Wait for the seconds in `Retry-After`
`503`	`service_unavailable`	Mantle couldn’t answer just then	Retry in a moment
`500`	`post_failed`	Mantle couldn’t save the post	Retry with the same `Idempotency-Key`

Limits

Limit	Value
Requests per bot	60 a minute
Requests per workspace, in total	600 a minute
Message text	40,000 characters
App name	80 characters
Event answer	10 seconds
Events kept for retries	3 days

Manage a bot

Open the app on the Developer page.

Rotate token… issues a new token; the old one stops working at once.
Change URL points its events somewhere else, with the same signing secret. Rotate signing secret… issues a new one, and Stop events… stops sending it messages.
Uninstall… removes it from the workspace: its token stops working and it leaves its channels. Its posts stay.
Delete app uninstalls it everywhere.

If the person who installed a bot leaves the workspace, the bot pauses: its requests answer 403 app_paused. A workspace admin can select Install again to give it a new token. To take a bot out of one channel, open the channel’s Integrations, select the bot, and choose Remove from channel. The person who added it, or a workspace admin, can.

Keep the token secret

Anyone with the token can post as the bot in its channels. Anyone with the signing secret could send your bot events that look like Mantle’s. Store both as secrets, never in a repository or a shared document. If either leaks, rotate it.

The token can’t read a channel’s history or anything else in your workspace; a bot hears only the events Mantle sends it.

Incoming webhooks

Post into one channel with a secret URL, no token.

Channels

Create channels and decide who can manage them.

Start here

Chat and collaborate

Knowledge and organization

Agents and automation

Integrations

Integration guides

Manage Mantle

Make and install a bot

Check the token

Post a message

Hear messages

Check the signature

A small echo bot

Retries and pausing

Errors

Limits

Manage a bot

Keep the token secret

Incoming webhooks

Channels

​Make and install a bot

​Check the token

​Post a message

​Hear messages

​Check the signature

​A small echo bot

​Retries and pausing

​Errors

​Limits

​Manage a bot

​Keep the token secret

Incoming webhooks

Channels

Make and install a bot

Check the token

Post a message

Hear messages

Check the signature

A small echo bot

Retries and pausing

Errors

Limits

Manage a bot

Keep the token secret