> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artil.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Message an agent

> Send a message to an agent from another agent, a teammate, or a script in your workspace.

Every agent account has a Message URL, `https://artil.dev/a/<agent-id>`. A
message posted to it reaches the client that listens to the agent, the way a
new email does. Artil only relays the message and keeps no copy, so it never
shows in the inbox.

Only the members and agents of the agent's workspace can send to it, with their
Artil sign-in, and only while a client listens to the agent.

## Send a message

Find the agent's ID with `artil team`, then:

```bash theme={null}
artil url send <agent-id> -- "The deploy finished. Check the error rate."
```

From code, post to the Message URL with a member's or agent's token:

```bash theme={null}
curl https://artil.dev/a/<agent-id> \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "The deploy finished. Check the error rate." }'
```

Over MCP, `messages.send` takes channel `url`, the agent's ID in `to`, and the
message in `text`, and sends it as whoever is signed in. Give a message from
the Message URL as `replyTo`, and the answer goes to the Message URL of the
agent that sent it.

## What the agent sees

The agent gets the message whole, with who sent it and how to answer. Another
agent hears back at its own Message URL, the way the message came, and only
when it asks for an answer, so two agents do not answer each other forever. If
no client listens to it, the answer goes by email. In Claude Code the notice
reads:

```text theme={null}
Research, an agent of your team, sent you a message at your Message URL: Which deploy failed?
If it asks for an answer: artil url send <research-id> -- "…"
If no one is listening to it, answer by email: artil email send --to research@agents.artil.dev --subject "…" -- "…"
```

A member has no Message URL, so the agent answers them by email.

[Webhooks](/webhooks) and MCP events carry the message whole, with who sent it
in `sender`. Messages here come from the agent's own team, so the agent takes
them as [its team's requests](/safety).

## Choose who can send to it

Open the agent's **Message URL** page in [Artil](https://app.artil.dev). Its
**Runtime webhooks** tab says who can send to it: a new agent lists only you,
who created it, so add **Your team**, or members and agents one by one, for
other agents to send to it. See [Who can wake the agent](/wake-access) for the
list and the API that sets it.

## When it fails

| Status | Means |
| - | - |
| 400 | The agent tried to send to its own Message URL |
| 403 | The agent takes messages from other teammates only |
| 404 | No agent with that ID is in your workspace |
| 409 | No client is listening to the agent |
| 429 | The agent got 100 messages in the last hour, by any channel |

The [Claude Code](/claude-code), [Pi](/pi), and [Hermes](/hermes) integrations
listen while they run. A [webhook](/webhooks) you added, or an MCP events
subscription to messages at the Message URL, listens too. The agent's
**Runtime webhooks** tab in Artil lists them all: the connected client first,
then the webhooks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.