> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# External Approval Channels

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

# 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](/docs/guides/approval-workflows). For the channel API reference (endpoints, request shapes), see [Notification channels](/docs/integrations/notification-channels).

## Prerequisites

<Check>An active organization with at least one agent</Check>

<Check>
  An approval trigger: a configured workflow or a policy rule that requires approval ([Securing
  Agents](/docs/guides/securing-agents))
</Check>

<Check>Admin or Owner role in your organization</Check>

## 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**.

<Steps>
  <Step title="Create the workflow">
    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         |
  </Step>

  <Step title="Verify it triggers">
    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>
</Steps>

## Step 2: Add a Notification Channel

<Steps>
  <Step title="Go to Settings > Channels">
    Click **Add Channel** and choose your platform.
  </Step>

  <Step title="Configure the channel">
    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
  </Step>

  <Step title="Select events">
    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
  </Step>

  <Step title="Test it">
    Click the test button. You should receive a sample notification on your platform.
  </Step>
</Steps>

## Step 3: Test the Full Flow

<Steps>
  <Step title="Trigger a payment that needs approval">
    Use the SDK or dashboard to request a payment above your approval threshold.

    ```bash theme={null}
    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" }'
    ```
  </Step>

  <Step title="Check your channel">
    Within a few seconds, you should receive a notification on your configured channel with payment details and Approve/Reject buttons.
  </Step>

  <Step title="Approve or reject">
    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.
  </Step>

  <Step title="Verify the audit log">
    Go to **Audit Logs** in the dashboard. You should see the approval decision with the channel recorded (e.g., `SLACK`, `EMAIL`).
  </Step>
</Steps>

## 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.
</Info>

## 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.

<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.
</Info>

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Notifications not arriving">
    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
  </Accordion>

  <Accordion title="Token expired or already used">
    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.
  </Accordion>

  <Accordion title="Slack buttons not working">
    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.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Channel Reference" icon="tower-broadcast" href="/docs/integrations/notification-channels">
    Full configuration reference for all channel types
  </Card>

  <Card title="Policy Testing" icon="flask-vial" href="/docs/guides/policy-testing">
    Test your approval workflows before going to production
  </Card>
</CardGroup>