Activity Class

An Activity is the basic communication type for the protocol.

Constructor

pydantic model Activity

Parameters

Name	Description
type Required	str or ActivityTypes Contains the activity type. Possible values include: 'message', 'contactRelationUpdate', 'conversationUpdate', 'typing', 'endOfConversation', 'event', 'invoke', 'deleteUserData', 'messageUpdate', 'messageDelete', 'installationUpdate', 'messageReaction', 'suggestion', 'trace', 'handoff'
id Required	str Contains an ID that uniquely identifies the activity on the channel.
timestamp Required	datetime Contains the date and time that the message was sent, in UTC, expressed in ISO-8601 format.
local_timestamp Required	datetime Contains the local date and time of the message expressed in ISO-8601 format. For example, 2016-09-23T13:07:49.4714686-07:00.
local_timezone Required	str Contains the name of the local timezone of the message, expressed in IANA Time Zone database format. For example, America/Los_Angeles.
service_url Required	str Contains the URL that specifies the channel's service endpoint. Set by the channel.
channel_id Required	ChannelId Contains an ID that uniquely identifies the channel (and possibly the sub-channel). Set by the channel.
from_property Required	ChannelAccount Identifies the sender of the message.
conversation Required	ConversationAccount Identifies the conversation to which the activity belongs.
recipient Required	ChannelAccount Identifies the recipient of the message.
text_format Required	str or TextFormatTypes Format of text fields Default:markdown. Possible values include: 'markdown', 'plain', 'xml'
attachment_layout Required	str or AttachmentLayoutTypes The layout hint for multiple attachments. Default: list. Possible values include: 'list', 'carousel'
members_added Required	list[ChannelAccount] The collection of members added to the conversation.
members_removed Required	list[ChannelAccount] The collection of members removed from the conversation.
reactions_added Required	list[MessageReaction] The collection of reactions added to the conversation.
reactions_removed Required	list[MessageReaction] The collection of reactions removed from the conversation.
topic_name Required	str The updated topic name of the conversation.
history_disclosed Required	bool Indicates whether the prior history of the channel is disclosed.
locale Required	str A locale name for the contents of the text field. The locale name is a combination of an ISO 639 two- or three-letter culture code associated with a language and an ISO 3166 two-letter subculture code associated with a country or region. The locale name can also correspond to a valid BCP-47 language tag.
text Required	str The text content of the message.
speak Required	str The text to speak.
input_hint Required	str or InputHints Indicates whether your agent is accepting, expecting, or ignoring user input after the message is delivered to the client. Possible values include: 'acceptingInput', 'ignoringInput', 'expectingInput'
summary Required	str The text to display if the channel cannot render cards.
suggested_actions Required	SuggestedActions The suggested actions for the activity.
attachments Required	list[Attachment] Attachments
entities Required	list[Entity] Represents the entities that were mentioned in the message.
channel_data Required	object Contains channel-specific content.
action Required	str Indicates whether the recipient of a contactRelationUpdate was added or removed from the sender's contact list.
reply_to_id Required	str Contains the ID of the message to which this message is a reply.
label Required	str A descriptive label for the activity.
value_type Required	str The type of the activity's value object.
value Required	object A value that is associated with the activity.
name Required	str The name of the operation associated with an invoke or event activity.
relates_to Required	ConversationReference A reference to another conversation or activity.
code Required	str or EndOfConversationCodes The a code for endOfConversation activities that indicates why the conversation ended. Possible values include: 'unknown', 'completedSuccessfully', 'userCancelled', 'botTimedOut', 'botIssuedInvalidMessage', 'channelFailed'
expiration Required	datetime The time at which the activity should be considered to be "expired" and should not be presented to the recipient.
importance Required	str or ActivityImportance The importance of the activity. Possible values include: 'low', 'normal', 'high'
delivery_mode Required	str or DeliveryModes A delivery hint to signal to the recipient alternate delivery paths for the activity. The default delivery mode is "default". Possible values include: 'normal', 'notification', 'expectReplies', 'ephemeral'
listen_for Required	list[str] List of phrases and references that speech and language priming systems should listen for
text_highlights Required	list[TextHighlight] The collection of text fragments to highlight when the activity contains a ReplyToId value.
semantic_action Required	SemanticAction An optional programmatic action accompanying this request
caller_id Required	str A string containing an IRI identifying the caller of an agent. This field is not intended to be transmitted over the wire, but is instead populated by agents and clients based on cryptographically verifiable data that asserts the identity of the callers (e.g. tokens).

