Permission modes: ask every time, notify only, rights-based
How much autonomy a connected app has: the default approve-every-task mode, notify-only auto-dispatch with a cancel window, rights-based auto-dispatch that fails closed, the sharing envelope, per-connection daily caps and frozen connections.
Every connected app has a permission mode, set by the user in Simp under Connected apps. The mode decides whether a task your integration creates needs a tap in the Simp app before anyone is contacted. Whatever the mode, every call still passes every cost gate at dispatch, every task is visible in the app, and sharing can never be widened without a human checkpoint.
get_user_info returns the current mode as connection, so your integration can set the user's expectations honestly - telling them the task will wait for their approval, or that it will start after a heads-up.
The three modes#
| Mode | What happens when an app creates a task | Default daily cap |
|---|---|---|
ask_every_time (default) | The task waits in the Simp app for the user's approval. create_task returns status: "awaiting_approval" and an approval_url; the approval expires after an hour. | 50 tasks |
notify_only | The task dispatches without an approval tap: the user gets a heads-up push naming the app ("ChatGPT started a task") and has a short cancel window; create_task returns status: "dispatching". | 20 tasks |
rights_based | The task dispatches without approval only if it matches the rights the user granted this connection; otherwise that one task falls back to ask_every_time. | The connection's own max_tasks_per_day |
Every new connection starts as ask_every_time. Moving to a lighter mode is a deliberate user action in the Simp app; no API call can change a connection's mode.
Rights (fixed set)#
A rights_based connection carries a small, fixed rights object. Evaluation is fail-closed: anything not positively authorised asks for approval.
| Right | Meaning | If absent or not met |
|---|---|---|
allowed_task_kinds | Kinds that may auto-dispatch: any of call, get_answer, send_update, follow_up | A connection granted before this right existed reads as ["call"]. A task of another kind asks. |
allowed_task_types | The call categories the user allows; a task from create_task counts as custom | Missing, empty or without custom: every task asks. |
max_tasks_per_day | Auto-dispatched tasks per UTC day for this connection | Missing: every task asks. At the cap: further tasks ask. |
known_contacts_only | Only people the user already knows: a saved contact, a number they have called, or a person Simp already holds for them | true and a participant is new: the task asks. |
boundaries.known_contacts_only on create_task is a different thing: it is the user's limit for that one task, and a task that breaks it is refused (participant_not_known), whatever the mode.
Falling back to approval is never an error: the tool returns awaiting_approval with the usual approval_url, and the app's note in get_user_info already said it might.
The sharing envelope#
Your integration can name About You field names on a task (allowed_info) so the simp may share those details; they never see or pass the values. Each connection has a sharing envelope: the set of field names the user has pre-agreed this app may enable without a fresh approval. It is empty by default.
| Situation | Result |
|---|---|
allowed_info names fields inside the envelope | Shared under the user's rules; the task may auto-dispatch (notify_only / rights_based). |
allowed_info names any field outside the envelope | That one task escalates to in-app approval, whatever the mode. Never a silent share, never a silent drop. |
forbidden_info | Always honoured, in every mode. Narrowing is always allowed. |
| A field the user has globally forbidden | Stays forbidden even if named in allowed_info; it cannot be placed in an envelope. |
In short: your integration can always narrow what is shared; widening goes through a human, either at approval time or by the user pre-granting the envelope.
Daily caps#
Each connection has a per-day task cap by mode (50 / 20 / the granted max_tasks_per_day for rights-based). Past it, create_task returns connection_daily_cap_reached. This is defence in depth on top of the per-minute rate limits and the user's plan minutes.
Frozen connections#
An unusual calling pattern from a connection (the platform's spend watchdog) freezes it: new tasks are refused with connection_frozen until the user re-enables the connection in Connected apps. The note in get_user_info says so; the agent's job is to tell the user, not to retry.
What the user sees#
- Connected apps lists every connection with its mode, rights, envelope and webhooks, and lets the user change any of it or disconnect.
- Every auto-dispatched task starts with a push that names the app, so autonomy is never invisible.
- Task Detail shows which fields the simp actually shared, including envelope-shared ones.