README.md

Bot API for Ashur

This directory contains Vercel serverless functions for bot management.

Endpoints

• POST /api/bot/create — Create a new bot user and token. Requires a valid Firebase user ID token in the Authorization header.
• POST /api/bot/sendMessage — Send a message as a bot to a user or group chat. Requires a valid bot token in the Authorization header.
• POST /api/bot/readMessages — Read the latest messages from a user or group chat as a bot. Requires a valid bot token in the Authorization header. ...

Environment Variables

• FIREBASE_SERVICE_ACCOUNT_JSON: The contents of your Firebase service account JSON (as a single line, escaped string).
• FIREBASE_DATABASE_URL: Your Firebase Realtime Database URL.

Usage

1. Create a Bot

1. Deploy this directory to Vercel.
2. Set the FIREBASE_SERVICE_ACCOUNT_JSON and FIREBASE_DATABASE_URL environment variables in your Vercel project settings.
3. To create a bot, send a POST request to /api/bot/create with the following JSON body:

   {
     "username": "botusername",
     "name": "Bot Display Name",
     "pic": "https://example.com/bot.png",
     "bio": "I'm a helpful bot!"
   }

   And the header:

   Authorization: Bearer <USER_ID_TOKEN>
   

4. The response will include the bot UID and bot token (show this to the user only once).

2. Send a Message as a Bot

1. To send a message as a bot, send a POST request to /api/bot/sendMessage with the following JSON body:

   {
     "target": "<userUid or groupId>",
     "message": "Hello, world!"
   }

   And the header:

   Authorization: Bot <BOT_TOKEN>
   

2. The endpoint will automatically detect if the target is a group or a direct message and write the message to the appropriate location in the database.
3. The response will be:

   { "success": true }

3. Read Messages as a Bot

1. To read messages as a bot, send a POST request to /api/bot/readMessages with the following JSON body:

   {
     "target": "<userUid or groupId>",
     "limit": 20
   }

   • target: The user UID (for DMs) or group ID (for group chats).
   • limit: (Optional) The maximum number of messages to return (default 20). And the header:

   Authorization: Bot <BOT_TOKEN>
   

2. The endpoint will return the latest messages, sorted oldest to newest:

   {
     "messages": [
       { "id": "msgid1", "sender": "uid", "text": "...", ... },
       ...
     ]
   }

Notes

• The bot token is only shown once at creation. If lost, you must regenerate a new bot.
• Bots can only send/read messages to/from chats and group chats (not posts or comments).
• Only bots with the chat permission can use the sendMessage and readMessages endpoints.