Overview Before your bot can interact with OpenChat, it must be registered and initialized. This process requires cycles payment and involves several configuration steps.
Bot registration requires at least 10 XDR in cycles (10,000,000,000,000 cycles). Make sure your canister has sufficient cycles before calling initBot.
Bot Status Lifecycle Your bot progresses through three states during initialization:
#NotInitialized - Initial state, bot has not been registered#Initializing - Registration in progress with OpenChat#Initialized - Bot successfully registered and ready to use
Prerequisites Canister Cycles When deploying to mainnet, create your canister with sufficient cycles:
dfx canister --network ic create OCBot --with-cycles 12_000_000_000_000
This provides:
0.5 XDR for canister instantiation
10 XDR for OpenChat bot registration fee
1.5 XDR for operational costs
Admin Access Add your principal as a custodian to access management endpoints:
dfx canister call OCBot addCustodian '(principal "${your-principal}")' --ic
Initializing Your Bot
Call initBot with bot name
The initBot function registers your canister as an OpenChat bot. You can provide an optional display name: # With both name and displayName dfx canister call OCBot initBot '("bot_name", opt "Display Name")' --ic # With name only (no displayName) dfx canister call OCBot initBot '("bot_name", null)' --ic
The bot name must be unique across OpenChat. Choose a descriptive, memorable name.
Understand the registration process
When you call initBot, the following occurs: // From BotService.mo:61-105 public func initBot<system>(name : Text, _displayName : ?Text) : async Result.Result<(), Text>{ switch(botModel.botStatus){ case(#NotInitialized){ botModel.botStatus := #Initializing; Cycles.add<system>(BOT_REGISTRATION_FEE); // 10T cycles let res = await* ocService.registerBot(USER_INDEX_CANISTER, { username = name; displayName = _displayName }); // Handle response... }; case(#Initializing){ return #err("Initializing") }; case(#Initialized){ return #err("Initialized") }; } };
The bot status transitions to #Initializing and exactly 10 XDR in cycles is attached to the registration call.
Handle registration responses
The registration can return several responses: Success Response: #Success -> botStatus := #Initialized
Error Responses: #AlreadyRegistered -> "AlreadyRegistered" #InsufficientCyclesProvided(n) -> "Not enough cycles. Required: {n}"
Your bot status reverts to #NotInitialized on error, allowing retry.
Verify bot status
Check that initialization succeeded: dfx canister call OCBot getBotStatus
Expected response: (variant { Initialized })
Configuring Bot Avatar After initialization, you can set a custom avatar for your bot:
Avatar Requirements
Maximum size: 800KB (819,200 bytes)
Supported formats: Any format supported by OpenChat
Must be uploaded to OpenChat storage first
Setting Avatar // From BotService.mo:125-149 public func setAvatar(args : SetAvatarArgs) : async* Result.Result<SetAvatarResponse, Text>{ if(not validateAvatar(args)){ return #err("Avatar too big"); }; switch(args.avatar){ case(?avatar){ switch(await* ocService.setAvatar(USER_INDEX_CANISTER, {avatar_id = ?avatar.id})){ case(#ok(res)){ return #ok(#Success); }; case(#err(msg)){ return #err("Error: " # msg); }; }; }; case(_){ return #err("Avatar not found") }; }; };
Avatar Type Definition public type SetAvatarArgs = { avatar : ?Document; }; public type Document = { id : Nat; data : Blob; mime_type : Text; };
The avatar must first be uploaded to OpenChat storage and assigned an ID before you can reference it in setAvatar.
Error Handling Always check for errors during initialization:
let result = await botService.initBot("my_bot", ?"My Bot"); switch(result){ case(#ok(_)){ // Initialization successful logService.logInfo("Bot initialized successfully", null); }; case(#err(msg)){ // Handle error logService.logError("Bot initialization failed: " # msg, null); }; };
Common Issues Insufficient Cycles Problem: #InsufficientCyclesProvided errorSolution: Top up your canister with more cycles:dfx canister --network ic deposit-cycles 10_000_000_000_000 OCBot
Bot Already Registered Problem: #AlreadyRegistered errorSolution: Your bot is already registered. The status should be #Initialized. If you need to reset, you must use a new canister.Name Conflict Problem: Bot name is already takenSolution: Choose a different, unique bot name.Next Steps Once your bot is initialized:
Join Communities Learn how to join groups and channels
Send Messages Start sending messages to OpenChat
