External Approval Channels

# External Approval Channels

> Set up email, Slack, Telegram, and WhatsApp approval flows so your team can approve payments without logging into Conto

- Human URL: https://conto.finance/docs/guides/external-approvals
- Raw Markdown: https://conto.finance/docs/guides/external-approvals.md
- Terminal view: https://conto.finance/ai/docs/guides/external-approvals

Documentation group: Guides

# External Approval Channels

This guide walks through setting up approval notifications so your team can approve or reject payments from wherever they already work.

This is the setup walkthrough. For the concepts (when to use approval workflows, trigger conditions, patterns), see [Approval workflows](https://conto.finance/guides/approval-workflows). For the channel API reference (endpoints, request shapes), see [Notification channels](https://conto.finance/integrations/notification-channels).

## Prerequisites

An active organization with at least one agent

  An approval trigger: a configured workflow or a policy rule that requires approval ([Securing
  Agents](https://conto.finance/guides/securing-agents))

Admin or Owner role in your organization

## What You'll Build

By the end of this guide, your approval flow will look like this:

```
Agent requests $500 payment
  → Approval workflow triggers
    → Approver gets a Slack message with Approve/Reject buttons
    → Approver clicks "Approve" in Slack
      → Payment is approved and executed
      → Audit log records: who, when, which channel
```

## Step 1: Set Up an Approval Workflow

If you haven't already, create an approval workflow that triggers on the conditions you care about.
For multi-review, sequential, or specifically assigned approvals, configure a custom workflow. A
policy rule that requires approval without a matching custom workflow still creates a one-review
request for an organization Owner, Admin, or Manager in **Alerts & Approvals**.

    Go to **Policies** in the dashboard. Create a new Approval Workflow with:

    | Field | Example Value |
    |-------|--------------|
    | Name | Large Payment Review |
    | Amount Threshold | $100 |
    | Required Approvals | 1 |
    | Timeout | 24 hours |
    | Approver Roles | OWNER, ADMIN |

    Request a payment above your threshold and confirm that Conto marks it as waiting for review.
    Keep the returned payment request ID and check its customer-facing status before taking another
    payment action.

## Step 2: Add a Notification Channel

 Channels">
    Click **Add Channel** and choose your platform.

    Fill in the platform-specific fields.

    **For Slack:**
    - Bot Token: `xoxb-...` (from your Slack app)
    - Channel ID: `C0123456789`

    **For Email:**
    - Recipients: `cfo@company.com, finance@company.com`

    **For Telegram:**
    - Bot Token: from @BotFather
    - Chat ID: your group chat ID

    At minimum, enable `approval.requested`. Consider also enabling:
    - `approval.escalated` for time-sensitive visibility
    - `approval.expired` so nothing falls through the cracks
    - `payment.executed` on `WEBHOOK` channels if your verifier needs to mark invoices as paid
    - `approval.approved` / `approval.denied` on your organization webhook when a decision is final, for your own audit trail

    Click the test button. You should receive a sample notification on your platform.

## Step 3: Test the Full Flow

    Use the SDK or dashboard to request a payment above your approval threshold.

    ```bash
    curl -X POST https://conto.finance/api/sdk/payments/request \
      -H "Authorization: Bearer $SDK_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "amount": 500, "recipientAddress": "0x...", "purpose": "Test approval" }'
    ```

    Within a few seconds, you should receive a notification on your configured channel with payment details and Approve/Reject buttons.

    Complete the approval from the email confirmation page or the Conto dashboard. When the final
    required approval is recorded, a Conto-managed wallet submits the payment automatically. The
    approval review then links directly to the chain explorer receipt. If custody execution cannot
    be completed, the approval remains recorded and the review shows that automatic execution needs
    attention instead of presenting a receipt. External and smart-contract wallets continue through
    their manual execution and confirmation flow.

    Go to **Audit Logs** in the dashboard. You should see the approval decision with the channel
    recorded (e.g., `SLACK`, `EMAIL`). Conto commits the decision, request state, and audit record
    atomically, so a successful decision cannot lose its audit entry.

## Multiple Channels

You can configure multiple channels simultaneously. When an approval request is created, notifications are sent to all active channels that subscribe to the `approval.requested` event. The first approver to act from any channel resolves the request.

Info:

  Notification channels deliver independently. If one channel is unavailable, other configured
  channels can still deliver. Temporary delivery failures are retried.

## Webhook Integration for Custom Systems

If you already have your own approval system, use the Webhook channel type to receive approval requests and hand the final decision off to an authenticated Conto approver.

  Approval authority is enforced the same way on every channel. Whether a decision arrives from the
  dashboard, Slack, Telegram, WhatsApp, email, or a webhook, the deciding member must hold an
  approval-capable role (`OWNER`, `ADMIN`, or `MANAGER`). Read-only roles (`VIEWER`, `MEMBER`) cannot
  clear a payment even if a workflow lists them, and the initiator cannot self-approve unless a
  custom workflow explicitly opts in.

Info:

  `/api/approvals/action` only processes payment-approval decision tokens. `GET ?token=...` never
  records a decision directly; it redirects to a hosted confirmation page first so mail scanners and
  link previews cannot approve or reject a request by accident. `POST` accepts only `APPROVE` and
  `REJECT` tokens from approval notifications. Store-order approval emails and auto-pay disable
  links use their own hosted action flows.

```bash
# 1. Configure a webhook channel pointing to your system
# 2. Your system receives a signed approval-request payload
# 3. Notify your reviewers or link them to the Conto approval inbox
# 4. Complete the decision in Conto
```

## Troubleshooting

    1. Check that the channel is **active** (toggle is on) in Settings > Channels
    2. Review the delivery notice shown for the channel
    3. Verify your bot token or credentials are correct
    4. For Slack, confirm the bot is invited to the target channel
    5. For Telegram, confirm the webhook URL is set correctly

    Action tokens are one-time use and expire with the approval request. If the approval request has already been resolved (by another approver or from the dashboard), the token is no longer valid.

    Confirm your Slack app's interactivity request URL is set to `https://conto.finance/api/webhooks/slack`, then reconnect the channel in Conto if the issue continues.

## Next Steps

### Channel Reference
Link: https://conto.finance/integrations/notification-channels

    Full configuration reference for all channel types

### Policy Testing
Link: https://conto.finance/guides/policy-testing

    Test your approval workflows before going to production