WebRobot
App Builder · pages

Documentation · App Builder

Messaging and egress

An app reaches people by email and, when it has a phone app, by push notification. Its agents reach the outside world only through the external hosts the manifest lists. This page explains both, and says plainly what is not available yet.

Notifications

Every email an app sends is plain text, sent through the platform's email service. There are four places that send one:

WhereSends
triggers[].notifyAn email when an event happens: a record saved, a date reached, an approval decided, a purchase, a webhook, a timer.
schedules[].deliverThe report of a scheduled agent run.
templates[].deliverThe report of each run of a template instance.
notifications.emailOnRunDoneAn email to the user when their form run ends.

A trigger's notify

A trigger with notify sends an email instead of starting an agent.

triggers:
  - key: new_booking
    on: { collection: bookings, op: insert }
    notify:
      to: [admins, record.email]
      subject: "New booking: {record.name} on {record.date}"
      body: |-
        {record.name} booked for {record.guests} people on {record.date}.
        Phone: {record.phone}
      link: bookings
FieldMeaning
toOne recipient or a list of up to 5. See Recipients.
subject, bodyText, or one text per language. They may use the record's fields as {record.<field>} or {<field>}, plus {date} and {app} (the app's name). The {?x}…{/x} blocks of goal templates work too.
linkA view key (becomes /v/<key>) or a path starting with /. The full address is added at the end of the body.
channelOnly email.

The text is in the app's default language. Every email ends with a footer: the app's name and its address.

Recipients

ValueWho gets it
ownerThe user the event or run belongs to.
adminsThe app's admins.
role:<key>Every user holding that role. For a role assigned from admin emails, the admins.
record.<field>The email address (or list of addresses) in that field of the event's record.

record.<field> works only where the event carries a record: a collection, date, approval, call or webhook trigger. Validation refuses it elsewhere, and refuses a role: that is not declared. Values that are not valid email addresses are dropped; at most 50 addresses receive one message.

Report delivery

deliver on a schedule or a template emails the report of each finished run.

schedules:
  - cron: "0 7 * * 1"
    agent: weekly_digest
    deliver: { to: "role:manager", subject: "Weekly digest — {date}", onlyIfNew: true }
  • A template's report goes to the instance's owner by default (to: owner).
  • A schedule has no owner: deliver.to is required (admins or role:<key>).
  • subject defaults to the report's title (its first # heading); {date} and {title} can be used.
  • onlyIfNew: true skips the email when the report is the same as the last one delivered.
  • Charts in the report are left out of the email; the Markdown is kept as text.

Run-done email

With notifications.emailOnRunDone: true, the user who started a form run gets an email when it ends:

  • with a report: the subject is the report's title (or "Your report is ready") and the body links to the run page;
  • without one: "Your request did not complete", and the body says no credits were charged.

The scheduler also checks runs nobody is watching, so the email leaves on time even if the user closed the page. The texts are in Italian when the app's default language is it, in English otherwise.

notifications.digest is not used: put a schedule with deliver instead.

Limits and duplicates

  • Once per event. Each message has an id made of the event and the recipient. A webhook delivered twice, or a scheduler tick retried, never sends the same email twice.
  • Daily caps (UTC day): at most 300 emails a day per app and 10 a day per recipient. Beyond them, messages are skipped.
  • Subject up to 200 characters, body up to 20,000.

Push notifications

An app with a phone app can send push notifications. You enable them by declaring the push capability in spec.mobile.capabilities (see Export).

What happens:

  1. The app's admins open /admin/push and paste the keys of their own store accounts: the Firebase service account JSON (Android) and the APNs key (.p8 content, key id and team id, 10 letters or digits each; optionally sandbox) for iPhone. Each platform is optional. The keys are encrypted at rest and never shown again; the page shows only which platforms are set and how many devices are registered.
  2. After sign-in, the phone app registers the device for that user. A user keeps at most 10 devices; the oldest are dropped.
  3. Every notification above also goes to the recipients' phones, when they are users of the app with a registered device: a trigger's notify (same subject and body, and the link) and the run-done email ("Tap to open it."). Report delivery (deliver) sends email only.

