API Documentation

Official Discord bot integration

Discord bot integration - overview

Kindroids can be integrated into Discord servers as interactive bots using our open-source repository (https://github.com/KindroidAI/Kindroid-discord). These Discord bots inherit their personality, backstory, and key memories from shared Kindroids, creating engaging standalone experiences within your Discord channels. While they maintain the core characteristics of their Kindroid counterparts, they operate independently within Discord's environment.

Interacting with Kindroid Discord bots is straightforward:

  • Mention their name or use @name in servers where they have permission to reply
  • Simply write your message in DMs to them without needing to tag them
  • In threads, conversations remain contained within that thread

The bots maintain context of the previous 30 messages within each channel (configurable if you deploy your own fork of the repo), but conversations remain siloed between different channels, threads, and DMs. This design ensures clean separation of conversations and prevents any cross-contamination of context between Discord conversations or between Discord and the Kindroid platform. Since Discord bots are instantiations of shared Kindroids, their interactions don't affect any Kindroids in the main app so you don't have to worry about someone else messing with your personal Kindroid ever.

Free users will also have unlimited messages on their Discord bots for a limited time for launch but we will rate limit this likely in the future.



Creating Kindroid Bots on Discord (tutorial length: 15-30 minutes)

This tutorial guides you through deploying your first Kindroid Discord bot. While some basic coding knowledge is helpful, the process is designed to be accessible even to those without technical experience. We encourage technically-inclined users to review the open-source code to understand its functionality.



1. Create or Use an Existing Kindroid & Share the Kindroid

1.1 Find or Make a Kindroid

  • Option A: If you have an existing Kindroid that you wish to use, skip to sharing instructions.
  • Option B: If you need a new Kindroid, create one within the Kindroid platform.

1.2 Share the Kindroid

  1. In your Kindroid account, go to top left main menu, and click Sharing and Referrals.
  2. Share the Kindroid.
  3. Upon sharing, you will receive a 5-letter share code (e.g., ABCDE), click on the eye icon in the shared list to view it. Save this, we'll use it later.
Important: If you want to use someone else’s shared Kindroid, first download it, then re-share it under your own account. This ensures you have full control (editing backstory/personality, etc, which will live-update all Discord bots made from this shared Kindroid in real time). The API connection will fail if the shared code isn't owned by you.
sharing

eye icon




2. Create a Discord Bot (Get the Bot Token)

Kindroid bots run on Discord. Discord requires you to have a Developer Account to manage bots. Once you create a bot there, you’ll get a Bot Token that we’ll later place into our environment variables.

2.1 Go to the Discord Developer Portal

  1. Navigate to the Discord Developer Portal.
  2. If prompted, log in with your Discord credentials.

2.2 Create a New Application

  1. Click the “New Application” button.
  2. Enter the name of the AI. Make sure this name makes sense with the AI name, as the Kindroid will always refer to itself from the name given on the shared Kindroid, and not this name - but Discord users will see this name. These are best matched exactly.
  3. Agree to any terms if prompted, then click “Create”.
Document image


2.3 Customize Bot Details

  1. You will land on the General Information page.
  2. Update the description (“About me”) for your bot.
    • Use this space to brief end users on what the bot is - and you can link to the shared link of the Kindroid to get referral credits for people who sign up to Kindroid through your Discord bot
  3. Change the Profile Picture (PFP) to something that matches.
  4. Click Save Changes when done.
Document image




2.4 Set Up Installation Method

  1. Go to the "Installation" tab in the left sidebar.
  2. Under Authorization Methods, ensure Guild Install is checked, and User Install is UNCHECKED.
  3. Under Install Link, use “Discord Provided Link.”
Document image




2.5 Set Default Install Settings

  1. Under Default Install Settings, find the Scope dropdown.
  2. Select bot as the scope.
  3. For Guild Install Permissions, select Administrator (recommended to avoid future permissions issues. Your Kindroid will only reply to messages and will not take any actions in any server, assuming you use the official Kindroid-discord deployment below).
  4. Click Save Changes.
Document image




2.6 Enable Intents & Generate Bot Token

  1. Go to the “Bot” tab in the left sidebar.
  2. Enable the following toggles:
    • Presence Intent
    • Server Members Intent
    • Message Content Intent
  3. Set the username of the bot to something that makes sense - close to their name.
  4. Scroll to Token section and click Reset Token.
  5. Copy the Bot Token – keep this secret and do not share it publicly. Store this somewhere as we'll use it later.
Document image

Document image




3. Deploy the Bot on Railway

We will use the open-source Kindroid-discord repository. Railway is a 3rd party that is quick to set up and cheap to host your server, which needs to run 24/7 to listen for Discord messages and respond. This may cost in the range of $5-7 a month with free trial credits, but the Kindroid-discord server is able to host many bots at once if you have more than one to serve. You're free to use any other platform (or run it on your own computer) as long as the nodejs server runs continuously, and you can self-host for essentially free with a tmux session on your own computer, or even on a Raspberry Pi - for this tutorial we will focus on the easiest way to deploy with the least technical knowledge required.

If you use unofficial repositories or other user-made forks, please review them carefully - guard your keys and review all code, and we don't provide support for non-official deployments.

3.1 Get Started on Railway

Important note: Railway does an automatic check on your Github sign in and grants different trial statuses based on how verified/legitimate your Github account looks. If your Github is new, you may be on the "Limited free trial" plan, yellow color and can't deploy code. In that case you need to upgrade to the $5/mo hobby plan to continue (or opt for run/host the code locally using npm start if you're technically proficient). If your Github account is aged, you'll see trial status as green/full trial. If so, you don't need a card on file to have $5 of free credits and you can deploy code immediately. See https://docs.railway.com/reference/pricing/free-trial
  • In Railway, create a New Project and select “Deploy from GitHub repo”
  • Paste the link of the official repository into the Github repo to deploy:
