Send Message Tool

Let agents manage the live conversation — send, react, open a thread, or edit / retract their own messages — through Telegram, Slack, Discord, and other gateways

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

1. 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.

2. 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".

3. 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.

How It Works

The verbs react, thread, edit, and delete add a capability-gate step: the router checks the adapter’s supports_* flag before dispatch and returns a typed unsupported when the channel lacks the primitive — it never raises.

Targets

Choose the right target form for your situation:

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")

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"}.

Reaction outcomes

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

{"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.

Threads

Open a topic or thread under a target so a long-running effort has its own space.

from praisonaiagents.tools import send_message

# Open a topic titled "Rollout 2026-09" under the current Slack channel
send_message("slack:#ops", "Rollout 2026-09", action="thread")

The thread title rides in the message argument. An empty title returns {"status": "failed", "detail": "no thread title provided"}.

Thread outcomes

Threads return a JSON ThreadResult with a typed status (plus thread_id on success):

{"status": "ok", "target": "slack:#ops", "thread_id": "T789"}
{"status": "unsupported", "detail": "the active gateway does not support threads"}
{"status": "failed", "detail": "no thread title provided"}

Thread-aware routing across platforms is covered in Gateway Threads.

Edit and Delete (own messages)

Update a status in place, or retract a message the agent shouldn’t have sent — instead of spamming follow-ups.

from praisonaiagents.tools import send_message

# Post a live status, then update it in place instead of spamming follow-ups
send_message("origin", "Working…", action="send")
# ... later:
send_message("origin", "Done ✅", action="edit", message_id="98")

# Retract a message the agent shouldn't have sent
send_message("origin", "", action="delete", message_id="77")

• Authority: edit and delete are the most-restricted class — own-prior-message. They only work on messages this agent/session sent.
• Capability gate: powered by the adapter’s supports_edit / supports_delete. Channels that can’t edit/delete return a typed unsupported outcome — the tool never raises.
• Send-policy still guards edit/delete — a steered agent cannot mutate messages on channels the operator hasn’t allowed.
• Required message_id: a missing id returns {"status": "failed", "detail": "no message_id provided"}.
• Result shape: a JSON MessageActionResult with status (ok / unsupported / failed / no_route), optional target, and optional detail.

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

Channel support today

Per-channel capability flags live in Bot Platform Capabilities.

Action Vocabulary and Authority

Every verb the tool accepts declares one of three authority classes — a closed set that keeps a steered agent from inventing new mutation verbs.

Any verb missing from the map is rejected — the agent cannot “invent” a new mutation verb that silently inherits send‘s guard:

Unknown action '<verb>'. Use 'send', 'list', 'react', 'unreact', 'thread', 'edit', or 'delete'.

The same Send Policy guards every write verb. Per-channel primitives are listed in Bot Platform Capabilities.

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:

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

When It’s Available

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.

An agent posts “Working…” on Telegram, keeps working, then edits that same message to “Done ✅” — the user sees a single evolving status line on their phone, not a stream of noisy follow-ups.

The agent notices it posted a message with the wrong figure and calls send_message("origin", "", action="delete", message_id="…") to unsend it before the user reads it.

Configuration Reference

send_message takes four arguments. All are optional:

action values at a glance:

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],
)

Post-then-edit a live status line

agent = Agent(
    name="Deployer",
    instructions="""
    When a deploy starts, post 'Deploying…' with send_message("origin", "Deploying…").
    Remember the returned message id, and when done, edit it to 'Deployed ✅' with
    send_message("origin", "Deployed ✅", action="edit", message_id="<id>").
    """,
    tools=[send_message],
)

Open a thread for a long-running rollout

send_message("slack:#ops", "Q4 rollout — sub-thread", action="thread")

Best Practices

Related