OCApi - OpenChat Bot SDK

Overview

The OCApi module contains auto-generated Motoko type bindings for the OpenChat platform. This file provides type-safe interfaces to OpenChat’s canister APIs, including comprehensive message types, user types, community/group structures, and response formats.

This file is auto-generated from OpenChat specifications. Do not modify it directly.

Core Types

Identity Types

UserId

public type UserId = CanisterId;
public type CanisterId = Principal;

Represents a unique user identifier (Principal).

ChannelId

public type ChannelId = Nat;

Numerical identifier for channels within communities.

CommunityId

public type CommunityId = CanisterId;

Principal identifier for communities.

ChatId

public type ChatId = CanisterId;

Principal identifier for group chats.

Message Types

MessageId

public type MessageId = Nat;

Unique identifier for messages (client-generated).

MessageIndex

public type MessageIndex = Nat32;

Server-assigned sequential index for messages within a chat.

EventIndex

public type EventIndex = Nat32;

Sequential index for all events (messages, reactions, edits, etc.) in a chat.

MessageContent

The content of a message. Supports multiple content types:

public type MessageContent = {
  #Text : TextContent;
  #Image : ImageContent;
  #Video : VideoContent;
  #Audio : AudioContent;
  #File : FileContent;
  #Poll : PollContent;
  #Crypto : CryptoContent;
  #Giphy : GiphyContent;
  #Prize : PrizeContent;
  #P2PSwap : P2PSwapContent;
  #GovernanceProposal : ProposalContent;
  #Custom : CustomMessageContent;
  #Deleted : DeletedContent;
  #ReportedMessage : ReportedMessage;
  #PrizeWinner : PrizeWinnerContent;
  #MessageReminderCreated : MessageReminderCreated;
  #MessageReminder : MessageReminder;
};

Show Content Type Details

#Text - Plain or markdown text message

public type TextContent = { text : Text };

#Image - Image with optional caption

public type ImageContent = {
  height : Nat32;
  mime_type : Text;
  blob_reference : ?BlobReference;
  thumbnail_data : Text;
  caption : ?Text;
  width : Nat32;
};

#File - File attachment

public type FileContent = {
  name : Text;
  mime_type : Text;
  file_size : Nat32;
  blob_reference : ?BlobReference;
  caption : ?Text;
};

#Audio - Audio file

public type AudioContent = {
  mime_type : Text;
  blob_reference : ?BlobReference;
  caption : ?Text;
};

#Video - Video file

public type VideoContent = {
  height : Nat32;
  image_blob_reference : ?BlobReference;
  video_blob_reference : ?BlobReference;
  mime_type : Text;
  thumbnail_data : Text;
  caption : ?Text;
  width : Nat32;
};

#Poll - Interactive poll

public type PollContent = {
  votes : PollVotes;
  ended : Bool;
  config : PollConfig;
};

#Crypto - Cryptocurrency transfer

public type CryptoContent = {
  recipient : UserId;
  caption : ?Text;
  transfer : CryptoTransaction;
};

MessageContentInitial

Initial message content when creating a new message (subset of MessageContent):

public type MessageContentInitial = {
  #Text : TextContent;
  #Image : ImageContent;
  #Video : VideoContent;
  #Audio : AudioContent;
  #File : FileContent;
  #Poll : PollContent;
  #Crypto : CryptoContent;
  #Giphy : GiphyContent;
  #Prize : PrizeContentInitial;
  #P2PSwap : P2PSwapContentInitial;
  #GovernanceProposal : ProposalContent;
  #Custom : CustomMessageContent;
  #Deleted : DeletedContent;
  #MessageReminderCreated : MessageReminderCreated;
  #MessageReminder : MessageReminder;
};

Message

Complete message structure:

public type Message = {
  forwarded : Bool;
  content : MessageContent;
  edited : Bool;
  tips : [(CanisterId, [(UserId, Nat)])];
  last_updated : ?TimestampMillis;
  sender : UserId;
  thread_summary : ?ThreadSummary;
  message_id : MessageId;
  replies_to : ?ReplyContext;
  reactions : [(Text, [UserId])];
  message_index : MessageIndex;
};

message_id

MessageId

Client-generated unique message identifier

message_index

MessageIndex

Server-assigned sequential index

sender

UserId

Principal of the message sender

content

MessageContent

The message content (text, image, etc.)

edited

Bool

Whether message has been edited

