Getting started

1. Create the bot

1. Open Palloo at app.palloo.app and sign in with your own account.
2. Open Settings and scroll to Bots.
3. Under Create a bot, enter a Bot username (2 to 32 letters, numbers, underscores, periods or hyphens) and, if you like, a Display name. Select Create bot. If your account has two-factor authentication, Palloo asks you to confirm with your second factor first.
4. Palloo shows the bot's token and its Bot ID. Copy the token now and store it somewhere safe, such as a password manager or your host's secret settings. It is shown only this once.

The token is a password. Anyone who has it can act as your bot. If it leaks, or you lose it, select Regenerate token next to the bot: the old token stops working at once. See Authentication.

Each account can own up to 25 bots. Instance admins can turn bot creation off, in which case creating one answers 403 bot_creation_disabled.

Below each bot are three switches that only its owner sees:

• Read message content. Without it, your bot receives messages in servers with an empty content, except its own messages, messages that mention it and direct messages with it. Turn it on only if your bot needs to read conversations.
• Presence intent. Lets the bot receive who is online, idle or on Do Not Disturb in its servers. Off by default.
• Public. Bots are private by default, and only you can add a private bot to a server. A public bot can be added by anyone who can manage a server and knows its ID.

2. Add the bot to a server

You need Manage Server in the server (the API calls it Manage Community).

1. Open the server, open its menu and choose Server settings.
2. In Add a bot, pick your bot under Your bots, or paste its Bot ID.
3. Choose the bot's permissions. For this guide, Send messages is enough. You can only give permissions you have yourself.
4. Select Add bot.

The bot joins with a role named after it that holds exactly those permissions. It can also do everything @everyone can in each channel. You can change the role later like any other; to remove the bot, kick or ban it and its role goes with it. Read more in Permissions.

3. Find a channel ID

Open the channel in Palloo. Its ID is the last part of the address: https://app.palloo.app/servers/<server ID>/channels/<channel ID>.

Your bot can also look IDs up itself: GET /users/@me/communities lists its servers and GET /communities/{id}/channels lists the channels it can see.

4. Send a message

Every request goes to the API at https://api.palloo.app/v1, with the bot token in the Authorization header.

Put the token and channel ID in environment variables so they stay out of your code:

export PALLOO_BOT_TOKEN='palloo_bot_...'
export PALLOO_CHANNEL_ID='01J9ZQ3V5K8M2N4P6R8T0W2Y4N'

First check that the token works. GET /users/@me answers with the bot's own account, where kind is bot:

curl -sS https://api.palloo.app/v1/users/@me \
  -H "Authorization: Bearer $PALLOO_BOT_TOKEN"

Then send a message:

curl -sS -X POST "https://api.palloo.app/v1/channels/$PALLOO_CHANNEL_ID/messages" \
  -H "Authorization: Bearer $PALLOO_BOT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"content": "Hello from my bot!"}'

The answer is 201 Created with the new Message. Everyone who can see the channel receives it at once.

The same in JavaScript

Node.js 18 or newer has fetch built in. Save this as send.mjs and run node send.mjs:

const token = process.env.PALLOO_BOT_TOKEN;
const channelId = process.env.PALLOO_CHANNEL_ID;

const response = await fetch(`https://api.palloo.app/v1/channels/${channelId}/messages`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ content: 'Hello from my bot!' }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${response.status} ${error.code}: ${error.message}`);
}

const message = await response.json();
console.log('Sent message', message.id);

The same in Python

This uses only the standard library. Save it as send.py and run python3 send.py:

import json
import os
import urllib.error
import urllib.request

token = os.environ["PALLOO_BOT_TOKEN"]
channel_id = os.environ["PALLOO_CHANNEL_ID"]

request = urllib.request.Request(
    f"https://api.palloo.app/v1/channels/{channel_id}/messages",
    data=json.dumps({"content": "Hello from my bot!"}).encode(),
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "User-Agent": "my-palloo-bot/1.0",
    },
    method="POST",
)

try:
    with urllib.request.urlopen(request) as response:
        message = json.load(response)
        print("Sent message", message["id"])
except urllib.error.HTTPError as failure:
    error = json.load(failure)["error"]
    print(failure.code, error["code"], error["message"])

If it does not work

Every error has the same shape; see Errors.

Next steps

• Want people to sign in to your website with Palloo instead? Request a Log in with Palloo app; every app is reviewed before it gets a client ID.

• Listen for messages and other events on the gateway.

• Give your bot slash commands.

• Browse everything a bot can do in the API reference.