BreezyCorp Handbook

Appearance

Set up an ingestion channel (WhatsApp / Drive / SharePoint / Dropbox) ​

Who does this: Senior Accountant · Platform Admin When: Onboarding a new bookkeeping client, or the client is moving from one document-delivery method to another (e.g. switching from WhatsApp to a shared Drive) Result: A connected channel that auto-feeds new documents into the platform, where they get OCR'd, classified, and dropped into the client's open journal batch.

Ingestion channels are how the platform avoids being a manual-upload tool. The four supported kinds all do the same job — pick up a new document and hand it to the OCR pipeline — but the connection mechanics differ. Pick what fits how the client already works:

  • WhatsApp Business — push-based, the client (or whoever they delegate) sends documents to the firm's WhatsApp Business number; an inbound webhook lands them on the right client by phone-number mapping.
  • Google Drive — pull-based, OAuth connect: click Connect, sign in with Google, and pick the watched folder through Google's own folder picker. No service account, no folder sharing.
  • SharePoint — pull-based, OAuth'd through the client's Microsoft 365 tenant (provider connect UI pending — still configured via JSON for now).
  • Dropbox — pull-based, OAuth connect: click Connect, sign in with Dropbox, and pick the watched folder.

A client can have multiple channels (e.g. WhatsApp for receipts, Drive for monthly invoices). Each is enabled or disabled independently.

Before you start ​

  • [ ] The client exists with Bookkeeping enabled.
  • [ ] You have credentials or access to whichever provider you're connecting:
    • WhatsApp: the firm's WhatsApp Business phone number ID, and the inbound webhook is wired up at the platform level (one-time setup, ask Platform Admin if unsure).
    • Google Drive / Dropbox: nothing in advance — you sign in during the Connect step. The Google / Dropbox OAuth apps are a one-time platform setup (see OAuth ingestion channels runbook).
    • SharePoint: the client's site/library URL and the OAuth credentials for an account with read access.
  • [ ] You have a sample document the client has agreed you can run through the channel for the smoke test (a real receipt or invoice from this client).

Steps ​

  1. Open Clients in the staff dashboard sidebar and click into your client.
  2. Open the Ingestion channels tab on the client detail page.
  3. Click Add channel in the top right.
  4. Pick the Channel type from the dropdown:
    • WhatsApp Business
    • Google Drive
    • SharePoint
    • Dropbox
  5. Fill in:
    • Label — a human-readable name for the channel; appears on the client detail page and in the activity log. Example: "Mason Industries — Ops shared Drive".
    • For Google Drive / Dropbox — that's it; there is no credentials or config to type. The connect step below handles it.
    • For WhatsApp / SharePoint / local-fs — also fill in:
      • Credentials ref (optional) — a key into the firm's secret store if the credentials are managed centrally. Leave blank if not in use.
      • Config (JSON) — the adapter-specific parameters: WhatsApp { "phoneNumberId": "..." }, SharePoint { "libraryUrl": "..." }.
  6. Click Create channel. The channel lands as Enabled by default.
  7. For Google Drive / Dropbox — connect the account:
    1. On the new channel row, click Connect Google Drive / Connect Dropbox.
    2. You're redirected to the provider's sign-in + consent screen. Sign in with the account that can see the client's documents and approve access.
    3. You land back on the Ingestion channels page; the row now shows Connected as <email>.
    4. Click Choose folder and pick the folder to watch — Google opens its own picker; Dropbox shows a folder browser. The chosen folder name shows on the row.
    • If the account ever needs re-authorizing, the row shows a red Reconnect required badge — click Reconnect to re-run consent.
  8. Smoke test. Drop your sample document into the source — send a WhatsApp message, copy the file into the connected folder, etc. Wait for the next folder-sync (see Timing reference for the cadence). Then:
    • Open the Documents tab on the client and confirm the file appears.
    • The channel row's Last polled timestamp updates after each sync attempt.

TIP

If you don't want to wait for the next sync window, drop a one-off document via Upload a document manually instead — it's a good way to confirm the rest of the pipeline works while you're waiting on the channel's first poll.

How to know it worked ​

  1. The Ingestion channels tab lists the channel with Enabled badge and the channel type.
  2. After the first successful poll, the row's Last polled timestamp appears.
  3. The activity log shows client.ingestion_channel.created and, after the first poll, bookkeeping.document.ingested for each file picked up.
  4. The smoke-test document shows up on the Documents tab; within ~30 seconds of OCR finishing, a draft journal entry appears in the client's current open batch.

What happens when something goes wrong ​

  • The polling loop catches errors per channel — a bad credential or revoked permission stops that channel without affecting others.
  • After a series of consecutive failures, the channel row shows the last error message (e.g. "403: insufficient permissions") under its label and stops further polls until you fix it.
  • To resume after fixing the underlying access: open the channel, click Disable, then Enable again — the next poll will retry.

Common situations ​

If you see…It means…What to do
Last polled still says never an hour after you savedThe folder-sync hasn't run yet, or the channel is disabledConfirm Enabled badge is set; if a full hour has passed, see A document didn't appear in any batch
Channel row shows a red Reconnect required badge or "error: Reauthorization required"The OAuth refresh token was revoked or expiredClick Reconnect on the channel row and re-run the provider consent — syncing resumes on the next poll
WhatsApp messages get sent but nothing appearsThe inbound webhook isn't routing to this client — check the phone-number → client mapping with Platform AdminConfirm the phoneNumberId in the channel's Config matches what the WhatsApp Business account is configured to forward
Document appears on the Documents tab but no journal entry followsOCR is failing or the chart-of-accounts is emptySee OCR failing runbook and confirm chart-of-accounts is populated
You need to stop ingestion temporarily (e.g. client is between accountants)Disable instead of deleteOpen the channel, click Disable. The platform stops polling immediately. Re-enable when ready — no data is lost.

Internal use only — BreezyCorp