The message tool allows agents to send messages directly to users on various chat platforms.
message
Send a message to a user on a chat channel.
Parameters
The message content to send.
Optional target channel (e.g., “telegram”, “whatsapp”, “discord”). If not specified, uses the current conversation’s channel.
Optional target chat or user ID. If not specified, uses the current conversation’s chat ID.
Returns
Silent confirmation: "Message sent to {channel}:{chat_id}"The result is marked as silent since the user already receives the message directly.
Usage Example
{
"tool": "message",
"parameters": {
"content": "Your analysis is complete. Found 42 items matching the criteria."
}
}
Context Management
The message tool uses conversation context to determine the default recipient:
messageTool.SetContext("telegram", "123456789")
channel defaults to the conversation’s channelchat_id defaults to the conversation’s chat ID
Override Context
Explicitly specify different channel/chat:
{
"tool": "message",
"parameters": {
"content": "Alert: System maintenance in 5 minutes",
"channel": "telegram",
"chat_id": "987654321"
}
}
Send Tracking
The message tool tracks whether messages were sent in the current processing round:
if messageTool.HasSentInRound() {
// Message was sent during this round
}
SetContext() is called for a new processing round.
Callback Integration
The message tool uses a callback function to deliver messages:
type SendCallback func(channel, chatID, content string) error
messageTool.SetSendCallback(func(channel, chatID, content string) error {
return sendToChannel(channel, chatID, content)
})
Callback Requirements
- channel: Platform identifier (“telegram”, “whatsapp”, etc.)
- chatID: Unique identifier for the chat or user
- content: Message text to send
- Returns: Error if sending fails
Error Handling
Missing Content
{
"error": "content is required"
}
Missing Context
{
"error": "No target channel/chat specified"
}
- No context was set via
SetContext()
channel or chat_id not provided in parameters
{
"error": "Message sending not configured"
}
Send Failure
{
"error": "sending message: connection timeout"
}
Use Cases
Progress Updates
{
"tool": "message",
"parameters": {
"content": "Step 1/3 complete: Data collected (2.5 GB)"
}
}
Task Completion
{
"tool": "message",
"parameters": {
"content": "✅ Analysis complete!\n\nResults:\n- Total items: 156\n- Errors: 3\n- Duration: 2m 30s"
}
}
Alerts & Notifications
{
"tool": "message",
"parameters": {
"content": "⚠️ Warning: Disk space low (5% remaining)"
}
}
Multi-user Notifications
Send to multiple recipients:
[
{
"tool": "message",
"parameters": {
"content": "Deployment starting...",
"chat_id": "user1"
}
},
{
"tool": "message",
"parameters": {
"content": "Deployment starting...",
"chat_id": "user2"
}
}
]
Best Practices
1. Use for Important Updates
Send messages for:
- Task completion
- Error conditions
- Progress milestones
- Time-sensitive alerts
// ✅ Good - Structured formatting
{
"content": "Analysis Complete\n\nResults:\n- Items: 42\n- Errors: 0\n- Time: 1m 30s"
}
// ❌ Avoid - Wall of text
{
"content": "Analysis complete found 42 items no errors took 1 minute 30 seconds"
}
3. Include Context
// ✅ Good
{
"content": "Database backup completed at 02:30 AM\nSize: 2.5 GB\nLocation: /backups/2024-03-15.sql.gz"
}
// ❌ Avoid
{
"content": "Backup done"
}
4. Use Emojis Sparingly
// ✅ Good
{
"content": "✅ Build successful\n⚠️ 3 warnings"
}
// ❌ Avoid
{
"content": "🎉🎊✨ Build successful! 🚀💯🔥"
}
5. Handle Failures Gracefully
Implement retry logic in the callback:
func sendWithRetry(channel, chatID, content string) error {
for i := 0; i < 3; i++ {
if err := sendToChannel(channel, chatID, content); err == nil {
return nil
}
time.Sleep(time.Second * time.Duration(i+1))
}
return errors.New("failed after 3 retries")
}
messageTool.SetSendCallback(sendWithRetry)
// Cron job sends message at scheduled time
job.Payload.Message = "Daily report ready"
job.Payload.Deliver = true
// Subagent reports completion via message
spawnTool.SetCallback(func(result string) {
messageTool.Execute(ctx, map[string]any{
"content": fmt.Sprintf("Subagent completed: %s", result),
})
})
The message tool is platform-agnostic. Supported channels depend on your callback implementation:
- Telegram
- WhatsApp
- Discord
- Slack
- IRC
- CLI (direct output)
- Custom platforms
Implement the SendCallback for your target platform.