Incoming Actions

The Incoming Actions section (/incoming-actions) is a rule builder that turns incoming messages (email, Telegram) into records of Orbita entities: tickets, requests, and any other record types created in the entity designer.

Each rule (an "action") describes: which channel it applies to, which entity the record is created in, how its fields are filled in, and whether the action should run automatically or only when the operator clicks a button.

List of actions

The screen shows all configured actions as cards:

Card element	Description
Name	The rule's name, set by the administrator
Auto	A badge shown if the action runs automatically (without operator involvement)
Channel	all (all channels), email, or telegram
Mapping → entity	The name of the target entity the record will be created in
Button label	The text of the button the operator will see in the incoming messages list (for actions triggered manually)

Edit and Delete buttons are available for each action. The + New Action button opens the creation form.

Creating and editing an action

1. Click + New Action
2. Fill in the Name field — for the administrator's own convenience
3. Choose the Channel: all channels, Email only, or Telegram only
4. Decide whether the action should run automatically (the "Run automatically" toggle) — if enabled, the action fires as soon as a message arrives, with no button and no operator involvement
5. For actions triggered manually, also specify:
   • The target entity — where the record will be created (chosen from the list of all entities created in the designer)
   • The button label and its color — how the action button will look in the incoming messages list
6. Configure the field mapping (the Field Mapping tab) and/or a processing script (the Script tab) — see below
7. Click Save

Field Mapping

This tab is available for actions that create a record in a specific entity (not for purely automatic background actions).

On the left are the fields of the selected target entity; on the right is the data path within the incoming message to pull the value from:

Source	Example
Base message fields	channel, sender_id, from_name, subject, body, message_id, attachments
Fields inside the channel's raw payload (JSON)	payload.message.from.username, payload.message.chat.id, etc.

To avoid guessing paths by hand, you can click "Load Fields" after choosing a channel (Email or Telegram) — the system will populate the actual structure of the last received message on that channel as a list of available paths.

A field can be left empty — in that case its value is either left unset or computed by the script (see below).

Script

The Script tab lets you write a PHP script that runs after the base field mapping and can:

• override or supplement the values collected by the mapping (the $data array)
• read any data from the incoming message via $incoming (channel, sender_id, the full payload)
• look up and read existing records ($api->get(...), $api->find(...)) — for example, to identify the author by email or Telegram chat_id
• work with relations between records (getRelatedByTable, addRelatedByTable)
• reply to the user directly in Telegram ($api->replyTelegram(...)) or send a push notification to the web interface ($api->sendPushNotification(...))

Built-in reference documentation for the available variables and helpers opens right in the action editor (the Context / Records / Relations / Notify / Helpers tabs).

The script is the main mechanism that lets you, for example, find an existing record by sender and update it instead of creating a new one for every incoming message: the rule itself decides which logic to apply, based on $incoming and lookups via $api.

Automatic actions and bots

If "Run automatically" is enabled, the action has neither a button nor a target entity — this is typically a bot script: for instance, it replies in Telegram immediately or performs background processing, and then marks the message as processed itself.

How an action is applied to a message

1. The operator opens Incoming Messages and clicks the desired action button next to a message (or the action fires automatically on message arrival, if marked automatic)
2. The server collects data: first using the Field Mapping rules, then (if defined) using the script
3. The message is marked as Processed
4. For manually triggered actions, the record creation form for the target entity opens with fields pre-filled — ready to review and save

See also

• Incoming Messages — the list of received messages and how to work with them
• Settings — connecting the email inbox (IMAP) and the Telegram bot that messages arrive through