reactions

[(Text, [UserId])]

Emoji reactions and users who reacted

replies_to

?ReplyContext

Optional reference to message being replied to

thread_summary

?ThreadSummary

Thread information if message has replies

MessageEventWrapper

Wraps a message with metadata:

public type MessageEventWrapper = {
  event : Message;
  timestamp : TimestampMillis;
  index : EventIndex;
  correlation_id : Nat64;
  expires_at : ?TimestampMillis;
};

File & Media Types

BlobReference

Reference to stored blob data:

public type BlobReference = {
  blob_id : Nat;
  canister_id : CanisterId;
};

blob_id

Nat

Identifier for the blob

canister_id

CanisterId

Canister storing the blob data

Document

Document/file data:

public type Document = {
  id : Nat;
  data : Blob;
  mime_type : Text;
};

Response Types

Bot Registration

InitializeBotResponse

public type InitializeBotResponse = {
  #Success;
  #EndDateInPast;
  #AlreadyRegistered;
  #UserLimitReached;
  #UsernameTaken;
  #UsernameInvalid;
  #UsernameTooShort : Nat16;
  #UsernameTooLong : Nat16;
  #InsufficientCyclesProvided : Nat;
  #InternalError : Text;
};

InitializeBotResponse

variant

Response from bot registration attempt

Show Response variants

#Success - Bot successfully registered
#AlreadyRegistered - Bot username already exists
#UsernameTaken - Username taken by another user
#UsernameInvalid - Invalid username format
#UsernameTooShort(Nat16) - Username too short (minimum length provided)
#UsernameTooLong(Nat16) - Username too long (maximum length provided)
#InsufficientCyclesProvided(Nat) - Not enough cycles (required amount provided)
#InternalError(Text) - Internal error with message

User Information

UserSummaryResponse

public type UserSummaryResponse = {
  #Success : UserSummary;
  #UserNotFound;
};

UserSummary

public type UserSummary = {
  username : Text;
  diamond_member : Bool;
  diamond_membership_status : DiamondMembershipStatus;
  user_id : UserId;
  is_bot : Bool;
  display_name : ?Text;
  avatar_id : ?Nat;
  suspended : Bool;
};

UserSummary

Show Fields

username

Text

Unique username

user_id

UserId

User’s principal identifier

is_bot

Bool

Whether this user is a bot

display_name

?Text

Optional display name

avatar_id

?Nat

Optional avatar image ID

suspended

Bool

Whether user is suspended

diamond_member

Bool

Whether user has diamond membership

Avatar

SetAvatarArgs

public type SetAvatarArgs = {
  avatar_id : ?Nat;
};

SetAvatarResponse

public type SetAvatarResponse = {
  #Success;
  #UserNotFound;
};

Group Operations

JoinGroupArgs

public type JoinGroupArgs = {
  chat_id : Principal;
  invite_code : ?Nat64;
  correlation_id : Nat64;
};

JoinGroupResponse

public type JoinGroupResponse = {
  #Success : {};
  #AlreadyInGroupV2 : {};
  #AlreadyInGroup;
  #GateCheckFailed : {};
  #GroupNotFound;
  #GroupNotPublic;
  #NotInvited;
  #ParticipantLimitReached : Nat32;
  #Blocked;
  #UserSuspended;
  #ChatFrozen;
  #InternalError : Text;
};

Community Operations

JoinCommunityArgs

public type JoinCommunityArgs = {
  community_id : CommunityId;
  user_id : UserId;
  principal : Principal;
  invite_code : ?Nat64;
  is_platform_moderator : Bool;
  is_bot : Bool;
  diamond_membership_expires_at : ?Int;
  verified_credential_args : ?VerifiedCredentialGateArgs;
};

community_id

CommunityId

required

The community to join

user_id

UserId

required

The user’s ID

is_bot

Bool

required

Set to true for bots

invite_code

?Nat64

Optional invite code for private communities

JoinCommunityResponse

public type JoinCommunityResponse = {
  #Success : CommunityCanisterCommunitySummary;
  #AlreadyInCommunity : CommunityCanisterCommunitySummary;
  #GateCheckFailed : GateCheckFailedReason;
  #NotInvited;
  #UserBlocked;
  #MemberLimitReached : Nat32;
  #CommunityFrozen;
  #InternalError : Text;
};

JoinChannelArgs

