Skip to content

Bot reference

Where to find the full SDK APIs, every limit in one table, and the error codes a bot can get from the Morsel API.

SDKs

The SDK READMEs are the full API reference:

To report a vulnerability, see SECURITY.md.

Under the hood, a bot uses the same chat endpoints as any wallet, signed with its own key using the MorselWallet2 scheme. A signature is good for 5 minutes either side of the server's clock, and a write's signature is accepted once. Raw calls are open to you with bot.api.call(method, path), signed for you.

Limits

WhatLimit
Bots per wallet20, and 5 new ones a day
Username5 to 32 characters, a-z 0-9 _, starts with a letter, no __, ends in bot
Name, about, description1 to 40, up to 120, up to 512 characters
CommandsUp to 100. Command 1 to 32 characters, description 1 to 256
PicturePNG, JPEG or WebP, up to 1 MB, 32 to 8000 pixels a side, 10 uploads an hour
Message text1000 characters, up to 100 formatting entities
Inline keyboard8 rows of 8, 64 buttons. Label 1 to 64 characters, callback data 1 to 64 bytes, copy text up to 256
Reply keyboard12 rows of 4 labels, label 1 to 64 characters, placeholder up to 64
Answer to a pressOnce, text up to 200 characters
Sending30 messages a second, a burst of 5 then about 1 a second per chat, 20 a minute per group
Edits48 hours, 100 edits a message
GroupsUp to 5000 per bot
InlineAnswer within 30 seconds, up to 50 results, cache up to 300 seconds, next offset up to 64 characters
Inline queries5 a second per person, 200 a second per bot, kept a minute for catch-up
Start payload1 to 64 characters, A-Z a-z 0-9 _ -
Webhookhttps, public host, URL up to 512 characters, secret 16 to 128 characters, 5 seconds to answer, retries for 24 hours

Errors

Every error is JSON: { "success": false, "error": "<CODE>", "message": "..." }. A 429 also carries retryAfter in seconds and a Retry-After header. The SDKs raise MorselApiError (TypeScript) or ApiError (Python) with status and code.

StatusCodeWhen
400BAD_USERNAME, RESERVEDThe username breaks the rules, or contains a reserved word.
400BAD_NAME, BAD_ABOUT, BAD_DESCRIPTION, BAD_AVATAR, BAD_COMMANDS, BAD_URL, BAD_SECRET, ...A field is out of its limits.
400BOT_NOT_ADMINSomeone tried to make a bot a group admin.
401UNAUTHORIZED, REPLAYEDThe signature is missing, wrong, stale or reused.
401BOT_REVOKEDThe token was regenerated, or the bot deleted. The SDK stops.
401BOT_AUTH_V2Signed with an old signature version. Update the SDK.
403BOT_SUSPENDEDMorsel suspended the bot.
403BOT_FORBIDDENA route bots may not call, like managing a group.
403BOT_CANNOT_INITIATEThat person never wrote to the bot.
403BLOCKEDThat person stopped the bot.
403BOT_TO_BOTBots can't write to bots.
404NOT_FOUNDUnknown, suspended, or not yours.
409USERNAME_TAKEN, ADDRESS_IN_USE, TOO_MANY_BOTSCreating a bot.
409EDIT_WINDOWThe message is older than 48 hours. The body has windowSeconds.
409INLINE_OFF, DUPLICATE, ANSWEREDInline mode is off, a query id was reused, or a query or press was already answered.
410BOT_MOVEDA message to a bot's old address. The body's address is the current one.
410BOT_GONEThe bot was deleted.
410EXPIREDAn inline answer after 30 seconds.
413TOO_LARGE, AVATAR_TOO_LARGEA message or a picture is over its limit.
415UNSUPPORTED_IMAGEA picture that isn't PNG, JPEG or WebP.
422IMAGE_TOO_SMALL, IMAGE_TOO_LARGE, BAD_IMAGEA picture's size, or a file that can't be read.
429BOT_RATE_LIMIT, SLOW_DOWNToo many messages or requests. Wait retryAfter.
503UNAVAILABLE, WEBHOOKS_OFFThe service is unavailable, or webhooks are off on the server.

Events your bot receives

EventSDK updateCarries
A message from a personmessage, or editedSender, chat, text, entities, media, reply, language
A button presscallbackData, the message pressed
A payment in a messagepayment or payment_failedAfter the on-chain check
bot_blocked, bot_unblockedblocked, unblockedThe person
bot_added, bot_removedbot_added, bot_removedThe group, and the manager
inline_queryinline_queryQuery, offset, sender, language
A chosen inline resultchosen_inline in TypeScript, inline_chosen in PythonQuery id, result id

Try one of these