Raven

Raven

Message actions

A message action turns a message into something in a Frappe app, such as a new document with the message text already filled in. An admin sets up the actions; anyone can then use them on any message.

The Actions submenu on a message

Use an action on a message

  1. Open the message's More actions menu and point to Actions.
  2. Click the action.
  3. Check the values in the dialog. Some are filled in from the message.
  4. Click Submit.

The dialog of a message action

If the action created a document, View in the confirmation opens it, and the message gets the document card unless it already had one.

Actions is on the menu only when your site has at least one enabled action.

An action runs with the permissions of the person who uses it. If they can't create the document, Raven shows the error and the dialog stays open, so they can fix a value and try again.

Set up an action

Only Raven Admins and System Managers can create and change message actions. Ask one to do it.

  1. Open Settings > Message Actions and click Create.
  2. Fill in the General tab.
  3. On the Fields tab, add the fields the dialog should show.
  4. Click Create.

General

The General tab of a message action

Field What it does
Name The name of the action on the Actions menu.
Action Type Create Document, Custom Function (API) or Server Script. Each type is explained below.
Title The title of the dialog. It starts as the name.
Description Shown under the title of the dialog.
Success Message Shown when the action is done. If empty, Raven shows Action completed.

Fields

Each row is a field in the dialog. The field's name is the key its value is sent under.

The Fields tab of a message action

Click Add Field to add one field. For Create Document, Import fields from adds all the mandatory fields of a document type at once.

The dialog for one field

Field What it does
Field For Create Document: the field of the new document to fill. Picking it fills in the label and type.
Field Name For the other two types: the name the value is sent under.
Label The label in the dialog.
Type The kind of input: Data, Number, Select, Link, Checkbox, Date, Time, Datetime or Small Text.
Validation For Data: checks that the value is an email, a phone number or a URL.
Required The dialog can't be submitted without it.
Options For Select: the choices, one on each line.
Document Type For Link: the type of document to pick from.
Default Value Type Where the starting value comes from. See the table below.
Default Value The starting value.
Description Help text under the field.
Default Value Type Default Value
Static A fixed value.
Message Field A value from the message. See the table below.
Jinja A template that uses the message, such as {{ message.content }}. message has every field of the message, and message.message_url.
Message Field The value
Text (with HTML) The message text, with its formatting.
Content (plain text) The message text, without formatting.
File The link to the file in the message.
Owner The user who sent the message.
Creation When the message was sent.
Message Type Text, Image, File or Poll.
Linked DocType The type of the document attached to the message.
Linked Document The ID of the document attached to the message.
Channel ID The ID of the channel.
Workspace ID The workspace of the channel.
Message URL A link that opens the message in Raven.

Number fields are sent as numbers. Checkbox fields are sent as 1 or 0. Datetime fields are sent as text, such as 2026-10-19 14:30:00.

Create Document

Raven creates a document of the type in Document Type, filled in with the values from the dialog.

  • Each field in the Fields tab fills the document field of the same name. Values with no matching field on the action are dropped.
  • The document must pass its own checks. Every mandatory field needs a value, so use Import fields from to add them.

Custom Function (API)

Raven calls a Python function in an app on your site. Use this when the action needs more than one document, or logic of its own.

A Custom Function action in Settings

In Custom Function Path, enter the dotted path to the function, with no spaces. For a function create_task in the file my_app/raven_actions.py, the path is my_app.raven_actions.create_task.

Raven calls the function with one keyword argument per field of the action, named after the field. Nothing else is passed, not even the message. To use a value from the message, add a field with Message Field as its Default Value Type.

A field that is left empty can arrive as an empty string, or not arrive at all. Give every optional argument a default.

The function runs as the person who used the action. If it raises an error, Raven shows the error and the dialog stays open. If it returns a dictionary with a link, the success message has a View button that opens that link.

This example has three fields on the action:

Field Name Type Default Value Type Default Value
description Small Text Message Field Content (plain text)
assigned_to Link, to User Static (empty)
message_url Data Message Field Message URL
# my_app/raven_actions.py
import frappe


def create_task(description, assigned_to=None, message_url=None):
	"""Called by a Raven message action. Each argument is a field of the action."""
	if not description:
		frappe.throw("Add a description first.")

	# ToDo is a document type that every Frappe site has.
	todo = frappe.get_doc(
		{
			"doctype": "ToDo",
			"description": f"{description}<br><br>From Raven: {message_url or ''}",
			"allocated_to": assigned_to or frappe.session.user,
		}
	).insert()

	# Raven shows a View button that opens this link.
	return {"link": todo.get_url()}

Server Script

Raven runs a Server Script with the values from the dialog. Use this to add logic without writing an app.

A Server Script action in Settings

Server scripts must be turned on for the bench. A system administrator runs this command on the server. It can take up to a minute to take effect:

bench set-config -g server_script_enabled 1

Write the script

  1. Under the Server Script field, click View Server Scripts.
  2. Create a Server Script with Script Type set to API.
  3. Save it, and make sure it is not disabled.
  4. Back in Message Actions, pick it in the Server Script field.

You need the Script Manager role to see and write server scripts.

What the script gets

The script reads its input from frappe.form_dict:

Key What it holds
message_id The ID of the message the action was used on.
action_id The ID of the message action.
values The values from the dialog, as a dictionary keyed by field name.

Read the values with frappe.form_dict.get("values"), then each value with .get("field_name"). frappe.form_dict.values does not work, because values is also a method of a Python dictionary.

frappe.session.user is the person who used the action. The script runs with their permissions.

Raven does not use anything the script returns. It shows the Success Message when the script ends without an error. Call frappe.throw("...") to stop and show an error instead.

Example: create a document and reply in the channel

This script creates a to-do from the message, then posts a reply in the channel as an agent. Add one field to the action: details, type Small Text, with Message Field and Content (plain text) as its default.

# Script Type: API
message_id = frappe.form_dict.get("message_id")
values = frappe.form_dict.get("values") or {}

message = frappe.get_doc("Raven Message", message_id)

# ToDo is a document type that every Frappe site has.
todo = frappe.get_doc({
    "doctype": "ToDo",
    "description": values.get("details") or message.content,
}).insert()

# Agents are stored as Raven Bot records. Use the name of one of your agents.
agent = frappe.get_doc("Raven Bot", "Requests")
agent.send_message(
    channel_id=message.channel_id,
    text="Logged as " + todo.name + " by " + frappe.session.user + ".",
)

See Agents to create an agent.

A full example

This action creates a document from a message with the message text filled in. It uses Create Document, so no code is needed.

  1. Open Settings > Message Actions and click Create.
  2. In Name, enter a name, such as Create a task.
  3. In Action Type, leave Create Document.
  4. In Document Type, pick the type of document to create.
  5. In Description, enter Create a task from this message.
  6. In Success Message, enter Task created.
  7. On the Fields tab, click Import fields from and the document type.
  8. Click the pencil on the field that should hold the message text.
  9. In Default Value Type, pick Message Field. In Default Value, pick Content (plain text).
  10. Click Save, then click Create.

Create a task is now under Actions in every message's More actions menu, and its dialog opens with the message text filled in.

Change, disable or delete an action

Click an action in the list, make your changes and click Save. To hide it without deleting it, click ⋮ at the top right and then Disable; Enable turns it back on. Delete in the same menu removes it for good.

On the mobile app

Touch and hold a message, tap Actions, then tap the action.

The actions for a message on the mobile app

Last updated 2 weeks ago
Was this helpful?
Thanks!