public type JoinChannelArgs = {
  community_id : CommunityId;
  channel_id : ChannelId;
  user_id : UserId;
  principal : Principal;
  invite_code : ?Nat64;
  is_platform_moderator : Bool;
  is_bot : Bool;
  diamond_membership_expires_at : ?Int;
  verified_credential_args : ?VerifiedCredentialGateArgs;
};

JoinChannelResponse

public type JoinChannelResponse = {
  #Success : CommunityCanisterChannelSummary;
  #SuccessJoinedCommunity : CommunityCanisterCommunitySummary;
  #AlreadyInChannel : CommunityCanisterCommunitySummary;
  #GateCheckFailed : GateCheckFailedReason;
  #UserNotInCommunity;
  #ChannelNotFound;
  #NotInvited;
  #UserSuspended;
  #UserBlocked;
  #MemberLimitReached : Nat32;
  #CommunityFrozen;
  #InternalError : Text;
};

Messaging Operations

SendMessageResponse

public type SendMessageResponse = {
  #Success : {
    event_index : Nat32;
    message_index : Nat32;
  };
  #ChannelNotFound;
  #ThreadMessageNotFound;
  #MessageEmpty;
  #TextTooLong : Nat32;
  #InvalidPoll : InvalidPollReason;
  #NotAuthorized;
  #UserNotInCommunity;
  #UserNotInChannel;
  #UserSuspended;
  #InvalidRequest : Text;
  #CommunityFrozen;
  #RulesNotAccepted;
  #CommunityRulesNotAccepted;
};

Success

Show Success fields

event_index

Nat32

Event index assigned to this message

message_index

Nat32

Message index assigned to this message

EditMessageResponse

public type EditMessageResponse = {
  #Success;
  #MessageNotFound;
  #CallerNotInGroup;
  #UserSuspended;
  #UserLapsed;
  #ChatFrozen;
};

EditChannelMessageResponse

public type EditChannelMessageResponse = {
  #Success;
  #MessageNotFound;
  #UserNotInCommunity;
  #UserNotInChannel;
  #UserSuspended;
  #UserLapsed;
  #CommunityFrozen;
  #ChannelNotFound;
};

Message Retrieval

MessagesByMessageIndexArgs

public type MessagesByMessageIndexArgs = {
  thread_root_message_index : ?MessageIndex;
  messages : [MessageIndex];
  latest_known_update : ?Nat64;
};

messages

[MessageIndex]

required

Array of message indices to retrieve

thread_root_message_index

?MessageIndex

If retrieving thread messages, specify thread root

latest_known_update

?Nat64

Optimization: skip if no updates since this timestamp

MessagesByMessageIndexResponse

public type MessagesByMessageIndexResponse = {
  #Success : MessagesResponse;
  #CallerNotInGroup;
  #ThreadMessageNotFound;
  #ReplicaNotUpToDateV2 : TimestampMillis;
};

MessagesResponse

public type MessagesResponse = {
  messages : [MessageEventWrapper];
  latest_event_index : EventIndex;
  chat_last_updated : TimestampMillis;
};

Community & Group Structures

CommunityCanisterCommunitySummary

Complete community information:

public type CommunityCanisterCommunitySummary = {
  is_public : Bool;
  permissions : CommunityPermissions;
  community_id : CommunityId;
  metrics : ChatMetrics;
  gate : ?AccessGate;
  name : Text;
  description : Text;
  last_updated : TimestampMillis;
  channels : [CommunityCanisterChannelSummary];
  user_groups : [UserGroup];
  avatar_id : ?Nat;
  membership : ?CommunityMembership;
  local_user_index_canister_id : CanisterId;
  frozen : ?FrozenGroupInfo;
  latest_event_index : EventIndex;
  banner_id : ?Nat;
  member_count : Nat32;
  primary_language : Text;
};

CommunityCanisterChannelSummary

Channel information:

public type CommunityCanisterChannelSummary = {
  channel_id : ChannelId;
  is_public : Bool;
  name : Text;
  description : Text;
  subtype : ?GroupSubtype;
  avatar_id : ?Nat;
  permissions_v2 : GroupPermissions;
  gate : ?AccessGate;
  member_count : Nat32;
  latest_message : ?MessageEventWrapper;
  latest_message_index : ?MessageIndex;
  latest_event_index : EventIndex;
  min_visible_event_index : EventIndex;
  min_visible_message_index : MessageIndex;
  metrics : ChatMetrics;
  membership : ?GroupMembership;
  history_visible_to_new_joiners : Bool;
  events_ttl : ?Milliseconds;
  events_ttl_last_updated : TimestampMillis;
  date_last_pinned : ?TimestampMillis;
  last_updated : TimestampMillis;
};

