Mirra Messaging Events

Handle messages sent and received in Mirra chats

Mirra messaging events fire when messages are sent or received in Mirra's internal chat system. These events include automation tracking metadata, making it possible to build flows that react to both user messages and automated messages from other flows or the SDK.

Event Types

mirra.message

The mirra.message event fires when a message is sent in a Mirra chat (direct or group). This event captures message content, chat context, media attachments, and automation metadata for tracking whether the message was sent by a user, a flow, or the SDK.

Event Type:

type: 'mirra.message'
source: 'mirra'

Fields:

content.text (string)

Message text content. Empty string if the message is media-only.

content.contentType (ContentType)

Always 'message' for Mirra messages.

actor.id (string)

User ID of the message sender.

actor.name (string)

Display name of the sender.

actor.actorType (ActorType)

'user' for regular messages, 'agent' for AI-generated messages.

mirra.messageId (string)

Unique message identifier.

mirra.chatInstanceId (string)

Chat instance where the message was sent.

mirra.scope (ChatScope)

Chat scope: 'direct' for 1-on-1, 'group' for group chats.

mirra.groupId (string | null)

Group ID if this is a group chat message. Null for direct messages.

mirra.isGroupChat (boolean)

True if the message is in a group chat.

mirra.hasMedia (boolean)

True if the message contains media.

mirra.mediaType ('image' | 'gif' | null)

Type of media attachment if present.

mirra.replyTo (object | null)

Reply context if this message is a reply to another message. Null if not a reply.

Field	Type	Description
messageId	string	ID of the message being replied to
senderId	string	User ID of the original message sender
automation	MirraAutomationMetadata | null	Automation metadata of the original message

mirra.automation (MirraAutomationMetadata)

Tracks whether this message was sent by a user, a flow, or the SDK.

Field	Type	Description
isAutomated	boolean	True if the message was sent programmatically
source	'sdk' | 'flow' | 'user'	How the message was sent
flowId	string | null	Flow ID if sent by a flow
flowTitle	string | null	Flow title if sent by a flow

enrichment (EventEnrichment | null)

Content enrichment including detected tickers, companies, and sentiment. Null until processing completes.

Example - Group Chat Monitor:

export async function handler(event, context) {
  // Only process group messages from real users (not automated)
  if (!event.mirra.isGroupChat || event.mirra.automation.isAutomated) {
    return { success: true, skipped: true };
  }
 
  // Log group activity
  await mirra.memory.create({
    type: 'group_message',
    content: event.content.text,
    metadata: {
      groupId: event.mirra.groupId,
      sender: event.actor.name,
      hasMedia: event.mirra.hasMedia,
      timestamp: event.timestamp
    }
  });
 
  return { success: true };
}

Example - Reply Tracker:

export async function handler(event, context) {
  // Track replies to automated messages (flow responses)
  if (!event.mirra.replyTo?.automation?.isAutomated) {
    return { success: true, skipped: true };
  }
 
  // A user replied to an automated message
  await mirra.google.sheets.appendRow({
    spreadsheetId: 'your-sheet-id',
    sheetName: 'User Replies',
    values: [
      new Date().toISOString(),
      event.actor.name,
      event.content.text,
      event.mirra.replyTo.automation.flowTitle || 'SDK',
      event.mirra.replyTo.automation.source
    ]
  });
 
  return { success: true };
}

Example - Keyword Alert:

export async function handler(event, context) {
  const text = event.content.text.toLowerCase();
  const keywords = ['help', 'urgent', 'bug', 'broken'];
 
  const matched = keywords.filter(kw => text.includes(kw));
  if (matched.length === 0) {
    return { success: true, skipped: true };
  }
 
  await mirra.telegram.sendMessage({
    chatId: 'admin-alerts',
    text: `🔔 Keywords detected in Mirra chat\n\nFrom: ${event.actor.name}\nChat: ${event.mirra.isGroupChat ? 'Group' : 'Direct'}\nKeywords: ${matched.join(', ')}\n\n"${event.content.text}"`
  });
 
  return { success: true };
}

Subscription Examples:

// All Mirra messages
{
  "eventType": "mirra.message"
}
 
// Group messages only
{
  "eventType": "mirra.message",
  "conditions": [
    {
      "field": "mirra.isGroupChat",
      "operator": "equals",
      "value": true
    }
  ]
}
 
// Only user messages (not automated)
{
  "eventType": "mirra.message",
  "conditions": [
    {
      "field": "mirra.automation.isAutomated",
      "operator": "equals",
      "value": false
    }
  ]
}
 
// Messages with specific keywords
{
  "eventType": "mirra.message",
  "conditions": [
    {
      "field": "content.text",
      "operator": "contains",
      "value": "help"
    }
  ]
}

See Also

• Events Overview - Event system architecture
• Telegram Events - Telegram automation
• Resources - Mirra messaging adapter API