discordpp::MessageHandle Class Reference

Detailed Description

A MessageHandle represents a single message received by the SDK.

Chat types

The SDK supports two types of chat:

1. 1 on 1 chat between two users
2. Chat within a lobby

You can determine the context a message was sent in with the MessageHandle::Channel and ChannelHandle::Type methods. The SDK should only be receiving messages in the following channel types:

• DM
• Ephemeral DM
• Lobby

Syncing with Discord

In some situations messages sent from the SDK will also show up in Discord. In general this will happen for:

• 1 on 1 chat when at least one of the users is a full Discord user
• Lobby chat when the lobby is linked to a Discord channel

Additionally the message must have been sent by a user who is not banned on the Discord side.

Legal disclosures

As a convenience for game developers, the first time a user sends a message in game, and that message will show up on the Discord client, the SDK will inject a "fake" message into the chat, that contains a basic English explanation of what is happening to the user. You can identify these messages with the MessageHandle::DisclosureType method. We encourage you to customize the rendering of these messages, possibly changing the wording, translating them, and making them look more "official". You can choose to avoid rendering these as well.

History

The SDK keeps the 25 most recent messages in each channel in memory, but it does not have access to any historical messages sent before the SDK was connected. A MessageHandle will keep working though even after the SDK has discarded the message for being too old, you just won't be able to create a new MessageHandle objects for that message.

Unrenderable Content

Messages sent on Discord can contain content that may not be renderable in game, such as images, videos, embeds, polls, and more. The game isn't expected to render these, but instead show a small notice so the user is aware there is more content and a way to view that content on Discord. The MessageHandle::AdditionalContent method will contain data about the non-text content in this message.

There is also more information about the struct of messages on Discord here: https://discord.com/developers/docs/resources/message

Note: While the SDK allows you to send messages on behalf of a user, you must only do so in response to a user action. You should never automatically send messages.

Handle objects in the SDK hold a reference both to the underlying data, and to the SDK instance. Changes to the underlying data will generally be available on existing handles objects without having to re-create them. If the SDK instance is destroyed, but you still have a reference to a handle object, note that it will return the default value for all method calls (ie an empty string for methods that return a string).

Public Member Functions
	MessageHandle (MessageHandle &&other) noexcept
	Move constructor for MessageHandle.
MessageHandle &	operator= (MessageHandle &&other) noexcept
	Move assignment operator for MessageHandle.
	operator bool () const
	Returns true if the instance contains a valid object.
	MessageHandle (const MessageHandle &other)
	Copy constructor for MessageHandle.
MessageHandle &	operator= (const MessageHandle &other)
	Copy assignment operator for MessageHandle.
std::optional< discordpp::AdditionalContent >	AdditionalContent () const
	If the message contains non-text content, such as images, videos, embeds, polls, etc, this method will return information about that content.
std::optional< discordpp::UserHandle >	Author () const
	Returns the UserHandle for the author of this message.
uint64_t	AuthorId () const
	Returns the user ID of the user who sent this message.
std::optional< discordpp::ChannelHandle >	Channel () const
	Returns the ChannelHandle for the channel this message was sent in.
uint64_t	ChannelId () const
	Returns the channel ID this message was sent in.
std::string	Content () const
	Returns the content of this message, if any.
std::optional< discordpp::DisclosureTypes >	DisclosureType () const
	If this is an auto-generated message that is explaining some integration behavior to users, this method will return the type of disclosure so you can customize it.
uint64_t	EditedTimestamp () const
	The timestamp in millis since the epoch when the message was most recently edited.
uint64_t	Id () const
	Returns the ID of this message.
std::optional< discordpp::LobbyHandle >	Lobby () const
	Returns the LobbyHandle this message was sent in, if it was sent in a lobby.
std::unordered_map< std::string, std::string >	Metadata () const
	Returns any metadata the developer included with this message.
std::string	RawContent () const
	Returns the content of this message, if any, but without replacing any markup from emojis and mentions.
std::optional< discordpp::UserHandle >	Recipient () const
	Returns the UserHandle for the other participant in a DM, if this message was sent in a DM.
uint64_t	RecipientId () const
	When this message was sent in a DM or Ephemeral DM, this method will return the ID of the other user in that DM.
