Skip to main content
This guide will help you set up, deploy, and test an OpenChat bot using the SDK. You’ll have a working bot registered with OpenChat and ready to send messages by the end.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js version 16 or higher
  • dfx version 0.14 or higher (installation guide)
  • Git for cloning the repository
  • At least 12 XDR worth of cycles for deployment (0.5 XDR for canister creation + 10 XDR for bot registration + operational overhead)
If you don’t have cycles yet, you can get free cycles from the cycles faucet or purchase them through an exchange.

​
Step 1: Clone and Set Up

Clone the repository and install dependencies:
1

Clone the repository

git clone https://github.com/AleDema/OC-Sample-Bot.git
cd OC-Sample-Bot
2

Start the Internet Computer locally

dfx start --clean --background
This starts a local Internet Computer replica in the background for development and testing.
3

Install dependencies and deploy locally

npm run setup
This command:
  • Installs npm packages
  • Installs Mops dependencies (Motoko packages)
  • Creates canisters
  • Deploys canisters to your local replica
  • Generates type bindings

​
Step 2: Test Locally

Start the development server to test your bot: 
npm start
This runs mo-dev which provides:
  • Live reload on code changes
  • Automatic redeployment
  • Type checking
Keep this running in a separate terminal while you develop. Your changes will be automatically deployed to the local replica.

​
Step 3: Deploy to Mainnet

When you’re ready to deploy to the Internet Computer mainnet:
1

Create the canister with cycles

Create your bot canister with sufficient cycles:
dfx canister --network ic create OCBot --with-cycles 12_000_000_000_000
This allocates 12 trillion cycles (12 XDR) to your canister:
  • 0.5 XDR for canister creation
  • 10 XDR for OpenChat bot registration
  • 1.5 XDR for operations
2

Deploy to mainnet

dfx deploy --network ic OCBot
This deploys your bot canister to the Internet Computer mainnet.
3

Add yourself as a custodian

Add your principal as a custodian to manage the bot:
dfx canister call OCBot addCustodian '(principal "YOUR_PRINCIPAL_ID")' --network ic
Get your principal ID with: dfx identity get-principal
4

Initialize the bot

Register your bot with OpenChat (requires 10 XDR in cycles):
dfx canister call OCBot initBot '("my_bot", opt "My Bot Display Name")' --network ic
Replace "my_bot" with your desired bot username and "My Bot Display Name" with a friendly name.
This step consumes 10 XDR (10 trillion cycles) from your canister balance. Ensure your canister has sufficient cycles before calling this.

​
Step 4: Join a Group and Send a Message

Now that your bot is registered, let’s join a group and send a test message:
1

Join a group

Join an OpenChat group using its canister ID:
dfx canister call OCBot tryJoinGroup '("GROUP_CANISTER_ID", null)' --network ic
Replace GROUP_CANISTER_ID with the canister ID of an OpenChat group. If the group is private, you’ll need an invite code:
dfx canister call OCBot tryJoinGroup '("GROUP_CANISTER_ID", opt 123456789)' --network ic
2

Send a test message

Send a message to the group:
dfx canister call OCBot testSendMessageToGroup '("GROUP_CANISTER_ID", "Hello from my OpenChat bot!", null)' --network ic
You should see your message appear in the OpenChat group.

​
Example: TallyBot Workflow

If you want to use TallyBot to track governance proposals: 
# Join a community
dfx canister call OCBot tryJoinCommunity '("COMMUNITY_ID", null)' --network ic

# Join a channel within the community
dfx canister call OCBot tryJoinChannel '("COMMUNITY_ID", CHANNEL_ID, null)' --network ic

# Subscribe the channel to a tally ID
dfx canister call OCBot addSubscriber '(
  "proposal_123",
  variant {
    Channel = record {
      communityCanisterId = "COMMUNITY_ID";
      channelId = CHANNEL_ID
    }
  }
)' --network ic
Now when you send tally updates via the tallyUpdate endpoint, they’ll be posted to this channel.

​
Verify Your Bot

Check that everything is working: 
dfx canister call OCBot getBotStatus --network ic

​
Next Steps

Bot Initialization Guide

Learn more about bot initialization, avatars, and configuration

Sending Messages

Explore message types, threading, and advanced messaging patterns

TallyBot

Set up TallyBot to track governance proposal voting

API Reference

Dive into the complete API documentation

​
Troubleshooting

Ensure your canister has at least 10 XDR (10 trillion cycles) available. Check with:
dfx canister status OCBot --network ic
If needed, top up your canister:
dfx cycles --network ic canister deposit OCBot 10000000000000
Private groups require either:
  1. An invite code from a group admin
  2. Being pre-added by a group admin through the OpenChat UI
Contact the group administrator to be invited.
Verify:
  1. Bot is registered: dfx canister call OCBot getBotStatus --network ic
  2. Bot has joined the group/channel
  3. You’re calling the correct canister ID
  4. Check logs for errors: dfx canister call OCBot getLogs '(null)' --network ic
For local development, omit the --network ic flag to interact with your local replica instead of mainnet.

Build docs developers (and LLMs) love

Get started for freeTalk to us