Provider Diagnostics

Diagnose provider setup before depending on it in a production workflow.

Doctor commands

woml telegram doctor --destination <chatId>
woml discord doctor --destination <channelId>
woml whatsapp doctor --phone-number-id <id> --callback-url <https-url>

Doctors verify identity, credentials, and optional destinations without creating a run or sending a business message. Slack reports actionable startup diagnostics instead of exposing a separate doctor command.

Common checks

• Confirm the credential type, not merely that a value exists.
• Reinstall provider apps after changing scopes or intents.
• Ensure only one runtime owns a polling or gateway identity.
• Verify the bot belongs to the destination and can read/send there.
• Keep callbacks authenticated and publicly reachable over HTTPS.

Credentials remain redacted in human and JSON diagnostics.

Diagnose in layers

Start with identity: does the token belong to the expected bot, app, workspace, or phone resource? Continue with permission: does that identity have the required scopes, intents, membership, and destination access? Then test transport ownership and callback reachability.

Do not change several settings at once. Verify one layer, restart WOML when the provider requires a fresh connection, and repeat the doctor.

Read common failures

Authentication success does not prove destination access. Slack may authenticate but lack channels:read; Discord may connect but receive empty content without Message Content Intent; Telegram may work in direct messages but not groups because of privacy mode; WhatsApp verification may pass while signed message delivery fails because the app secret or reverse proxy body handling is wrong.

Protect diagnostics

Doctor commands intentionally report token class, safe identity, required permission, and destination outcome without echoing credentials. Do not add debug logging that prints full provider responses or Authorization headers to compensate for a setup problem.

Recover production providers

Only one active runtime should own a polling or Gateway identity where the provider contract requires it. Use WOML's runtime ownership and graceful stop commands rather than killing and immediately duplicating provider hosts across machines.