Bot API

Bot API allows you to create bots for the WWChat messenger. The API is similar to Telegram Bot API.

Getting Started

Base URL

https://api.wwchat.org/bot/v1/{token}/ 

Authentication

The bot authenticates using a token in the URL. The token is issued when creating a bot.

Token format: {user_id}:{random_string}

Example: 550e8400-e29b-41d4-a716-446655440000:aB3dE5fG7hJ9kL1mN3pQ5rS7tU9vW1xY3zA5bC7dE9fG1

Creating a Bot

Via @BotMama:

1. Open a chat with @BotMama
2. Send the command /newbot
3. Enter the bot name
4. Enter username (must end with bot)
5. Receive your token

Response Format

All methods return JSON:

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

On error:

{
  "ok": false,
  "error_code": 400,
  "description": "Error message"
}

API Methods

getMe

Get information about the bot.

Request: GET /bot/v1/{token}/getMe

{
  "ok": true,
  "result": {
    "id": "uuid",
    "username": "MyBot",
    "description": "Bot description",
    "is_bot": true,
    "can_join_groups": true
  }
}

sendMessage

Send a message.

Request: POST /bot/v1/{token}/sendMessage

Example with inline keyboard:

{
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "text": "Choose an action:",
  "reply_markup": {
    "inline_keyboard": [
      [
        {"text": "Button 1", "callback_data": "btn1"},
        {"text": "Button 2", "callback_data": "btn2"}
      ],
      [
        {"text": "Open website", "url": "https://example.com"}
      ]
    ]
  }
}

getUpdates

Get updates (long polling).

Request: GET /bot/v1/{token}/getUpdates

Important: After receiving updates, send the next request with offset = last_update_id + 1 to confirm receipt.

editMessageText

Edit message text.

Request: POST /bot/v1/{token}/editMessageText

answerCallbackQuery

Respond to inline button press.

Request: POST /bot/v1/{token}/answerCallbackQuery

Important: Call this method even if you don't need to show a notification.

Webhooks

setWebhook

Set webhook for receiving updates.

Request: POST /bot/v1/{token}/setWebhook

deleteWebhook

Request: POST /bot/v1/{token}/deleteWebhook

getWebhookInfo

Request: GET /bot/v1/{token}/getWebhookInfo

Webhook Request Format

POST https://mybot.example.com/webhook
Content-Type: application/json
X-WWChat-Bot-Api-Secret-Token: my_secret_123

{
  "update_id": 123456789,
  "message": { ... }
}

Your server must return HTTP 200 OK.

Object Types

Update

{
  "update_id": 123456789,
  "message": { ... },        // new message
  "callback_query": { ... }  // inline button press
}

Message

{
  "message_id": "uuid",
  "from": { "id": "uuid", "username": "john", "is_bot": false },
  "chat": { "id": "uuid", "type": "private" },
  "date": 1705123456,
  "text": "Hello",
  "entities": [ ... ],
  "reply_markup": { ... }
}

CallbackQuery

{
  "id": "unique_callback_id",
  "from": { "id": "uuid", "username": "john" },
  "message": { ... },
  "data": "btn1"  // button callback_data
}

InlineKeyboardMarkup

{
  "inline_keyboard": [
    [
      { "text": "Button", "callback_data": "btn1" }
    ],
    [
      { "text": "Website", "url": "https://example.com" }
    ]
  ]
}

User

Chat

Examples

Python

import requests
import time

TOKEN = "550e8400-...:aB3dE5fG7h..."
BASE_URL = f"https://api.wwchat.org/bot/v1/{TOKEN}"

def get_updates(offset=None):
    params = {"timeout": 30}
    if offset:
        params["offset"] = offset
    return requests.get(f"{BASE_URL}/getUpdates", params=params).json()

def send_message(chat_id, text):
    return requests.post(f"{BASE_URL}/sendMessage", json={
        "chat_id": chat_id,
        "text": text
    }).json()

def main():
    offset = None
    print("Bot started!")

    while True:
        result = get_updates(offset)

        if not result.get("ok"):
            time.sleep(5)
            continue

        for update in result.get("result", []):
            offset = update["update_id"] + 1

            if "message" in update:
                msg = update["message"]
                chat_id = msg["chat"]["id"]
                text = msg.get("text", "")

                if text.startswith("/start"):
                    send_message(chat_id, "Hello! I'm a WWChat bot.")
                else:
                    send_message(chat_id, f"You wrote: {text}")

if __name__ == "__main__":
    main()

Limits

• Long polling timeout: max 60 seconds
• Updates limit: max 100 per request
• Webhook URL: HTTPS only
• Max 20 bots per user
• Bot username is reserved forever (even after deletion)

System Bots

@BotMama

System bot for creating and managing bots:

• /newbot — create a new bot
• /mybots — list my bots
• /deletebot — delete a bot
• /token — get a new token