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:
- TypeScript,
@morsel/bot: typescript/README.md, with runnable bots in typescript/examples. - Python,
morsel-bot: python/README.md, with runnable bots in python/examples. - Both SDKs, and the app, replay the same test vectors in vectors, so they agree byte for byte on keys, encryption, payloads and signatures.
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
| What | Limit |
|---|---|
| Bots per wallet | 20, and 5 new ones a day |
| Username | 5 to 32 characters, a-z 0-9 _, starts with a letter, no __, ends in bot |
| Name, about, description | 1 to 40, up to 120, up to 512 characters |
| Commands | Up to 100. Command 1 to 32 characters, description 1 to 256 |
| Picture | PNG, JPEG or WebP, up to 1 MB, 32 to 8000 pixels a side, 10 uploads an hour |
| Message text | 1000 characters, up to 100 formatting entities |
| Inline keyboard | 8 rows of 8, 64 buttons. Label 1 to 64 characters, callback data 1 to 64 bytes, copy text up to 256 |
| Reply keyboard | 12 rows of 4 labels, label 1 to 64 characters, placeholder up to 64 |
| Answer to a press | Once, text up to 200 characters |
| Sending | 30 messages a second, a burst of 5 then about 1 a second per chat, 20 a minute per group |
| Edits | 48 hours, 100 edits a message |
| Groups | Up to 5000 per bot |
| Inline | Answer within 30 seconds, up to 50 results, cache up to 300 seconds, next offset up to 64 characters |
| Inline queries | 5 a second per person, 200 a second per bot, kept a minute for catch-up |
| Start payload | 1 to 64 characters, A-Z a-z 0-9 _ - |
| Webhook | https, 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.
| Status | Code | When |
|---|---|---|
| 400 | BAD_USERNAME, RESERVED | The username breaks the rules, or contains a reserved word. |
| 400 | BAD_NAME, BAD_ABOUT, BAD_DESCRIPTION, BAD_AVATAR, BAD_COMMANDS, BAD_URL, BAD_SECRET, ... | A field is out of its limits. |
| 400 | BOT_NOT_ADMIN | Someone tried to make a bot a group admin. |
| 401 | UNAUTHORIZED, REPLAYED | The signature is missing, wrong, stale or reused. |
| 401 | BOT_REVOKED | The token was regenerated, or the bot deleted. The SDK stops. |
| 401 | BOT_AUTH_V2 | Signed with an old signature version. Update the SDK. |
| 403 | BOT_SUSPENDED | Morsel suspended the bot. |
| 403 | BOT_FORBIDDEN | A route bots may not call, like managing a group. |
| 403 | BOT_CANNOT_INITIATE | That person never wrote to the bot. |
| 403 | BLOCKED | That person stopped the bot. |
| 403 | BOT_TO_BOT | Bots can't write to bots. |
| 404 | NOT_FOUND | Unknown, suspended, or not yours. |
| 409 | USERNAME_TAKEN, ADDRESS_IN_USE, TOO_MANY_BOTS | Creating a bot. |
| 409 | EDIT_WINDOW | The message is older than 48 hours. The body has windowSeconds. |
| 409 | INLINE_OFF, DUPLICATE, ANSWERED | Inline mode is off, a query id was reused, or a query or press was already answered. |
| 410 | BOT_MOVED | A message to a bot's old address. The body's address is the current one. |
| 410 | BOT_GONE | The bot was deleted. |
| 410 | EXPIRED | An inline answer after 30 seconds. |
| 413 | TOO_LARGE, AVATAR_TOO_LARGE | A message or a picture is over its limit. |
| 415 | UNSUPPORTED_IMAGE | A picture that isn't PNG, JPEG or WebP. |
| 422 | IMAGE_TOO_SMALL, IMAGE_TOO_LARGE, BAD_IMAGE | A picture's size, or a file that can't be read. |
| 429 | BOT_RATE_LIMIT, SLOW_DOWN | Too many messages or requests. Wait retryAfter. |
| 503 | UNAVAILABLE, WEBHOOKS_OFF | The service is unavailable, or webhooks are off on the server. |
Events your bot receives
| Event | SDK update | Carries |
|---|---|---|
| A message from a person | message, or edited | Sender, chat, text, entities, media, reply, language |
| A button press | callback | Data, the message pressed |
| A payment in a message | payment or payment_failed | After the on-chain check |
bot_blocked, bot_unblocked | blocked, unblocked | The person |
bot_added, bot_removed | bot_added, bot_removed | The group, and the manager |
inline_query | inline_query | Query, offset, sender, language |
| A chosen inline result | chosen_inline in TypeScript, inline_chosen in Python | Query id, result id |