Keyword-Only Parameters

Name	Description
type Required
id	Default value: None
timestamp	Default value: None
localTimestamp	Default value: None
localTimezone	Default value: None
serviceUrl	Default value: None
from_property	Default value: None
conversation	Default value: None
recipient	Default value: None
textFormat	Default value: None
attachmentLayout	Default value: None
membersAdded	Default value: None
membersRemoved	Default value: None
reactionsAdded	Default value: None
reactionsRemoved	Default value: None
topicName	Default value: None
historyDisclosed	Default value: None
locale	Default value: None
text	Default value: None
speak	Default value: None
inputHint	Default value: None
summary	Default value: None
suggestedActions	Default value: None
attachments	Default value: None
entities	Default value: None
channelData	Default value: None
action	Default value: None
replyToId	Default value: None
label	Default value: None
valueType	Default value: None
value	Default value: None
name	Default value: None
relatesTo	Default value: None
code	Default value: None
expiration	Default value: None
importance	Default value: None
deliveryMode	Default value: None
listenFor	Default value: None
textHighlights	Default value: None
semanticAction	Default value: None
callerId	Default value: None

Methods

add_ai_metadata	Adds AI entity to an activity to indicate AI-generated content.
apply_conversation_reference	Updates this activity with the delivery information from an existing ConversationReference.
as_contact_relation_update_activity	Returns this activity as a ContactRelationUpdateActivity object; or None, if this is not that type of activity.
as_conversation_update_activity	Returns this activity as a ConversationUpdateActivity object; or None, if this is not that type of activity.
as_end_of_conversation_activity	Returns this activity as an EndOfConversationActivity object; or None, if this is not that type of activity.
as_event_activity	Returns this activity as an EventActivity object; or None, if this is not that type of activity.
as_handoff_activity	Returns this activity as a HandoffActivity object; or None, if this is not that type of activity.
as_installation_update_activity	Returns this activity as an InstallationUpdateActivity object; or None, if this is not that type of activity.
as_invoke_activity	Returns this activity as an InvokeActivity object; or None, if this is not that type of activity.
as_message_activity	Returns this activity as a MessageActivity object; or None, if this is not that type of activity.
as_message_delete_activity	Returns this activity as a MessageDeleteActivity object; or None, if this is not that type of activity.
as_message_reaction_activity	Returns this activity as a MessageReactionActivity object; or None, if this is not that type of activity.
as_message_update_activity	Returns this activity as an MessageUpdateActivity object; or None, if this is not that type of activity.
as_suggestion_activity	Returns this activity as a SuggestionActivity object; or None, if this is not that type of activity.
as_trace_activity	Returns this activity as a TraceActivity object; or None, if this is not that type of activity.
as_typing_activity	Returns this activity as a TypingActivity object; or null, if this is not that type of activity.
create_contact_relation_update_activity	Creates an instance of the Activity class as a ContactRelationUpdateActivity object.
create_conversation_update_activity	Creates an instance of the Activity class as a ConversationUpdateActivity object.
create_end_of_conversation_activity	Creates an instance of the Activity class as an EndOfConversationActivity object.
create_event_activity	Creates an instance of the Activity class as an EventActivity object.
create_handoff_activity	Creates an instance of the Activity class as a HandoffActivity object.
create_invoke_activity	Creates an instance of the Activity class as an InvokeActivity object.
create_message_activity	Creates an instance of the Activity class as a MessageActivity object.
create_reply	Creates a new message activity as a response to this activity.
create_trace	Creates a new trace activity based on this activity.
create_trace_activity	Creates an instance of the Activity class as a TraceActivity object.
create_typing_activity	Creates an instance of the Activity class as a TypingActivity object.
get_agentic_instance_id	Gets the agent instance ID from the context if it's an agentic request.
get_agentic_user	Gets the agentic user (agenticUserId) from the context if it's an agentic request.
get_conversation_reference	Creates a ConversationReference based on this activity.
get_mentions	Resolves the mentions from the entities of this activity.
get_product_info_entity
get_reply_conversation_reference	Create a ConversationReference based on this Activity's Conversation info and the ResourceResponse from sending an activity.
has_content	Indicates whether this activity has content.
is_agentic_request
is_from_streaming_connection	Determine if the Activity was sent via an Http/Https connection or Streaming. This can be determined by looking at the service_url property: (1) All channels that send messages via http/https are not streaming. (2) Channels that send messages via streaming have a ServiceUrl that does not begin with http/https.

