Skip to content

chats

import "github.com/pzsp-teams/lib/chats"

Package chats provides various chat-related operations. It abstracts the underlying Microsoft Graph API calls. Package provides two services implementations - one with cache and one without cache. Both can be instantiated and used interchangeably. If cache is enabled, the service will use a caching layer to store and retrieve chat/member references, improving performance and reducing API calls. Concepts:

  • Chats are either one-on-one or group chats.
  • Users are identified by userID or email.
  • Some operations require messageID - these can be obtained via ListMessages.
  • ChatRef and GroupChatRef are references to chats used in method parameters.
  • If chatRef is a topic and is not unique, an ambiguity error is returned.
  • The authenticated user (derived from MSAL) is the one making the API calls (appropriate scopes must be granted).

If an async cached service is used, call Wait() to ensure all background cache updates are finished.

Index

type ChatRef

ChatRef is an interface representing a reference to a chat, which can be either a group chat or a one-on-one chat.

type ChatRef interface {
    // contains filtered or unexported methods
}

type GroupChatRef

GroupChatRef identifies a group chat. It may reference a chat by:

  • unique chatID

  • chat topic

Note: Using chat topic may lead to ambiguities (which must be resolved manually) if multiple group chats share the same topic.

type GroupChatRef struct {
    Ref string
}

type OneOnOneChatRef

OneOnOneChatRef identifies a one-on-one chat. It may reference a chat by:

  • unique chatID

  • recipient's reference (userID, email)

Note: Chat must be established between the logged-in user and the recipient for resolution to succeed.

type OneOnOneChatRef struct {
    Ref string
}

type Service

Service defines the interface for chat-related operations. It includes methods for creating chats, managing members, sending messages, and more.

type Service interface {
    // CreateOneOnOne creates a one-on-one chat with the given recipient.
    // The authenticated user is automatically added to the chat.
    CreateOneOnOne(ctx context.Context, recipientRef string) (*models.Chat, error)

    // CreateGroup creates a group chat with the given recipients and topic.
    // The authenticated user may be included by setting includeMe to true.
    CreateGroup(ctx context.Context, recipientRefs []string, topic string, includeMe bool) (*models.Chat, error)

    // GetChat retrieves a chat (one-on-one or group) by its reference.
    GetChat(ctx context.Context, chatRef ChatRef) (*models.Chat, error)

    // AddMemberToGroupChat adds a user to a group chat.
    AddMemberToGroupChat(ctx context.Context, chatRef GroupChatRef, userRef string) (*models.Member, error)

    // RemoveMemberFromGroupChat removes a user from a group chat.
    RemoveMemberFromGroupChat(ctx context.Context, chatRef GroupChatRef, userRef string) error

    // ListGroupChatMembers returns all members of a group chat.
    ListGroupChatMembers(ctx context.Context, chatRef GroupChatRef) ([]*models.Member, error)

    // UpdateGroupChatTopic updates the topic of a group chat.
    UpdateGroupChatTopic(ctx context.Context, chatRef GroupChatRef, topic string) (*models.Chat, error)

    // ListMessages returns all messages in a chat.
    //
    // NextLink in the returned MessageCollection can be used to retrieve the next page of messages.
    ListMessages(ctx context.Context, chatRef ChatRef, includeSystem bool, nextLink *string) (*models.MessageCollection, error)

    // SendMessage sends a message to a chat.
    // Body parameter is the body of the message. It includes:
    //   - Content: the text or html content of the message.
    //   - ContentType: the type of content (text or html).
    //   - Mentions: optional mentions to include in the message.
    SendMessage(ctx context.Context, chatRef ChatRef, body models.MessageBody) (*models.Message, error)

    // DeleteMessage deletes a message from a chat. Action is reversible - soft delete is performed.
    DeleteMessage(ctx context.Context, chatRef ChatRef, messageID string) error

    // GetMessage retrieves a specific message from a chat by its ID.
    GetMessage(ctx context.Context, chatRef ChatRef, messageID string) (*models.Message, error)

    // ListChats returns all chats, optionally filtered by chat type.
    ListChats(ctx context.Context, chatType *models.ChatType) ([]*models.Chat, error)

    // ListAllMessages returns all messages in all chats within the specified time range. Top limits the number of messages returned.
    //
    // Note: This operation does not work in delegated permission mode.
    ListAllMessages(ctx context.Context, startTime, endTime *time.Time, top *int32) ([]*models.Message, error)

    // ListPinnedMessages returns all pinned messages in a chat.
    ListPinnedMessages(ctx context.Context, chatRef ChatRef) ([]*models.Message, error)

    // PinMessage pins a message in a chat.
    PinMessage(ctx context.Context, chatRef ChatRef, messageID string) error

    // UnpinMessage unpins a message in a chat.
    UnpinMessage(ctx context.Context, chatRef ChatRef, pinnedMessageID string) error

    // GetMentions resolves raw mention strings to Mention objects in the context of a chat. Raw mentions can be:
    //   - Emails
    //   - Everyone (for group chats)
    //   - User IDs
    GetMentions(ctx context.Context, chatRef ChatRef, rawMentions []string) ([]models.Mention, error)

    // SearchMessages searches for messages in a chat matching the specified query and options.
    //
    // If chatRef is nil, searches across all chats the user has access to.
    //
    // Returns search results containing matching messages.
    SearchMessages(ctx context.Context, chatRef ChatRef, opts *search.SearchMessagesOptions, searchConfig *search.SearchConfig) (*search.SearchResults, error)
}

func NewService

func NewService(chatOps chatOps, cr resolver.ChatResolver) Service

NewService creates a new instance of the chat service.

Generated by gomarkdoc