Custom Entities

A Custom Entity is a per-tenant data type attached to contacts — the platform’s equivalent of “custom objects” in Salesforce, HubSpot, or Zendesk. Each contact can have many records of a given entity (a customer might have three policies, twelve tickets, two cars). Records render in the agent right rail as a table or list view, and bot recipes can read them via the Lookup Entity node.

Use Custom Entities when contacts have repeating, structured data that shouldn’t sit on the contact record itself.

The source-mode rule

Every field on every Custom Entity is declared at create time as one of two sources:

integration — populated only by Smart Plug response mappings. Agents see the value, but it’s read-only in the UI.
manual — populated only by agent input in the contact panel. Smart Plugs never overwrite a manual field.

The two are mutually exclusive. A field is one or the other, never both. The data is stored in two physically separate columns under the hood, so manual edits and integration refreshes cannot collide with each other no matter what order they arrive in.

This eliminates the entire class of “did the agent’s edit win, or the plug refresh?” conflicts that plague generic custom-object systems. The trade-off: you commit to the source at field-create time. Switching a field from integration to manual (or vice versa) requires creating a new field and migrating the data.

Custom Entity field row showing the Integration / Manual source radio with mutually exclusive selection

Creating an entity

Settings → Custom Entities → + New Entity.
The form has two tabs: Identity and Fields.

Identity

Name (English) — what agents read in the right rail (e.g. Helpdesk Ticket).
Name (Arabic) — optional Arabic label.
Key — machine name in lowercase + underscores (e.g. helpdesk_ticket). Immutable after create. Used by the Lookup Entity node and Smart Plug bindings.
Icon — optional design-system icon name.
Display mode — Table (compact rows in a grid) or List (one row per record with more detail).
Visible in agent right panel — uncheck to keep the entity around without showing it (useful for fields a recipe needs but an agent shouldn’t see).
Record label template — the row label in the inbox panel. Supports {{field_key}} interpolation (e.g. Ticket #{{external_id}}: {{subject}}).
Sort field and Sort direction — how records are ordered in the panel.

Fields

Add at least one field before saving. Each field:

Key — short identifier (e.g. plan_name). Used by response mappings and the Lookup Entity node.
Name (EN) / Name (AR) — labels shown to agents.
Data type — Text (short/long), Number, Currency, Percent, Date, Date + time, Status badge, Boolean, URL, Reference. The chosen type drives the renderer in the agent panel and the editor in the manual-input drawer.
Source — Integration or Manual (the rule above).
Required — only meaningful for manual fields; integration fields aren’t validated against required.
Show in panel — controls visibility in the table/list view.
Show in detail drawer — controls visibility when the agent opens a record for full edit.

Some data types have additional config:

Status badge — define the enum values with bilingual labels and a colour token each.
Currency — pick the ISO currency code (e.g. AED).
URL — optional URL template for rendering as a clickable link.

Where entities are used

Agent Console right rail — every panel-visible entity renders as its own card. Records populate from Smart Plug auto-fires + the Refresh button.
Manual edit drawer — agents click a record to open it. Manual fields are editable; integration fields are read-only.
Lookup Entity node in the recipe canvas — bot recipes branch on entity records (e.g. “if any policy has plan_tier = platinum → route to VIP team”). Read-only; recipes can’t write entity records.

Agent Console right rail showing a Helpdesk Tickets entity panel with one record below a Smart Plug card

Best practices

Pick the source carefully at create time. Migrating later is a pain.
Use Status badge with explicit enum colours. Free-form text status fields look noisy in the panel.
Keep the record label template short. Agents glance at the panel; long labels truncate.
Match the manual / integration split to operational reality. Notes the agent writes are manual; everything from the source system is integration. The split should mirror who owns the data.
Set Show in panel off and Show in detail drawer on for fields agents need to see occasionally but shouldn’t clutter the main view (e.g. created_at).

Deleting an entity

Deleting an entity removes it from the agent right rail and the Lookup Entity node’s picker. Existing records are soft-deleted along with the entity definition — they remain in the database for audit but are no longer reachable.