add_ai_metadata

Adds AI entity to an activity to indicate AI-generated content.

add_ai_metadata(citations: list[ClientCitation] | None = None, usage_info: SensitivityUsageInfo | None = None) -> None

Parameters

Name	Description
activity Required	The activity to modify
citations	list[ClientCitation] | None Optional list of citations Default value: None
usage_info	SensitivityUsageInfo | None Optional sensitivity usage information Default value: None

Returns

Type	Description
None

apply_conversation_reference

Updates this activity with the delivery information from an existing ConversationReference.

apply_conversation_reference(reference: ConversationReference, is_incoming: bool = False)

Parameters

Name	Description
reference Required	ConversationReference The existing conversation reference.
is_incoming	bool Optional, True to treat the activity as an incoming activity, where the agent is the recipient; otherwise, False. Default is False, and the activity will show the agent as the sender. Default value: False

Returns

Type	Description
	This activity, updated with the delivery information.

Remarks

Call GetConversationReference on an incoming activity to get a conversation reference that you can then use to update an outgoing activity with the correct delivery information.

as_contact_relation_update_activity

Returns this activity as a ContactRelationUpdateActivity object; or None, if this is not that type of activity.

as_contact_relation_update_activity()

Returns

Type	Description
	This activity as a message activity; or None.

as_conversation_update_activity

Returns this activity as a ConversationUpdateActivity object; or None, if this is not that type of activity.

as_conversation_update_activity()

Returns

Type	Description
	This activity as a conversation update activity; or None.

as_end_of_conversation_activity

Returns this activity as an EndOfConversationActivity object; or None, if this is not that type of activity.

as_end_of_conversation_activity()

Returns

Type	Description
	This activity as an end of conversation activity; or None.

as_event_activity

Returns this activity as an EventActivity object; or None, if this is not that type of activity.

as_event_activity()

Returns

Type	Description
	This activity as an event activity; or None.

as_handoff_activity

Returns this activity as a HandoffActivity object; or None, if this is not that type of activity.

as_handoff_activity()

Returns

Type	Description
	This activity as a handoff activity; or None.

as_installation_update_activity

Returns this activity as an InstallationUpdateActivity object; or None, if this is not that type of activity.

as_installation_update_activity()

Returns

Type	Description
	This activity as an installation update activity; or None.

as_invoke_activity

Returns this activity as an InvokeActivity object; or None, if this is not that type of activity.

as_invoke_activity()

Returns

Type	Description
	This activity as an invoke activity; or None.

as_message_activity

Returns this activity as a MessageActivity object; or None, if this is not that type of activity.

as_message_activity()

Returns

Type	Description
	This activity as a message activity; or None.

as_message_delete_activity

Returns this activity as a MessageDeleteActivity object; or None, if this is not that type of activity.

as_message_delete_activity()

Returns

Type	Description
	This activity as a message delete request; or None.

as_message_reaction_activity

Returns this activity as a MessageReactionActivity object; or None, if this is not that type of activity.

as_message_reaction_activity()

Returns

Type	Description
	This activity as a message reaction activity; or None.

as_message_update_activity

Returns this activity as an MessageUpdateActivity object; or None, if this is not that type of activity.

