Agents
An agent is a user that other systems post as, under its own name, in any channel without being a member.

Agents post the messages from incoming webhooks, recurring agent messages and document notifications. Your own code can post as an agent too.
Only Raven Admins and System Managers can create, change or delete agents, in Settings > Agents. Ask one to do it.
Create an agent
- Open Settings > Agents and click Create.
- Enter a Name. People see it on the agent's messages.
- Leave Is AI Agent off.
- Click Create.

A Description is optional. The name must be unique and can't be changed later. AI features in Raven are being retired, so keep Is AI Agent off. An agent without AI does not reply to messages.
Change or delete an agent
Open the agent from the list. Edit the description and click Save. Open Chat starts a direct message with the agent, and the API Docs tab shows code to post as it. To delete the agent, click ⋮ next to Open Chat, then Delete, and confirm.
Post as an agent from code
A server script or a custom Frappe app can post as an agent. In code, an agent is a record of the DocType Raven Bot. Load it by name, then call one of its methods. Each method returns the ID of the new message.
Post in a channel
agent = frappe.get_doc("Raven Bot", "Releases")
agent.send_message(
channel_id="lumen-cycles-engineering",
text="**Version 2.4** is live.",
markdown=True,
)
The channel ID is the last part of the channel's address in your browser. In /raven/Lumen%20Cycles/lumen-cycles-engineering it is lumen-cycles-engineering.
Send a direct message
agent.send_direct_message(
user_id="maya@lumencycles.com",
text="Your export is ready.",
)
user_id is the person's email address, their user ID on the site. Raven opens a direct message between the agent and the person if there isn't one yet. Nothing is sent if the person is disabled. If the person is not on Raven, Raven raises an error.
Attach a document
Any document from any Frappe app on your site can be attached, and the message shows a preview of it. In a document event server script, doc is the document that changed:
agent.send_message(
channel_id="lumen-cycles-finance",
text="This needs a review.",
link_doctype=doc.doctype,
link_document=doc.name,
)
Reply in a thread
Pass the thread's ID as channel_id. The thread ID is the ID of the message the thread was started on, and the last part of the thread's address after /thread/.
agent.send_message(
channel_id="q8x2k4m1pz",
text="The build for this branch passed.",
)
The thread must already exist. There is no method to start a thread as an agent.
Arguments
send_message and send_direct_message take the same arguments, except for the first one.
| Argument | What it does |
|---|---|
channel_id |
The channel or thread to post in. send_message only. |
user_id |
The person to send a direct message to. send_direct_message only. |
text |
The message. It is HTML unless markdown=True. |
markdown |
Set to True to write text in Markdown. |
link_doctype |
The DocType of the document to attach. |
link_document |
The name of the document to attach. |
file |
The URL of a file on your site to send, such as "/files/report.pdf". JPG, PNG, GIF and WEBP files show as images. |