Send Message Tool - PraisonAI

Send Message lets a running agent reach the user proactively on their configured channels — without waiting for the next user turn. Need the answer back, not just delivery? See Ask Conversation.

from praisonaiagents import Agent
from praisonaiagents.tools import send_message

agent = Agent(
    name="Reporter",
    instructions="When you finish a long task, message the user on their channel.",
    tools=[send_message],
)
agent.start("Generate the weekly report and notify me when it's ready.")

The user starts a long job; the agent proactively messages them on Telegram, Slack, or email when it finishes.

Quick Start

Give Your Agent the Tool

from praisonaiagents import Agent
from praisonaiagents.tools import send_message

agent = Agent(
    name="Reporter",
    instructions="When you finish a long task, message the user on their channel.",
    tools=[send_message],
)

agent.start("Generate the weekly report and notify me when it's ready.")

The agent can now call send_message at any point mid-task to push a notification to the user.

List Available Targets

# The model calls:
#   send_message(action="list")
# and gets back JSON like:
#   [{"target": "telegram:home", "platform": "telegram", "kind": "home", "label": "Telegram"}]

Use action="list" first when you want the agent to pick the right channel rather than defaulting to "origin".

Send with a File Attachment

# Model call:
#   send_message("origin", "Weekly report ready MEDIA:/tmp/report.pdf")
# Returns: "Sent to telegram:<chat_id> (media not attached)."

Append MEDIA:<path> to the message text to attach a local file. Multiple attachments are supported.

Media attachments aren’t delivered yet. The text portion is sent, the MEDIA: paths are parsed and counted, and the result detail confirms how many files were skipped. File delivery will land in a future transport update — track PraisonAI#2374 for follow-ups.The MEDIA: caveat applies only to the send_message tool path (via BotOutboundMessenger). Proactive / scheduled / gateway-driven deliveries via DeliveryRouter.send_media do deliver attachments and honour threaded targets — see Outbound Media Delivery.

How It Works

Component	Purpose
send_message tool	Agent-callable function; resolves messenger from context
OutboundMessengerProtocol	Interface the gateway registers per-turn
SessionContext	Task-local registry — no globals, safe for concurrent handlers
Gateway	Delivers to Telegram, Slack, Discord, WhatsApp, etc.

Targets

Choose the right target form for your situation:

Target form	Example	Description
`"origin"`	`"origin"`	The chat this conversation came from (default)
`"<platform>"`	`"telegram"`	That platform’s configured home channel
`"<platform>:<chat_id>"`	`"slack:#ops"`	A specific chat or channel
`"<platform>:<chat_id>:<thread_id>"`	`"slack:#ops:T123"`	A specific thread within a chat
`"<alias>"`	`"my-ops-alert"`	A named alias configured in the gateway

Attachments (MEDIA:)

Append MEDIA:<path> to the message string to attach a local file to the delivery.

# Single attachment
send_message("origin", "Report ready MEDIA:/tmp/report.pdf")

# Multiple attachments — each MEDIA: token is stripped and the paths collected
send_message("origin", "Charts attached MEDIA:/tmp/chart1.png MEDIA:/tmp/chart2.png")

File paths must not contain whitespace. The MEDIA: directive is stripped from the displayed message text before delivery.

Reactions

Agents can tap a lightweight ✅ / 👍 / ⏳ reaction on a message instead of sending a full reply — perfect for busy group chats where every reply is noise.

from praisonaiagents.tools import send_message

# React to the message being handled right now
send_message(action="react", target="origin", message="👍")

# Remove a reaction you added earlier
send_message(action="unreact", target="origin", message="👍")

The emoji rides in the message argument and is .strip()-ed — an empty emoji returns {"status": "failed", "detail": "no emoji provided"}.

target="origin" reacts to the inbound message the agent is currently handling — its message_id is carried on the session automatically, so no extra parameter is needed. To react to a different message, use the explicit "<platform>:<chat_id>:<message_id>" form.

Reaction outcomes

Reactions return a JSON string of a ReactionResult with a typed status (plus optional target and detail):

`status`	Meaning
`"ok"`	Reaction added/removed successfully
`"unsupported"`	The channel doesn’t support reactions (e.g. WhatsApp) — degrade gracefully
`"failed"`	Blocked by send-policy, empty emoji, or downstream error
`"no_route"`	Target could not be resolved to a reachable channel

{"status": "ok", "target": "telegram:12345"}
{"status": "unsupported", "detail": "the active gateway does not support reactions"}
{"status": "failed", "detail": "no emoji provided"}

Channels that support reactions today: Telegram, Slack, Discord. Others (WhatsApp, Signal, email, agentmail, Linear) return "unsupported" — the tool never raises. The same Send Policy that guards action="send" also guards react/unreact — a steered or prompt-injected agent cannot react on a channel the operator never intended.

Listing Targets

action="list" returns a JSON array of all reachable targets so the agent can pick the right one before sending.

# Model call:
#   send_message(action="list")

# Returns JSON:
# [
#   {"target": "origin", "platform": "telegram", "kind": "origin", "label": "Current chat"},
#   {"target": "telegram", "platform": "telegram", "kind": "home", "label": "Telegram"},
#   {"target": "slack:#ops", "platform": "slack", "kind": "alias", "label": "#ops"}
# ]

Each entry in the array:

