Building an app

Back to the guide

An app is your own software, extending Deeluge the way a plug-in would: it reads and writes the CRM, hears about changes as they happen, and adds buttons to record pages. You describe it in a manifest; an owner or admin registers and installs it under Settings → Apps.

The manifest

{
  "manifest_version": 1,
  "key": "deal-enricher",
  "name": "Deal Enricher",
  "description": "Adds revenue estimates to new companies.",
  "developer": { "name": "Acme Labs", "url": "https://acme.dev", "email": "apps@acme.dev" },
  "scopes": ["objects:read", "records:read", "records:write"],
  "webhooks": [
    { "url": "https://acme.dev/deeluge/webhooks", "events": ["record.created"], "objects": ["accounts"] }
  ],
  "record_actions": [
    { "key": "enrich", "label": "Enrich with Acme", "objects": ["accounts"],
      "url": "https://acme.dev/deeluge/actions/enrich", "confirm": "Look this company up?" }
  ]
}

Key
`key`	Lowercase letters, digits and dashes. Cannot change once registered.
`scopes`	The API permissions the app gets. Each can be narrowed to objects: `{ "scope": "records:read", "objects": ["accounts"] }`.
`webhooks`	Events to send the app. Each needs the matching read scope.
`record_actions`	Items added to a record's … menu. Need `records:read`.

Every problem in a manifest is reported at once when you save it.

Installing

Installing gives the app:

An API key with exactly the manifest's scopes, shown once. The app calls /api/v1 with it. Like every key, it sees nothing restricted until someone grants it access, and it is never told about changes it made itself.
Its webhooks, signed with the app's signing secret (under Secret on the app). See Webhooks for the format and how to verify.
Its record actions, on the records of the objects it names.

Changing the manifest of an installed app takes effect straight away. Uninstalling revokes the key and deletes the webhooks in one step.

Record actions

When someone chooses the action, the app receives a signed POST, with the same headers as a webhook:

{
  "id": "act_…",
  "type": "record_action.invoked",
  "version": 1,
  "created_at": "…",
  "workspace_id": "…",
  "app": { "id": "…", "key": "deal-enricher", "installation_id": "…" },
  "action": { "key": "enrich", "label": "Enrich with Acme" },
  "record": { "id": "…", "object": "accounts" },
  "user": { "id": "…", "name": "Sam Lee" }
}

Answer within eight seconds with 2xx and, optionally:

{ "message": "Added revenue estimate", "open_url": "https://acme.dev/report/123" }

The message is shown to the person and the link opened in a new tab. To read or change the record, use the API with the app's key. The person's email is never sent.

Good practice

Verify every signature, and de-duplicate on webhook-id.
Keep the key and signing secret on your server, never in a browser.
Ask for the fewest scopes that work; installers see the list before they agree.

What apps cannot do yet