as_message_update_activity()

Returns

Type	Description
	This activity as a message update request; or None.

as_suggestion_activity

Returns this activity as a SuggestionActivity object; or None, if this is not that type of activity.

as_suggestion_activity()

Returns

Type	Description
	This activity as a suggestion activity; or None.

as_trace_activity

Returns this activity as a TraceActivity object; or None, if this is not that type of activity.

as_trace_activity()

Returns

Type	Description
	This activity as a trace activity; or None.

as_typing_activity

Returns this activity as a TypingActivity object; or null, if this is not that type of activity.

as_typing_activity()

Returns

Type	Description
	This activity as a typing activity; or null.

create_contact_relation_update_activity

Creates an instance of the Activity class as a ContactRelationUpdateActivity object.

static create_contact_relation_update_activity()

Returns

Type	Description
	The new contact relation update activity.

create_conversation_update_activity

Creates an instance of the Activity class as a ConversationUpdateActivity object.

static create_conversation_update_activity()

Returns

Type	Description
	The new conversation update activity.

create_end_of_conversation_activity

Creates an instance of the Activity class as an EndOfConversationActivity object.

static create_end_of_conversation_activity()

Returns

Type	Description
	The new end of conversation activity.

create_event_activity

Creates an instance of the Activity class as an EventActivity object.

static create_event_activity()

Returns

Type	Description
	The new event activity.

create_handoff_activity

Creates an instance of the Activity class as a HandoffActivity object.

static create_handoff_activity()

Returns

Type	Description
	The new handoff activity.

create_invoke_activity

Creates an instance of the Activity class as an InvokeActivity object.

static create_invoke_activity()

Returns

Type	Description
	The new invoke activity.

create_message_activity

Creates an instance of the Activity class as a MessageActivity object.

static create_message_activity()

Returns

Type	Description
	The new message activity.

create_reply

Creates a new message activity as a response to this activity.

create_reply(text: str = None, locale: str = None)

Parameters

Name	Description
text	str The text of the reply. Default value: None
locale	str The language code for the text. Default value: None

Returns

Type	Description
	The new message activity.

Remarks

The new activity sets up routing information based on this activity.

create_trace

Creates a new trace activity based on this activity.

create_trace(name: str, value: object = None, value_type: str = None, label: str = None)

Parameters

Name	Description
name Required	str The name of the trace operation to create.
value	object Optional, the content for this trace operation. Default value: None
value_type	str Optional, identifier for the format of the value. Default is the name of type of the value. Default value: None
label	str Optional, a descriptive label for this trace operation. Default value: None

Returns

Type	Description
	The new trace activity.

create_trace_activity

Creates an instance of the Activity class as a TraceActivity object.

static create_trace_activity(name: str, value: object = None, value_type: str = None, label: str = None)

Parameters

Name	Description
name Required	str The name of the trace operation to create.
value	object Optional, the content for this trace operation. Default value: None
value_type	str Optional, identifier for the format of the value. Default is the name of type of the value. Default value: None
label	str Optional, a descriptive label for this trace operation. Default value: None

Returns

Type	Description
	The new trace activity.

create_typing_activity

Creates an instance of the Activity class as a TypingActivity object.

static create_typing_activity() -> Activity

Returns

Type	Description
Activity	The new typing activity.

get_agentic_instance_id

Gets the agent instance ID from the context if it's an agentic request.

get_agentic_instance_id() -> str | None

Returns

Type	Description
str | None

get_agentic_user

Gets the agentic user (agenticUserId) from the context if it's an agentic request.

get_agentic_user() -> str | None

Returns

Type	Description
str | None

get_conversation_reference

Creates a ConversationReference based on this activity.

get_conversation_reference() -> ConversationReference

Returns

Type	Description
ConversationReference	A conversation reference for the conversation that contains this activity.

get_mentions

Resolves the mentions from the entities of this activity.

get_mentions() -> list[Mention]

Returns

Type	Description
list[Mention]	The array of mentions; or an empty array, if none are found.

Remarks