Field	Type	Description
`target`	`str`	Token to pass as the `target` argument to `send_message`
`platform`	`str`	Platform name (e.g. `"telegram"`, `"slack"`)
`kind`	`str`	One of `"origin"`, `"home"`, `"alias"`, or `"observed"`
`label`	`str`	Friendly name for display

"observed" means a channel the gateway has seen activity on but is not a configured home or alias.

When It’s Available

Runtime	Behaviour
Bot / Gateway (Telegram, Slack, Discord, WhatsApp, …)	Delivers the message; returns a short summary string
CLI / one-shot (`agent.start(...)` directly)	Returns the string below — does not raise

When no gateway is active the tool returns:

No active gateway: send_message is only available inside a running bot/gateway (e.g. Telegram, Slack, Discord). It is unavailable for CLI/one-shot runs.

Agent instructions can check for this string and fall back gracefully.

User Interaction Flow

A user starts a long research task on Telegram, then closes their phone. The agent finishes compiling the report, calls send_message("origin", "Your report is ready MEDIA:/tmp/report.pdf"), and the user receives a Telegram push notification with the text — without ever having to ask “are you done yet?”. A user pings the agent in a 500-person Slack channel. Instead of replying and cluttering the thread, the agent taps a ⏳ reaction to acknowledge, works on the task, then swaps to ✅ when done — no message noise, but the user still sees progress.

Configuration Reference

send_message takes three arguments. All are optional:

Argument	Type	Default	Description
`target`	`str`	`"origin"`	Symbolic destination (see Targets table)
`message`	`str`	`""`	Text to send; append `" MEDIA:<path>"` to attach files. Attachments are parsed today but not yet delivered through bot transports — the result detail reports how many were skipped.
`action`	`str`	`"send"`	`"send"` to deliver, `"list"` to enumerate reachable targets, `"react"` to add an emoji reaction, `"unreact"` to remove one

When action is "react" or "unreact", pass the emoji as the message argument. action values at a glance:

`action`	`message` carries	Returns
`"send"`	text (`" MEDIA:<path>"` optional)	Short summary string, e.g. `"Delivered to slack:#ops"`
`"list"`	ignored	JSON array of `{target, platform, kind, label}` objects
`"react"`	the emoji, e.g. `"👍"`	JSON string of a `ReactionResult`, e.g. `{"status": "ok"}`
`"unreact"`	the emoji to remove	JSON string of a `ReactionResult`, e.g. `{"status": "ok"}`

Common Patterns

Notify on long-task completion

agent = Agent(
    name="Analyst",
    instructions="""
    Run deep analysis tasks. When a task finishes, always call
    send_message("origin", "<summary>") to let the user know.
    """,
    tools=[send_message],
)

Cross-channel handoff

# Model calls send_message(action="list") first, picks slack:#ops, then:
#   send_message("slack:#ops", "Deploy finished ✅")

Pick the target from the list, then send

# 1. List targets
#    send_message(action="list")
#    → [{"target": "slack:#ops", ...}, {"target": "telegram", ...}]
# 2. Choose and send
#    send_message("slack:#ops", "All tests passed")

Acknowledge with a reaction in a busy channel

agent = Agent(
    name="Support",
    instructions="""
    In busy group chats, tap send_message(action="react", target="origin",
    message="⏳") to acknowledge a request, then react with "✅" once the
    task is done instead of posting a full reply.
    """,
    tools=[send_message],
)

Best Practices

Confirm channel before sending to an explicit target

Call send_message(action="list") first when the user hasn’t specified where they want to be notified. Sending to a channel the user doesn’t monitor is noise.

Default to 'origin'

"origin" sends to the chat the conversation started in — usually the right choice. Only override it when you have a specific reason (e.g., sending an ops alert to a dedicated Slack channel).

Handle the no-gateway fallback in agent instructions

Include a note like “If send_message returns a ‘No active gateway’ message, skip the notification and continue.” so the agent doesn’t retry endlessly on CLI runs.

Keep messages short — they hit a phone

Mobile push notifications truncate long text. Send a one-line summary; attach details as a file with MEDIA:.

Ask Conversation

Request/reply sibling — message a target and wait for its answer

Send Policy

Restrict which channels send_message is allowed to deliver to

Clarify Tool

Ask the user mid-task for clarifying input

Channels Gateway

Connect agents to Telegram, Slack, Discord, and WhatsApp

Bot Gateway

Run the gateway server

Bot Routing

Route messages by channel and platform

​Quick Start

​How It Works

​Targets

​Attachments (MEDIA:)

​Reactions

​Reaction outcomes

​Listing Targets

​When It’s Available

​User Interaction Flow

​Configuration Reference

​Common Patterns

​Notify on long-task completion

​Cross-channel handoff

​Pick the target from the list, then send

​Acknowledge with a reaction in a busy channel

​Best Practices

​Related

Ask Conversation

Send Policy

Clarify Tool

Channels Gateway

Bot Gateway

Bot Routing

Quick Start

How It Works

Targets

Attachments (MEDIA:)

Reactions

Reaction outcomes

Listing Targets

When It’s Available

User Interaction Flow

Configuration Reference

Common Patterns

Notify on long-task completion

Cross-channel handoff

Pick the target from the list, then send

Acknowledge with a reaction in a busy channel

Best Practices

Related