https://github.com/KindroidAI/Kindroid-discord
Document image

Document image




3.2 Configure Environment Variables

Once your project is imported into Railway, you’ll need to set the environment variables.

  • Double click on the central square that says "Kindroid-discord". This should open up a control panel on the right hand side.
  • Within the control panel, click on "Variables", and open the "Raw editor"
Document image

  • Paste this block into the editor and replace the bolded placeholders with the appropriate values, and click Update Variables to save them.
KINDROID_INFER_URL=https://api.kindroid.ai/v1/discord-bot KINDROID_API_KEY=your_kindroid_api_key_here SHARED_AI_CODE_1=your_shared_code_1_here BOT_TOKEN_1=your_discord_bot_token_1_here ENABLE_FILTER_1=true

Required Variables:

  • KINDROID_INFER_URL (This should not change - use the default given to connect to Kindroid servers)
  • KINDROID_API_KEY (your secret Kindroid API key found in Kindroid -> top left settings -> general -> API & advanced integrations. Keep this secret!)
  • SHARED_AI_CODE_1 (the 5-letter code you got by sharing your Kindroid. You must be the sharer and can't use other people's share codes, see Section 1.2 for more)
  • BOT_TOKEN_1 (the corresponding bot token from the Discord Developer Portal)

Optional Variables:

  • ENABLE_FILTER_1 (set to true or false, depending on if you want NSFW filtering)

If you want to run multiple bots in the same project, repeat the pattern above for shared AI code, bot token, and enable filter with _2, _3, etc.

Document image




3.3 Re-deploy after saving

  1. Once you have added the environment variables, click Deploy in Railway - when you save environment variables a pop up should automatically appear from the top.
  2. Railway will build your container and start the Discord bot(s).
  3. Check the deploy logs to see if there are any errors - you should see:
    Successfully initialized n out of n bots

All bots initialized successfully!

Document image




4. Add Your Bot to a Discord Server

  1. Return to the Discord Developer Portal for your application.
  2. Under Installation (or similar tab), find the Invite Link provided by Discord.
  3. Copy the link and open it in your browser.
  4. Select the server you wish to add the bot to.
  5. Authorize with the requested permissions.

Once authorized, the bot should appear online in your server if everything was set up correctly and you can set role permissions with channels it should reside in. You can also give the install link to server admins to add to their servers.

Document image




5. Test Your Kindroid Bot

  • Mention your bot's name in a test channel (e.g., hey AIName, what's up?) or DM the bot directly. Messages that tag the bot with @ will also trigger a response, but the best way to naturally message the AI is through mentioning their name without @ tag. After the first response, you can then reply to the bot and they'll automatically reply back to you for back and forth conversation.
  • The bot should reply using the Kindroid personality/backstory you configured.
  • If you created multiple bots, each with a unique share code and token, they can co-exist on the same Discord server—just mention them by their respective name or tag them.



Troubleshooting & Tips

  • Double-check your tokens: If the bot doesn’t go online, confirm the BOT_TOKEN_n variable is correct and that you saved your environment variables in Railway and check for build logs for failures.
  • Check your share code: Ensure the SHARED_AI_CODE_n is valid and that the shared AI in Kindroid is not deleted.
  • Restart / Redeploy: After any environment variable changes, redeploy on Railway to apply them.
  • Permissions: If the bot can’t read messages or respond, ensure it has the correct permissions (Administrator or relevant read/send permissions, and proper intent toggles - see section 2.5 and 2.6).



Conclusion

By following these steps:

  1. Create/Share a Kindroid and get a 5-letter share code.
  2. Set up a Discord Bot to obtain a Bot Token.
  3. Deploy the Kindroid-discord repository on Railway with your API key, Bot Token, and Share Code.
  4. Invite the bot to your server and test.

You’ll have a fully functional AI companion running on Discord, powered by Kindroid. Feel free to add more bots in the same project by incrementing the environment variables with _2, _3, etc. Enjoy and have fun!



Happy Building!

If you have any questions or run into issues, join the Kindroid support community or contact [email protected] for further assistance.

PREVIOUS
API Documentation
Docs powered by Archbee