/fax-send

name: fax-send
description: "Send outbound faxes through a guarded provider adapter and route inbound fax-to-email attachments into downstream document workflows."
user-invocable: true
requires:
  bins:
    - node
credentials:
  - id: sinch-fax-basic-auth
    kind: header
    required: false
    secret_ref:
      source: store
      id: SINCH_FAX_BASIC_AUTH
    scope: "fax.api.sinch.com"
    how_to_obtain: "Create Sinch Fax API credentials for the target EU project/service and base64-encode username:password. Set `SINCH_FAX_BASIC_AUTH` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set SINCH_FAX_BASIC_AUTH \"<base64>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set SINCH_FAX_BASIC_AUTH \"<base64>\"`."
  - id: sinch-fax-oauth-token
    kind: bearer
    required: false
    secret_ref:
      source: store
      id: SINCH_FAX_OAUTH_TOKEN
    scope: "fax.api.sinch.com"
    how_to_obtain: "Use only when the operator has an OAuth token minting path for Sinch Fax. Set `SINCH_FAX_OAUTH_TOKEN` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set SINCH_FAX_OAUTH_TOKEN \"<access-token>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set SINCH_FAX_OAUTH_TOKEN \"<access-token>\"`."
metadata:
  hybridclaw:
    category: communication
    short_description: "Guarded outbound fax sending for DACH PDF workflows."
    tags:
      - fax
      - dach
      - sinch
      - healthcare
      - legal
      - steuerberater
    related_roadmap:
      - R26
    issue: 659
    stakes_tiers:
      green:
        - fax.status
        - fax.classify-status
        - fax.plan
      amber:
        - fax.send
    escalation:
      writes: confirm-each
      route: f8
    cost_measurement:
      system: UsageTotals
      sub_limit_key: fax-pages
      unit: fax-page

Fax Send

Use this skill when a user asks to fax a supported file, web page, text note, or PDF to an external fax number, or when an inbound fax arrives as an email PDF and needs routing to a document workflow such as DATEV Belegtransfer, file storage, or client records.

Response Contract

• Return exactly one user-facing summary per fax request. Do not restate the

same plan, missing-input list, or no-send notice in a second format.

• For provider results, write the status sentence once. Do not emit both a

markdown-styled version and a plain-text duplicate of the same sentence.

• Do not use decorative emoji, checkmarks, sign-off text, or "ready to proceed"

filler in fax responses.

• If setup is blocked by missing secrets, report each missing secret exactly

once and only if it is actually required: `SINCH_FAX_PROJECT_ID` plus either `SINCH_FAX_BASIC_AUTH` or `SINCH_FAX_OAUTH_TOKEN`. Never claim a Sinch service ID secret is required for normal outbound sending.

• When the user provides text content such as "Hallo Welt", use the helper's

helper-generated PDF upload path after the recipient fax number, stored Sinch project ID, stored credential, and explicit approval are available. Omit `from` when the user wants to use the Sinch Fax service default sender. Do not ask the user for a service ID for a normal outbound send; Sinch uses the product's default Fax service when `serviceId` is omitted.

• A live `http_request` to Sinch is terminal for that send attempt. After it

returns, stop and report the provider result. Do not use `web_search`, `web_fetch`, the PDF skill, local PDF scripts, helper source inspection, or ad hoc replacement requests, and do not ask to retry in the same response, unless the user explicitly asks for debugging in a new turn.

Scope

• outbound fax send from a content URL or direct generated-PDF text upload
• outbound fax send from a local generated PDF file
• Sinch Fax API request construction for EU-resident Sinch projects/services
• delivery status lookup and status-to-audit-event classification
• fax-page cost measurement in helper output
• inbound fax-to-email operating recipe through the existing email channel
• eval scenarios for successful send, busy/retry, failed delivery, and inbound

PDF handoff flows

Direct modem control, T.38/SIP live transmission, binary local file upload, and cover-page templating are outside this skill slice.

Credential Rules

Store credentials in HybridClaw encrypted runtime secrets. Never paste them into chat or helper arguments.

For Sinch Basic auth, set the base64 value of `username:password` in this order:

1. Browser admin: open the active HybridClaw admin URL ending in `/admin/secrets` and set `SINCH_FAX_BASIC_AUTH`. 2. Browser `/chat` or TUI fallback: `/secret set SINCH_FAX_BASIC_AUTH "<base64-username-password>"`. 3. Local console fallback:

hybridclaw secret set SINCH_FAX_BASIC_AUTH "<base64-username-password>"

For Sinch OAuth, set a bearer token only if the operator has a token minting process, using the same setup order:

1. Browser admin: open the active HybridClaw admin URL ending in `/admin/secrets` and set `SINCH_FAX_OAUTH_TOKEN`. 2. Browser `/chat` or TUI fallback: `/secret set SINCH_FAX_OAUTH_TOKEN "<access-token>"`. 3. Local console fallback:

hybridclaw secret set SINCH_FAX_OAUTH_TOKEN "<access-token>"

The helper emits either `secretHeaders: [{ name: "Authorization", secretName: "SINCH_FAX_BASIC_AUTH", prefix: "Basic" }]` or `bearerSecretName: "SINCH_FAX_OAUTH_TOKEN"` so the gateway injects the secret server-side.

Set the Sinch project default once so normal sends do not need provider account arguments:

1. Browser admin: open the active HybridClaw admin URL ending in `/admin/secrets` and set `SINCH_FAX_PROJECT_ID`. 2. Browser `/chat` or TUI fallback: `/secret set SINCH_FAX_PROJECT_ID "<sinch-project-id>"`. 3. Local console fallback:

hybridclaw secret set SINCH_FAX_PROJECT_ID "<sinch-project-id>"

Default Workflo