Limits and behaviour:

  • At most 20 push notifications a day per user, once per event.
  • Title up to 120 characters, body up to 240. A link opens a page of the app.
  • A device the store reports as gone is removed.
  • Without keys for a platform, its devices are skipped: the app works before push is set up.

Channels

spec.channels declares where conversations come from. The schema accepts four types: web, phone, telegram and email, each tied to one agent.

TypeStatus
webAvailable: the app's chat views. See Agents and automation.
phoneNot available yet. Validation accepts it, and a trigger may name it in on.call, but the runtime does not receive calls yet.
telegramNot available yet.
emailNot available yet: the app does not receive email.

There is no SMS or WhatsApp channel.

Egress: calling external APIs

An agent reaches an external service in one of two ways:

  • an http app tool: one HTTPS request the runtime makes for the agent, to a host the manifest lists;
  • an MCP server in agents[].mcpServers, added to the agent at publish.

spec.egress.hosts lists the hosts the app's http tools may call (at most 20). Nothing else is reachable.

egress:
  hosts: [api.example.org, "*.myshopify.com"]
  notes: "api.example.org: public company register, CC BY 4.0. *.myshopify.com: each user's own shop."
agents:
  - key: researcher
    # ...
    appTools:
      - name: company
        description: "Look up a company by number: path = /companies/<number>"
        action: http
        http: { url: "https://api.example.org", allowPath: true, attribution: "Example register, CC BY 4.0" }

What the manifest fixes and what the agent fills

The manifest fixes the method, the base URL and any fixed headers. The agent fills only:

  • query — query-string parameters (text, numbers, booleans);
  • path — a path appended to the base URL, only when allowPath: true; letters, digits and ._~-/, at most 300 characters, no . or .. segments;
  • body — a JSON body, not for GET or DELETE, at most 100,000 characters.

The agent never sets headers, host, method or credentials.

The guards

  • HTTPS only. The URL must stay on the tool's own host.
  • The host must be in spec.egress.hosts. An entry *.<domain> is only for each user's own host, saved with their credential (https://{host}/… in the tool's URL).
  • Every address the host resolves to is checked when connecting: private, loopback, link-local and similar addresses are refused.
  • Redirects are not followed; the answer says where it pointed.
  • timeoutMs 1,000–30,000 (default 20,000). The response is cut beyond maxBytes (1,000–2,000,000, default 500,000).
  • Fixed headers may not carry credentials: Authorization, Cookie, X-Api-Key, Host, Forwarded, X-Forwarded-* and Proxy-* are dropped.

The tool returns {status, data} for JSON, else {status, text, truncated} (text cut at 20,000 characters), plus source when the tool sets attribution. Use egress.notes to record why each host is there and its terms of use.

Users' own keys

An http tool can send a key the user connected for a provider (spec.data.credentials, kind api_key):

http:
  method: GET
  url: "https://{host}/admin/api/2024-10/orders.json"
  credential: { provider: shopify, header: X-Shopify-Access-Token, format: "{secret}" }
  • Users connect their key on the account page; a credential with scope: org is set once by the app's admins. Keys are encrypted at rest and never shown again (only their last four characters), never put in a goal and never returned to an agent.
  • The runtime adds the key to the request: by default Authorization: Bearer {secret}; header and format change it; query sends it as a query parameter instead.
  • If the key appears in the response, it is replaced with [credential].
  • If the user has not connected the provider, the tool answers "the user has not connected <provider>: ask them to connect it on their account page".
  • PUT, PATCH and DELETE are meant for writing to the user's own account, with a credential.

Credentials of kind oauth and mcp are accepted by the schema but not offered on the account page yet.

MCP servers

agents[].mcpServers adds external MCP servers (up to 10 per agent) to the agent at publish. Each has a name, an https:// URL, optional headers and allow ("all" or a list of tool names). A header value must not contain a secret: reference a credential of your organisation as ${VAR}. Validation refuses a header that looks like a literal secret.