Smart Plugs

A Smart Plug is an admin-configured HTTP-call card that renders in the agent right rail. Each plug binds to one connector, holds one credential, and exposes one or more action buttons. Plugs are how agents reach external systems — pull eligibility, create a ticket, push a contact update — without leaving the inbox.

Plugs can also populate Custom Entities automatically when the conversation opens, so agents see the contact’s tickets, policies, or orders without clicking anything.

Creating a plug

1. Settings → Smart Plugs → + New Smart Plug.
2. The form opens with four tabs: Connection, Inputs, Buttons, Entity Bindings. Work through them in order — the right panel won’t save until every required field is filled and at least one button is defined.

Connection

This tab covers the plug’s identity, the integration it speaks to, and who can see it.

• Name — what agents will read in their right rail (e.g. Member Eligibility).
• Trigger mode — pick one:
  • Auto on conversation open — the plug’s bound button fires automatically when an agent opens a conversation. Use for read-only lookups.
  • Manual click only — the agent must click a button to fire. Use for actions with side effects.
• Connector — pick from System and Tenant connectors. Immutable after create.
• Credential secret — the static credential used per the connector’s auth scheme. Stored encrypted; never returned to the UI. On edit, leave blank to keep the current secret, or type a new value to rotate.
• Description — admin-only notes shown on the list page.
• Visibility roles — tick the roles that should see this plug in the agent panel (agent, supervisor, admin).
• Enabled — uncheck to disable the plug without deleting it.

Inputs

Plug-level inputs are rendered above the buttons in the agent panel. They cover values that every button needs — for example, a member_id field used by all of “Lookup”, “Update”, and “Cancel”. Each button can also declare its own additional inputs in the Buttons tab.

The v1 editor takes a JSON array. Each input has a key, bilingual label, type, required flag, optional default, and optional prefill source.

Buttons

Each button is one HTTP action on the plug. Add at least one button to save.

For every button:

• Key — short stable identifier (e.g. create_ticket). Unique within the plug.
• Label (EN) / Label (AR) — what the agent reads on the button.
• Colour — visual variant. Azure for default, green for confirm-positive, gold for caution, red for destructive, plus teal and purple.
• Timeout (ms) — 1,000 to 120,000. The button fails closed if the call exceeds this.
• Confirm before fire? — when ticked, the agent sees an “Are you sure?” modal before the request leaves CraftBot.
• Connector action — pick one action exposed by the bound connector, OR leave blank and define a Custom request override below.
• Custom request override — method + path + body template. Use this for Generic REST plugs or to override a connector action.
• Response mapping — a JSON array that maps the HTTP response into display fields (shown to the agent in the plug card) and Custom Entity records.

Entity Bindings

Each binding links a button to a Custom Entity. When the button fires (either from auto-on-open or from a manual click), the response mapping writes records into the entity, and the agent’s right-rail panel for that entity refreshes automatically. The same wiring powers the Refresh button on each entity panel.

Bindings only make sense once you’ve defined at least one Custom Entity — if the list is empty, head over to Custom Entities first.

Previewing response mapping

Each plug row in the list has a Preview button. The preview tool:

1. Asks you to pick a button.
2. Asks you to paste a sample HTTP response (as JSON).
3. Runs the response mapping against the sample and shows exactly which display fields and entity records the plug would produce.

Use this when authoring or debugging a response mapping — it removes the network round-trip so you can iterate fast.

Where plugs are used

• Agent Console right rail — every plug visible to the user’s role renders as a card. Auto-trigger plugs fire on open; manual ones wait for a click.
• Custom Entity panels — bindings drive the auto-refresh and Refresh-button behaviour on each entity table.

Best practices

• One plug per logical concept. “Ticket Manager” with Create / Escalate / Resolve buttons beats three separate plugs.
• Use Auto on open sparingly. Every auto-fire is a network round-trip on every conversation open. Reserve it for short, fast, read-only lookups (eligibility check, contact enrichment).
• Tick Confirm before fire on every destructive button. An accidental “Cancel policy” click should never bypass a confirmation.
• Test the response mapping in the preview tool with at least three sample responses: a happy-path, a missing-field, and an error shape. Live API responses are messier than the docs suggest.
• Keep secrets in the vault, not in connector helpers. Helpers are visible to every admin; the credential field is encrypted.

Deleting a plug

Deleting a plug removes it from the agent right rail immediately. Entity bindings on the plug are removed too — Custom Entity records previously populated by the plug are preserved (no retroactive deletion), but future refreshes won’t update them.