PublicGroupSummary

Public group information:

public type PublicGroupSummary = {
  is_public : Bool;
  subtype : ?GroupSubtype;
  gate : ?AccessGate;
  name : Text;
  wasm_version : BuildVersion;
  latest_message_index : ?MessageIndex;
  description : Text;
  events_ttl : ?Milliseconds;
  last_updated : TimestampMillis;
  avatar_id : ?Nat;
  local_user_index_canister_id : CanisterId;
  frozen : ?FrozenGroupInfo;
  latest_event_index : EventIndex;
  history_visible_to_new_joiners : Bool;
  chat_id : ChatId;
  events_ttl_last_updated : TimestampMillis;
  participant_count : Nat32;
  latest_message : ?MessageEventWrapper;
};

Access Control Types

AccessGate

Access requirements for groups/channels:

public type AccessGate = {
  #DiamondMember;
  #SnsNeuron : SnsNeuronGate;
  #TokenBalance : TokenBalanceGate;
  #Payment : PaymentGate;
  #VerifiedCredential : VerifiedCredentialGate;
};

Show Gate types

DiamondMember - Requires diamond membershipSnsNeuron - Requires SNS neuron with minimum stake/dissolve delay

public type SnsNeuronGate = {
  min_stake_e8s : ?Nat64;
  min_dissolve_delay : ?Milliseconds;
  governance_canister_id : CanisterId;
};

TokenBalance - Requires minimum token balance

public type TokenBalanceGate = {
  min_balance : Nat;
  ledger_canister_id : CanisterId;
};

Payment - Requires payment to join

public type PaymentGate = {
  fee : Nat;
  ledger_canister_id : CanisterId;
  amount : Nat;
};

Permission Types

GroupPermissions

public type GroupPermissions = {
  mention_all_members : PermissionRole;
  delete_messages : PermissionRole;
  remove_members : PermissionRole;
  update_group : PermissionRole;
  message_permissions : MessagePermissions;
  invite_users : PermissionRole;
  thread_permissions : ?MessagePermissions;
  change_roles : PermissionRole;
  add_members : PermissionRole;
  pin_messages : PermissionRole;
  react_to_messages : PermissionRole;
};

PermissionRole

public type PermissionRole = {
  #None;
  #Owner;
  #Admins;
  #Moderators;
  #Members;
};

GroupRole

public type GroupRole = {
  #Owner;
  #Admin;
  #Moderator;
  #Participant;
};

Time Types

public type TimestampMillis = Nat64;  // Unix timestamp in milliseconds
public type TimestampNanos = Nat64;   // Unix timestamp in nanoseconds
public type Milliseconds = Nat64;     // Duration in milliseconds

Canister Actor Types

The module defines actor interfaces for calling OpenChat canisters:

UserIndexCanister

public type UserIndexCanister = actor {
  c2c_register_bot : ({
    username : Text;
    display_name : ?Text;
  }) -> async InitializeBotResponse;
  
  user : query ({
    user_id : ?UserId;
    username : ?Text;
  }) -> async UserSummaryResponse;
  
  c2c_set_avatar : ({
    avatar_id : ?Nat;
  }) -> async SetAvatarResponse;
};

GroupIndexCanister

public type GroupIndexCanister = actor {
  public_summary : query ({
    invite_code : ?Nat64;
  }) -> async {
    #Success : PublicSummarySuccessResult;
    #NotAuthorized;
  };
  
  messages_by_message_index : query (
    MessagesByMessageIndexArgs
  ) -> async MessagesByMessageIndexResponse;
  
  send_message_v2 : (
    SendMessageV2Args
  ) -> async SendMessageResponse;
  
  edit_message_v2 : (
    EditMessageV2Args
  ) -> async EditMessageResponse;
};

CommunityIndexCanister

public type CommunityIndexCanister = actor {
  send_message : (
    SendChannelMessageArgs
  ) -> async SendMessageResponse;
  
  edit_message : (
    EditChannelMessageArgs
  ) -> async EditChannelMessageResponse;
  
  join_community : (
    JoinCommunityArgs
  ) -> async JoinCommunityResponse;
  
  join_channel : (
    JoinChannelArgs
  ) -> async JoinChannelResponse;
  
  summary : query ({
    invite_code : ?Nat64;
  }) -> async CommunitySummaryResponse;
};

