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, the platform watches a specific folder (via a service account the client shares to) and ingests new files on its hourly sync.
  • SharePoint — pull-based, OAuth'd through the client's Microsoft 365 tenant; same hourly sync.
  • Dropbox — pull-based, OAuth'd through the client's Dropbox account; same hourly sync.

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: a folder the client has shared with the firm's service account email, and the folder's ID.
    • SharePoint: the client's site/library URL and the OAuth credentials for an account with read access.
    • Dropbox: the OAuth'd account and the path to the watched folder.
  • [ ] 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".
    • 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": "..." }
      • Google Drive: { "folderId": "..." }
      • SharePoint: { "libraryUrl": "..." }
      • Dropbox: { "path": "/Apps/Spade/Mason" }
  6. Click Create channel. The channel lands as Enabled by default.
  7. Smoke test. Drop your sample document into the source — send a WhatsApp message, copy the file into the Drive folder, etc. Wait up to one hour (default folder-sync interval — see Timing reference for the exact 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 "error: 403" or "error: token expired"The OAuth token or service-account permission has been revoked or expiredReconnect the credentials at the source (re-share the Drive folder, refresh OAuth on Dropbox/SharePoint), then disable + re-enable the channel
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