Quickstart: your first bot

In about ten minutes you will have an application, a bot with a token, the bot sitting in a server of your own, and a program that calls the API as that bot.

What you need

A Moymo account with a verified e-mail address, the Moymo for Windows app (a server is made and used there), and Node.js 20 or newer for the last step. Any language that can make an HTTPS request works the same way; the examples use curl and JavaScript.

1. Make an application

1. Open the Developer Portal and choose Continue with Moymo. The portal signs you in with your Moymo account; it never sees your password.
2. Choose New application, give it a name (for example Dice Roller) and make it.

The application starts as a draft: only you, and testers you add, can use it. That is what you want while you build. Everything on its page is explained in Applications.

2. Give it a bot

Open the Bot tab and choose Add a bot. Moymo makes a member for it with a username taken from the application's name (dice_roller; you can change it) and shows you its token once:

Your bot's token (shown once)Text

moymo_bot_VYuEVu0uSZicSgGfSXhFVA.k2Zp1o4dM0n9rXq3w7c8vHjB5LyTfUaRsNeGiOxKz1Q

Copy it now and put it where your program can read it, never in code you share. Moymo keeps only a hash, so it cannot show it again; if you lose it, Reset token makes a new one and the old one stops working at once. See Tokens and secrets.

3. Add the bot to a server

You add a bot to a server you manage (you are its owner, or you have the Manage Server permission) with a link.

1. Open the Installation tab. Tick the scope bot and the permissions the bot needs. For a first bot, View channels, Send messages and Read message history are enough.
2. Copy the install link and open it in your browser. It looks like this:

The install linkText

https://moymo.net/oauth2/authorize?client_id=0f6c1a52-3b9e-4c1c-9d1b-6e7d2a8f4b10&scope=bot&permissions=7

3. Moymo shows what the bot asks for. Pick the server and untick anything you do not want to give it, then Authorise.

The bot is now a member of the server, with a role of its own named after the application, holding exactly the permissions you chose. You can see it in the member list with a BOT tag. Details are in Adding a bot to a server.

Draft applications

While the application is a draft, only you and your testers can add its bot, and to at most 25 servers.

4. Call the API as the bot

Every request carries the token in an Authorization header with the word Bot. The first call asks the API who the bot is:

RequestGET/users/@me

curl

curl https://moymo.net/api/app/v1/users/@me \
  -H "Authorization: Bot $MOYMO_BOT_TOKEN"

JavaScript

const token = process.env.MOYMO_BOT_TOKEN

const response = await fetch('https://moymo.net/api/app/v1/users/@me', {
  headers: { Authorization: `Bot ${token}` }
})
if (!response.ok) {
  const problem = await response.json()
  throw new Error(`${response.status} ${problem.code}: ${problem.message}`)
}
console.log(await response.json())

Python

import os
import requests

response = requests.get(
    "https://moymo.net/api/app/v1/users/@me",
    headers={"Authorization": f"Bot {os.environ['MOYMO_BOT_TOKEN']}"},
)
response.raise_for_status()
print(response.json())

Response200OKJSON

{
  "id": "b2a40959-d70f-4cd2-892f-1c037515d8fa",
  "username": "dice_roller",
  "display_name": "Dice Roller",
  "bot": true
}

The servers the bot is in:

RequestGET/users/@me/serversShell

curl https://moymo.net/api/app/v1/users/@me/servers \
  -H "Authorization: Bot $MOYMO_BOT_TOKEN"

Response200OKJSON

[
  {
    "id": "5f1d2b8e-7a64-4d07-8d3a-0b9f6c4e2a11",
    "name": "My server",
    "icon": "",
    "color": "#2bff6e",
    "owner": false
  }
]

Something went wrong?

A 401 means the token is wrong or was reset. A 403 means the call needs something the bot was not given. Every error has the same shape; quote its traceId if you ask for help.

5. Send a message

The bot may write in any channel where its role lets it. Find a channel's id with Developer mode (Copy ID), and:

RequestPOST/channels/{channel.id}/messages

curl

curl -X POST https://moymo.net/api/app/v1/channels/$CHANNEL_ID/messages \
  -H "Authorization: Bot $MOYMO_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from Dice Roller",
    "embeds": [{ "title": "d6", "description": "Rolled **4**", "color": 3145582 }]
  }'

JavaScript

await fetch(`https://moymo.net/api/app/v1/channels/${channelId}/messages`, {
  method: 'POST',
  headers: {
    Authorization: `Bot ${process.env.MOYMO_BOT_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content: 'Hello from Dice Roller',
    embeds: [{ title: 'd6', description: 'Rolled **4**', color: 3145582 }]
  })
})

Python

import os
import requests

requests.post(
    f"https://moymo.net/api/app/v1/channels/{channel_id}/messages",
    headers={"Authorization": f"Bot {os.environ['MOYMO_BOT_TOKEN']}"},
    json={
        "content": "Hello from Dice Roller",
        "embeds": [{"title": "d6", "description": "Rolled **4**", "color": 3145582}],
    },
)

The message appears in the channel from the bot, with its BOT tag. See Sending messages.

6. Add a slash command

A command needs somewhere for Moymo to send it: an interactions endpoint, a small https server of yours that verifies Moymo's signature and answers.

1. Write the endpoint (the example in Interactions overview is about twenty lines) and make it reachable on a public https address (a development tunnel works).

2. On the application's Interactions tab paste the address and Save and verify.

3. Register the command with the bot token:

   RequestPUT/applications/@me/commandsShell

   curl -X PUT https://moymo.net/api/app/v1/applications/@me/commands \
     -H "Authorization: Bot $MOYMO_BOT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '[{ "name": "hello", "description": "Say hello" }]'

4. In the server, in Moymo for Windows (Servers add-on 1.19 or newer), type / and choose hello. Your endpoint gets a request and answers:

   What your endpoint answersJSON

   { "type": 4, "data": { "content": "Hello!" } }

   The answer appears in the channel.

Where to go next

• The whole API is in the reference: messages, servers, commands.
• Build interfaces: Application commands, Components, Using modals.
• To let people sign in to your own site with Moymo, read the OAuth2 guide.
• To find the id of a server, channel, message or member while you build, switch on Developer mode in the Servers add-on.
• When you are ready for other people to use your application, read Publishing.