This method is defined on the Activity class, but is only intended for use with a message activity, where the activity Activity.Type is set to ActivityTypes.Message.

get_product_info_entity

get_product_info_entity() -> ProductInfo | None

Returns

Type	Description
ProductInfo | None

get_reply_conversation_reference

Create a ConversationReference based on this Activity's Conversation info and the ResourceResponse from sending an activity.

get_reply_conversation_reference(reply: ResourceResponse) -> ConversationReference

Parameters

Name	Description
reply Required	ResourceResponse ResourceResponse returned from send_activity.

Returns

Type	Description
ConversationReference	A ConversationReference that can be stored and used later to delete or update the activity.

has_content

Indicates whether this activity has content.

has_content() -> bool

Returns

Type	Description
bool	True, if this activity has any content to send; otherwise, false.

Remarks

This method is defined on the Activity class, but is only intended for use with a message activity, where the activity Activity.Type is set to ActivityTypes.Message.

is_agentic_request

is_agentic_request() -> bool

Returns

Type	Description
bool

is_from_streaming_connection

Determine if the Activity was sent via an Http/Https connection or Streaming. This can be determined by looking at the service_url property: (1) All channels that send messages via http/https are not streaming. (2) Channels that send messages via streaming have a ServiceUrl that does not begin with http/https.

is_from_streaming_connection() -> bool

Returns

Type	Description
bool	True if the Activity originated from a streaming connection.

Attributes

action

field action: NonEmptyString = None

attachment_layout

field attachment_layout: NonEmptyString = None (alias 'attachmentLayout')

attachments

field attachments: list[Attachment] = None

caller_id

field caller_id: NonEmptyString = None (alias 'callerId')

channel_data

field channel_data: object = None (alias 'channelData')

code

field code: NonEmptyString = None

conversation

field conversation: ConversationAccount = None

delivery_mode

field delivery_mode: NonEmptyString = None (alias 'deliveryMode')

entities

field entities: list[SerializeAsAny[Entity]] = None

expiration

field expiration: datetime = None

from_property

field from_property: ChannelAccount = None (alias 'from')

history_disclosed

field history_disclosed: bool = None (alias 'historyDisclosed')

id

field id: NonEmptyString | None = None

importance

field importance: NonEmptyString = None

input_hint

field input_hint: NonEmptyString = None (alias 'inputHint')

label

field label: NonEmptyString = None

listen_for

field listen_for: list[NonEmptyString] = None (alias 'listenFor')

local_timestamp

field local_timestamp: datetime = None (alias 'localTimestamp')

local_timezone

field local_timezone: NonEmptyString = None (alias 'localTimezone')

locale

field locale: NonEmptyString = None

members_added

field members_added: list[ChannelAccount] = None (alias 'membersAdded')

members_removed

field members_removed: list[ChannelAccount] = None (alias 'membersRemoved')

name

field name: NonEmptyString = None

reactions_added

field reactions_added: list[MessageReaction] = None (alias 'reactionsAdded')

reactions_removed

field reactions_removed: list[MessageReaction] = None (alias 'reactionsRemoved')

recipient

field recipient: ChannelAccount = None

relates_to

field relates_to: ConversationReference = None (alias 'relatesTo')

reply_to_id

field reply_to_id: NonEmptyString = None (alias 'replyToId')

semantic_action

field semantic_action: SemanticAction = None (alias 'semanticAction')

service_url

field service_url: NonEmptyString = None (alias 'serviceUrl')

speak

field speak: str = None

suggested_actions

field suggested_actions: SuggestedActions = None (alias 'suggestedActions')

summary

field summary: NonEmptyString = None

text

field text: str = None

text_format

field text_format: NonEmptyString = None (alias 'textFormat')

text_highlights

field text_highlights: list[TextHighlight] = None (alias 'textHighlights')

timestamp

field timestamp: datetime = None

topic_name

field topic_name: NonEmptyString = None (alias 'topicName')

type

field type: NonEmptyString [Required]

value

field value: object = None

value_type

field value_type: NonEmptyString = None (alias 'valueType')