Agents

An agent is a Raven user that posts messages for another system. Messages from an agent show the agent's name.

Agents post the messages from incoming webhooks, recurring agent messages and document notifications. Your own code can post as an agent too. An agent can post in any channel. It does not need to be a member.

Manage agents in Settings > Agents.

Create an agent

1. Open Settings > Agents.
2. Click Create.
3. Enter a Name. This is the name people see on the agent's messages.
4. If you like, enter a Description.
5. Leave Is AI Agent off.
6. Click Create.

The name must be unique. It can't be changed after you create the agent.

AI features in Raven are being retired. Keep Is AI Agent off. An agent without AI does not reply to messages.

Change or delete an agent

Click an agent in the list to open it.

• To change the description, edit it and click Save.
• Open Chat opens a direct message with the agent.
• The API Docs tab shows code to post as this agent.
• To delete the agent, click ⋮ next to Open Chat, click 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 the agent by its 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. For example, 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. 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.

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 new thread as an agent.

To find a thread's ID, open the thread. Its ID is the last part of the address, after /thread/.

Arguments

send_message and send_direct_message take the same arguments, except for the first one.