LocalUserIndexCanister

public type LocalUserIndexCanister = actor {
  join_group : (
    JoinGroupArgs
  ) -> async JoinGroupResponse;
};

Usage Guidelines

Creating Text Messages

let content : MessageContentInitial = #Text({
  text = "Hello from my bot!";
});

Creating Image Messages

let content : MessageContentInitial = #Image({
  height = 800;
  width = 600;
  mime_type = "image/png";
  blob_reference = ?{ blob_id = 123; canister_id = imagePrincipal };
  thumbnail_data = "base64_thumbnail_data";
  caption = ?"Check out this image!";
});

Handling Message Responses

switch (sendResult) {
  case (#Success({ event_index; message_index })) {
    Debug.print("Message sent: " # Nat32.toText(message_index));
  };
  case (#UserNotInChannel) {
    Debug.print("Bot not in channel");
  };
  case (#TextTooLong(maxLength)) {
    Debug.print("Text exceeds " # Nat32.toText(maxLength));
  };
  // ... handle other cases
};

OCService - High-level service implementation
OCTypes - Type abstractions and patterns

OpenChat API Version

This binding is generated from OpenChat’s canister interface specifications. For the latest OpenChat API documentation, visit OpenChat documentation.

Bot Service

OpenChat API

Governance

Proposal Management

Utilities

​Overview

​Core Types

​Identity Types

​UserId

​ChannelId

​CommunityId

​ChatId

​Message Types

​MessageId

​MessageIndex

​EventIndex

​MessageContent

​MessageContentInitial

​Message

​MessageEventWrapper

​File & Media Types

​BlobReference

​Document

​Response Types

​Bot Registration

​InitializeBotResponse

​User Information

​UserSummaryResponse

​UserSummary

​Avatar

​SetAvatarArgs

​SetAvatarResponse

​Group Operations

​JoinGroupArgs

​JoinGroupResponse

​Community Operations

​JoinCommunityArgs

​JoinCommunityResponse

​JoinChannelArgs

​JoinChannelResponse

​Messaging Operations

​SendMessageResponse

​EditMessageResponse

​EditChannelMessageResponse

​Message Retrieval

​MessagesByMessageIndexArgs

​MessagesByMessageIndexResponse

​MessagesResponse

​Community & Group Structures

​CommunityCanisterCommunitySummary

​CommunityCanisterChannelSummary

​PublicGroupSummary

​Access Control Types

​AccessGate

​Permission Types

​GroupPermissions

​PermissionRole

​GroupRole

​Time Types

​Canister Actor Types

​UserIndexCanister

​GroupIndexCanister

​CommunityIndexCanister

​LocalUserIndexCanister

​Usage Guidelines

​Creating Text Messages

​Creating Image Messages

​Handling Message Responses

​Related Documentation

​OpenChat API Version

Build docs developers (and LLMs) love

Overview

Core Types

Identity Types

UserId

ChannelId

CommunityId

ChatId

Message Types

MessageId

MessageIndex

EventIndex

MessageContent

MessageContentInitial

Message

MessageEventWrapper

File & Media Types

BlobReference

Document

Response Types

Bot Registration

InitializeBotResponse

User Information

UserSummaryResponse

UserSummary

Avatar

SetAvatarArgs

SetAvatarResponse

Group Operations

JoinGroupArgs

JoinGroupResponse

Community Operations

JoinCommunityArgs

JoinCommunityResponse

JoinChannelArgs

JoinChannelResponse

Messaging Operations

SendMessageResponse

EditMessageResponse

EditChannelMessageResponse

Message Retrieval

MessagesByMessageIndexArgs

MessagesByMessageIndexResponse

MessagesResponse

Community & Group Structures

CommunityCanisterCommunitySummary

CommunityCanisterChannelSummary

PublicGroupSummary

Access Control Types

AccessGate

Permission Types

GroupPermissions

PermissionRole

GroupRole

Time Types

Canister Actor Types

UserIndexCanister

GroupIndexCanister

CommunityIndexCanister

LocalUserIndexCanister

Usage Guidelines

Creating Text Messages

Creating Image Messages

Handling Message Responses

Related Documentation

OpenChat API Version