bool	SentFromGame () const
	Returns true if this message was sent in-game, otherwise false (i.e. from Discord itself).
uint64_t	SentTimestamp () const
	The timestamp in millis since the epoch when the message was sent.

Static Public Attributes
static const MessageHandle	nullobj
	Uninitialized instance of MessageHandle.

Constructor & Destructor Documentation

MessageHandle() [1/2]

discordpp::MessageHandle::MessageHandle ( MessageHandle && other )

noexcept

Move constructor for MessageHandle.

MessageHandle() [2/2]

discordpp::MessageHandle::MessageHandle

(

const MessageHandle &

other

)

Copy constructor for MessageHandle.

Member Function Documentation

AdditionalContent()

std::optional< discordpp::AdditionalContent > discordpp::MessageHandle::AdditionalContent

(

)

const

If the message contains non-text content, such as images, videos, embeds, polls, etc, this method will return information about that content.

Author()

std::optional< discordpp::UserHandle > discordpp::MessageHandle::Author

(

)

const

Returns the UserHandle for the author of this message.

AuthorId()

uint64_t discordpp::MessageHandle::AuthorId

(

)

const

Returns the user ID of the user who sent this message.

Channel()

std::optional< discordpp::ChannelHandle > discordpp::MessageHandle::Channel

(

)

const

Returns the ChannelHandle for the channel this message was sent in.

ChannelId()

uint64_t discordpp::MessageHandle::ChannelId

(

)

const

Returns the channel ID this message was sent in.

Content()

std::string discordpp::MessageHandle::Content

(

)

const

Returns the content of this message, if any.

A message can be blank if it was sent from Discord but only contains content such as image attachments. Certain types of markup, such as markup for emojis and mentions, will be auto replaced with a more human readable form, such as @username or :emoji_name:.

DisclosureType()

std::optional< discordpp::DisclosureTypes > discordpp::MessageHandle::DisclosureType

(

)

const

If this is an auto-generated message that is explaining some integration behavior to users, this method will return the type of disclosure so you can customize it.

EditedTimestamp()

uint64_t discordpp::MessageHandle::EditedTimestamp

(

)

const

The timestamp in millis since the epoch when the message was most recently edited.

Returns 0 if the message has not been edited yet.

Id()

uint64_t discordpp::MessageHandle::Id

(

)

const

Returns the ID of this message.

Lobby()

std::optional< discordpp::LobbyHandle > discordpp::MessageHandle::Lobby

(

)

const

Returns the LobbyHandle this message was sent in, if it was sent in a lobby.

Metadata()

std::unordered_map< std::string, std::string > discordpp::MessageHandle::Metadata

(

)

const

Returns any metadata the developer included with this message.

Metadata is just a set of simple string key/value pairs. An example use case might be to include a character name so you can customize how a message renders in game.

operator bool()

discordpp::MessageHandle::operator bool ( ) const

inline

Returns true if the instance contains a valid object.

operator=() [1/2]

MessageHandle & discordpp::MessageHandle::operator=

(

const MessageHandle &

other

)

Copy assignment operator for MessageHandle.

operator=() [2/2]

MessageHandle & discordpp::MessageHandle::operator= ( MessageHandle && other )

noexcept

Move assignment operator for MessageHandle.

RawContent()

std::string discordpp::MessageHandle::RawContent

(

)

const

Returns the content of this message, if any, but without replacing any markup from emojis and mentions.

A message can be blank if it was sent from Discord but only contains content such as image attachments.

Recipient()

std::optional< discordpp::UserHandle > discordpp::MessageHandle::Recipient

(

)

const

Returns the UserHandle for the other participant in a DM, if this message was sent in a DM.

RecipientId()

uint64_t discordpp::MessageHandle::RecipientId

(

)

const

When this message was sent in a DM or Ephemeral DM, this method will return the ID of the other user in that DM.

SentFromGame()

bool discordpp::MessageHandle::SentFromGame

(

)

const

Returns true if this message was sent in-game, otherwise false (i.e. from Discord itself).

SentTimestamp()

uint64_t discordpp::MessageHandle::SentTimestamp

(

)

const

The timestamp in millis since the epoch when the message was sent.

Member Data Documentation

nullobj

const MessageHandle discordpp::MessageHandle::nullobj

static

Uninitialized instance of MessageHandle.