Bot API Overview

At its core, you can think of the SafeW Bot API as software that provides JSON-encoded responses to your queries.

A bot, on the other hand, is essentially a routine, software or script that queries the API by means of an HTTPS request and waits for a response. There are several types of requests you can make, as well as many different objects that you can use and receive as responses.

Obtain Your Bot Token

In this context, a token is a string that authenticates your bot (not your account) on the bot API. Each bot has a unique token which can also be revoked at any time via @BotFather.

Obtaining a token is as simple as contacting @BotFather, issuing the /newbot command and following the steps until you're given a new token. You can find a step-by-step guide here.

Your token will look something like this:

4839574812:AAFD39kkdpWt3ywyRZergyOLMaJhac60qc

Making Requests

All requests are authenticated via the token in the URL, using the following format:

https://api.safew.org/bot<YOUR_BOT_TOKEN>/methodName

Since your browser is capable of sending HTTPS requests, you can use it to quickly try out the API. After obtaining your token, try pasting this string into your browser:

https://api.safew.org/bot<YOUR_BOT_TOKEN>/getMe

In theory, you could interact with the API with basic requests like this, either via your browser or other tailor-made tools like cURL. While this can work for simple requests like the example above, it's not practical for larger applications and doesn't scale well.

Request data is formatted as JSON. File uploads use multipart/form-data.

Standard Response Format

Success Response

{
  "ok": true,
  "result": {
    ...
  }
}

Error Response

{
  "ok": false,
  "error_code": 400,
  "description": "Bad Request: ...",
  "trace_id": "abc123"
}

Common Error Codes

Code	Description
400	Bad request parameters
401	Invalid or expired token
403	Bot does not have permission to perform this action
404	Method not found or resource does not exist
429	Too many requests, rate limit triggered
500	Internal server error

Available Methods

Basic Methods

Method	Description	HTTP Method
getMe	Get basic Bot information	GET / POST
getUpdates	Long polling to get updates	GET / POST

Sending Messages

Method	Description	HTTP Method
sendMessage	Send a text message	POST
sendPhoto	Send a photo	POST
sendVideo	Send a video	POST
sendVoice	Send a voice message	POST
sendAudio	Send an audio file	POST
sendDocument	Send a document	POST
sendMediaGroup	Send a media group	POST

Editing Messages

Method	Description	HTTP Method
editMessageText	Edit message text	POST
editMessageReplyMarkup	Edit message reply markup	POST

File Upload Notes

The following methods support file uploads and require multipart/form-data encoding:

• sendPhoto - Photo file, max 10MB
• sendVideo - Video file
• sendVoice - Voice file
• sendAudio - Audio file
• sendDocument - Document file, max 100MB
• sendMediaGroup - Media group, max 10 files

In addition to uploading files directly, you can also pass a file_id of a previously uploaded file to reuse it.