Overview The OCService module provides a high-level interface for interacting with OpenChat canisters. It wraps the low-level OpenChat APIs and provides error handling, making it easier to build bots that interact with OpenChat groups, communities, and channels.
This is the primary service layer you’ll use to integrate your bot with OpenChat.
OCServiceImpl Class The main class that implements the OpenChat service interface.
public class OCServiceImpl()
Bot Registration registerBot Registers a new bot with OpenChat.
public func registerBot( userIndexCanister : Text, { username : Text; displayName : ?Text } ) : async* Result.Result<OCApi.InitializeBotResponse, Text>
The canister ID of the OpenChat user index canister
The username for the bot (must be unique)
Optional display name for the bot
Result
Result<InitializeBotResponse, Text>
Returns #ok(InitializeBotResponse) on success, or #err(Text) with error message on failure Show InitializeBotResponse variants
#Success - Bot registered successfully#AlreadyRegistered - Bot username already exists#UsernameTaken - Username is taken by another user#UsernameInvalid - Username format is invalid#UsernameTooShort - Username is too short#UsernameTooLong - Username is too long#InsufficientCyclesProvided - Not enough cycles provided#InternalError(Text) - Internal error occurred setAvatar Sets the avatar for the bot.
public func setAvatar( userIndexCanister : Text, avatar : OCApi.SetAvatarArgs ) : async* Result.Result<OCApi.SetAvatarResponse, Text>
The canister ID of the OpenChat user index canister
Avatar configuration with avatar_id field (optional Nat)
Result
Result<SetAvatarResponse, Text>
Returns #Success or #UserNotFound
userSummary Retrieves summary information about a user.
public func userSummary( userIndexCanister : Text, { userId : ?OCApi.UserId; username : ?Text } ) : async* Result.Result<OCApi.UserSummaryResponse, Text>
The canister ID of the OpenChat user index canister
Optional user ID to look up
Optional username to look up
Result
Result<UserSummaryResponse, Text>
Returns user summary information including username, display name, avatar, bot status, and diamond membership status
publicGroupSummary Retrieves public information about a group.
public func publicGroupSummary( groupCanisterId : Text, args : { invite_code : ?Nat64 } ) : async* Result.Result<OCTypes.PublicSummaryResponse, Text>
The canister ID of the group
Optional invite code if the group requires one
Result
Result<PublicSummaryResponse, Text>
Returns #Success with group summary or #NotAuthorized
Retrieves public information about a community.
public func publicCommunitySummary( communityCanisterId : Text, args : { invite_code : ?Nat64 } ) : async* Result.Result<OCApi.CommunitySummaryResponse, Text>
The canister ID of the community
Optional invite code if required
Result
Result<CommunitySummaryResponse, Text>
Returns community summary with channels, permissions, and membership details
Joining Groups & Communities joinGroup Joins a group chat.
public func joinGroup( groupCanisterId : Text, args : OCApi.JoinGroupArgs ) : async* Result.Result<OCApi.JoinGroupResponse, Text>
The canister ID of the group to join
Join arguments including chat_id, invite_code, and correlation_id
Result
Result<JoinGroupResponse, Text>
#Success - Successfully joined group#AlreadyInGroup / #AlreadyInGroupV2 - Already a member#GroupNotFound - Group doesn’t exist#GroupNotPublic - Group is private#NotInvited - Not invited to private group#GateCheckFailed - Failed access gate requirements#ParticipantLimitReached - Group is full#Blocked - User is blocked#UserSuspended - User is suspended#ChatFrozen - Group is frozen Joins a community.
public func joinCommunity( communityCanisterId : Text, args : OCApi.JoinCommunityArgs ) : async* Result.Result<OCApi.JoinCommunityResponse, Text>
The canister ID of the community
args
JoinCommunityArgs
required
Join arguments including community_id, user_id, principal, invite_code, and bot flags
Result
Result<JoinCommunityResponse, Text>
Returns #Success with community summary, or error variant
joinChannel Joins a channel within a community.
public func joinChannel( communityCanisterId : Text, args : OCApi.JoinChannelArgs ) : async* Result.Result<OCApi.JoinChannelResponse, Text>
The canister ID of the community
Join arguments including community_id, channel_id, user_id, and other metadata
Result
Result<JoinChannelResponse, Text>
Returns channel summary on success, or error variant indicating the failure reason
Messaging sendGroupMessage Sends a message to a group chat.
public func sendGroupMessage( groupCanisterId : Text, sender : Text, senderDisplayName : ?Text, content : OCApi.MessageContentInitial, messageId : Nat, threadIndexId : ?Nat32 ) : async* Result.Result<OCApi.SendMessageResponse, Text>
The canister ID of the group
content
MessageContentInitial
required
The message content (Text, Image, File, Poll, etc.)
Unique message identifier
Optional thread root message index if replying in a thread
Result
Result<SendMessageResponse, Text>
Returns #Success with event_index and message_index, or error variant
sendChannelMessage Sends a message to a community channel.
public func sendChannelMessage( communityCanisterId : Text, channelId : Nat, sender : Text, senderDisplayName : ?Text, content : OCApi.MessageContent, messageId : Nat, threadIndexId : ?Nat32 ) : async* Result.Result<OCApi.SendMessageResponse, Text>
The canister ID of the community
The channel ID within the community
Unique message identifier
Optional thread root message index
Result
Result<SendMessageResponse, Text>
Returns success with message indices or error variant
editGroupMessage Edits an existing group message.
public func editGroupMessage( groupCanisterId : Text, messageId : OCApi.MessageId, threadRootIndex : ?OCApi.MessageIndex, newContent : OCApi.MessageContentInitial ) : async* Result.Result<OCApi.EditMessageResponse, Text>
The canister ID of the group
The ID of the message to edit
Optional thread root if editing a thread message
newContent
MessageContentInitial
required
The new message content
Result
Result<EditMessageResponse, Text>
Returns #Success, #MessageNotFound, #CallerNotInGroup, #UserSuspended, or #ChatFrozen
editChannelMessage Edits an existing channel message.
public func editChannelMessage( communityCanisterId : Text, channelId : Nat, messageId : OCApi.MessageId, threadRootIndex : ?OCApi.MessageIndex, newContent : OCApi.MessageContentInitial ) : async* Result.Result<OCApi.EditChannelMessageResponse, Text>
The canister ID of the community
The ID of the message to edit
Optional thread root index
newContent
MessageContentInitial
required
The new message content
Result
Result<EditChannelMessageResponse, Text>
Returns success or error variant indicating the failure reason
Message Retrieval messagesByMessageIndex Retrieves messages by their message indices.
public func messagesByMessageIndex( groupCanisterId : Text, args : OCApi.MessagesByMessageIndexArgs ) : async* Result.Result<OCApi.MessagesByMessageIndexResponse, Text>
The canister ID of the group
args
MessagesByMessageIndexArgs
required
Arguments including:
thread_root_message_index: Optional thread rootmessages: Array of message indices to retrievelatest_known_update: Optional timestamp for optimization Result
Result<MessagesByMessageIndexResponse, Text>
Returns #Success with messages array, latest_event_index, and chat_last_updated timestamp
Error Handling All methods return Result.Result<T, Text> types:
#ok(value) - Successful operation with result value#err(message) - Operation failed with error message
The service layer automatically catches exceptions from canister calls and converts them to error results.
Usage Example import OCService "backend/OC/OCService"; let ocService = OCService.OCServiceImpl(); // Register bot let result = await* ocService.registerBot( "renrk-eyaaa-aaaaa-aaada-cai", { username = "my_bot"; displayName = ?"My Bot"; } ); switch (result) { case (#ok(#Success)) { // Bot registered successfully }; case (#ok(otherResponse)) { // Handle other response variants }; case (#err(message)) { // Handle error }; };
