External Provider

External Provider

Use this skill when the user asks about data from configured external providers (citizen services, banking, health, etc.).

Available Services

Check the provider schema to see which services are available. The authoritative list is the provider's /v1/schema response (cached in references/provider-schema.md when available). Common examples:

• Health services (appointments, records)
• Banking services (balance, transactions)
• Government services (documents, status)

How to Use

IMPORTANT: Use the telclaude providers ... CLI commands for all provider operations.

• Do NOT use WebFetch or curl to call provider endpoints directly
• Use Bash only to run telclaude CLI commands (providers query, providers schema, send-attachment, etc.)
• The CLI handles authentication through the relay (mechanism is provider-dependent)
• Direct HTTP calls will fail with "Missing internal auth headers"
• The relay sanitizes responses (strips inline base64, stores attachments)

User ID

Extract the user ID from <request-context> for provider queries.

Look for this tag in your system context:

<request-context user-id="admin" />

telclaude providers query falls back to TELCLAUDE_REQUEST_USER_ID when the relay exports it, but pass --user-id explicitly whenever you have the value or when running outside the relay context.

1. Read the schema file

Read references/provider-schema.md

This shows the provider ID and available services/actions.

2. Query the provider via CLI

telclaude providers query <providerId> <service> <action> --user-id <userId>

With parameters:

telclaude providers query <providerId> <service> <action> --user-id <userId> --params '{"key": "value"}'

Examples (assuming <request-context user-id="admin" />):

# Get appointments
	telclaude providers query my-provider health-api appointments --user-id admin

# Get bank transactions with date range
	telclaude providers query my-provider bank-api transactions --user-id admin --params '{"startDate": "2024-01-01"}'

# Get document status
	telclaude providers query my-provider gov-api status --user-id admin

3. Parse the response

The command outputs JSON. The exact shape is provider-dependent, but the common structure is:

{
  "status": "ok" | "auth_required" | "challenge_pending" | "error",
  "errorCode": "credentials_missing" | "session_expired" | "auth_required" | "...",
  "data": { ... },
  "attachments": [
    {
      "id": "att_123",
      "filename": "document.pdf",
      "mimeType": "application/pdf",
      "size": 12345,
      "ref": "att_abc123.1234567890.signature",
      "textContent": "Extracted text from the PDF for analysis..."
    }
  ]
}

Some providers may include additional fields (e.g., confidence, lastUpdated, errorCode).

**Note:** The relay proxy intercepts responses and:
- Strips `inline` base64 content (you won't see it)
- Stores the file in the outbox
- Adds a `ref` token for delivery

### 4. Handle status codes

- `ok`: Present the data. Check for `noResults` field - if present, tell user "no records found"
- `credentials_missing`: The provider has no stored session for this user. For session-only
  providers, tell the operator to run `/providers enroll <service>`. Do not give CLI password
  setup instructions and do not ask the user for credentials.
- `session_expired`: The stored provider session is no longer usable. Tell the operator to
  re-enroll with `/providers enroll <service>`. Do not treat this as first-time setup or give
  CLI password instructions.
- `auth_required`: Authentication is required but the provider did not identify whether the
  session is missing or expired. Use the provider's documented session-only enrollment path.
- `challenge_pending`: Ask user to complete verification via `/otp <service> <code>`
- `error`: Show error message to user

## Handling Attachments

Attachments include:
- `ref`: Token to retrieve the stored file (use with `telclaude send-attachment`)
- `textContent`: Extracted text content (for PDFs, documents) - use this to analyze/summarize

**Important:** You will NOT see `inline` base64 content. The relay proxy strips it and stores the file automatically. Use `ref` to send files to users.

### Reading document content

Use `textContent` to answer questions about the document:

"Based on the document, [relevant information extracted from textContent]..."

### Sending files to the user

There are two cases depending on file size:

#### Case 1: Has `ref` — already stored

If the attachment has a `ref` field, the relay proxy already stored the file:

```bash
telclaude send-attachment --ref <attachment.ref>

Case 2: No ref — fetch from provider

If ref is empty, fetch the attachment directly:

telclaude fetch-attachment --provider <providerId> --id <attachment.id> --filename <attachment.filename> --mime <attachment.mimeType>

Output and delivery

Both commands output:

Attachment ready: /media/outbox/documents/<filename>.pdf

or

Attachment saved to: /media/outbox/documents/<filename>.pdf

You MUST include the exact path in your response. The relay watches for this path to trigger Telegram delivery.

Example workflow

1. User asks for data or a document
2. Call provider via telclaude providers query
3. Response includes data and optionally attachments with ref and textContent
4. Present the data to the user
5. If attachments exist, use textContent to summarize the document
6. If user wants the file:
   • If ref is present: telclaude send-attachment --ref <ref>
   • If ref is empty: telclaude fetch-attachment --provider <providerId> --id <id> ...
7. Include the exact path from output in your response

Important Rules

1. ALWAYS extract user-id for provider queries - Look for <request-context user-id="..." /> in your context. Pass it via --user-id when available, or rely on TELCLAUDE_REQUEST_USER_ID only when the relay already exports it.
2. ALWAYS use the provider - NEVER search for local files in the workspace when the user asks for health, banking, or government data. Always use telclaude providers query to fetch fresh data from the provider.
3. Use CLI for provider queries - Use telclaude providers query, not WebFetch or curl
4. Never ask for credentials - The provider handles authentication separately. Session-only providers use /providers enroll <service> and never use CLI password setup.
5. Show confidence levels - If confidence < 1.0, mention data may be incomplete
6. Show freshness - Always tell user when data was last updated
7. Handle challenges gracefully - If OTP needed, explain the /otp <service> <code> command
8. Never copy files directly to outbox - Only use telclaude send-attachment or telclaude fetch-attachment to deliver files. Copying files directly to /media/outbox/ will NOT trigger delivery.

Example Responses

Successful data fetch:

"Your next appointment is on [date] at [time]. This information was last updated [X] minutes ago."

Challenge pending:

"To access this service, please complete verification. Check your phone for an SMS code, then reply with /otp <service> <code>."

Auth required:

"Authentication is required. Ask the operator to run /providers enroll <service>."

Provider session missing:

"This provider is not enrolled for this user. Ask the operator to run /providers enroll <service>."

Provider session expired:

"The provider session expired. Ask the operator to re-enroll with /providers enroll <service>."

Attachment available:

"I found a document from [date]. There's a PDF available ([size]). Would you like me to send it to you?"

Attachment sent (use EXACT path from relay response):

"Here's your document: /media/outbox/documents/.pdf"

CLI Command Reference

Note: Extract user-id from <request-context user-id="..." />. Pass --user-id when available; otherwise providers query can use TELCLAUDE_REQUEST_USER_ID if the relay injected it.

Provider Schemas (auto-generated)

See references/provider-schema.md for the latest schema fetched from /v1/schema.