Skip to main content
The message tool enables agents to send messages to users across different chat platforms with optional media attachments.

​
Tool Name

message

​
Description

Send a message to the user. Use this when you want to communicate something.

​
Parameters

​
content
string
required
The message content to send (text, markdown supported)
​
channel
string
Target channel (telegram, discord, cli, etc.). If not provided, uses the current context channel.
​
chat_id
string
Target chat or user ID. If not provided, uses the current context chat_id.
​
media
array
List of file paths to attach (images, audio, documents). Each item is a string file path.

​
Return Value

Returns a success message indicating where the message was sent, or an error message if:
  • No target channel/chat is specified
  • Message sending is not configured
  • An exception occurs during sending

​
Configuration

MessageTool(
    send_callback=async_send_function,  # Async function to handle message delivery
    default_channel="telegram",         # Default target channel
    default_chat_id="123456",          # Default target chat/user ID
    default_message_id="789"           # Optional: message ID for threading/replies
)

​
Context Management

The tool maintains context about the current conversation: 
# Set context from incoming message
message_tool.set_context(
    channel="telegram",
    chat_id="123456",
    message_id="789"
)

# Set send callback
message_tool.set_send_callback(async_send_function)

# Track per-turn sending
message_tool.start_turn()  # Call at the start of each agent turn

​
Examples

​
Basic Message

{
  "content": "Task completed successfully!"
}
Returns: 
Message sent to telegram:123456

​
Message with Formatting

{
  "content": "# Report\n\nProcessed **5 files**:\n- data.csv\n- report.pdf\n- summary.txt"
}

​
Message with Media

{
  "content": "Here are the generated charts:",
  "media": [
    "/tmp/chart1.png",
    "/tmp/chart2.png"
  ]
}
Returns: 
Message sent to telegram:123456 with 2 attachments

​
Message to Different Channel

{
  "content": "Alert: System maintenance in 10 minutes",
  "channel": "discord",
  "chat_id": "987654321"
}
Returns: 
Message sent to discord:987654321

​
Error: No Target

{
  "content": "Hello"
}
Returns (when no context is set): 
Error: No target channel/chat specified

​
Error: Not Configured

Returns (when send_callback is None): 
Error: Message sending not configured

​
Message Flow

  1. Agent calls message tool with content and optional parameters
  2. Tool resolves target (channel, chat_id) from parameters or context
  3. Creates OutboundMessage with content and media
  4. Calls send_callback to deliver message
  5. Returns confirmation or error

​
OutboundMessage Schema

OutboundMessage(
    channel="telegram",      # Target channel
    chat_id="123456",        # Target chat/user
    content="message text",  # Message content
    media=[],                # List of file paths
    metadata={
        "message_id": "789"  # Optional: for threading
    }
)

​
Platform Support

The message tool is platform-agnostic and works with any channel that implements the send callback interface:
  • Telegram: Full markdown support, media attachments
  • Discord: Embeds and markdown
  • CLI: Terminal output
  • Custom: Any platform implementing the callback

​
Best Practices

​
Use for User Communication

The message tool should be used when the agent needs to:
  • Report progress or results
  • Ask clarifying questions
  • Send alerts or notifications
  • Share generated content or media

​
Don’t Use for Tool Output

Avoid using the message tool to:
  • Log internal operations
  • Return tool execution results (return those directly)
  • Debug information (use logging instead)

​
Media Guidelines

  • Provide absolute file paths for media
  • Ensure files exist before attaching
  • Check file size limits for the target platform
  • Supported formats vary by channel (images, audio, documents, video)

​
Turn Tracking

The tool tracks whether a message has been sent in the current turn: 
message_tool.start_turn()  # Reset tracking
message_tool._sent_in_turn  # False initially

# After sending to the context channel/chat
message_tool._sent_in_turn  # True
This helps agents avoid sending duplicate messages in the same turn.

​
Implementation

See nanobot/agent/tools/message.py:9 for the full implementation.

Build docs developers (and LLMs) love

Get started for freeTalk to us