external-provider
Access configured sidecar providers (health, banking, government) via WebFetch.
When & Why to Use This Skill
The External Provider skill enables Claude to securely interface with specialized sidecar services for health, banking, and government sectors. It automates complex data retrieval tasks by dynamically reading provider schemas, executing authenticated WebFetch calls, and managing multi-factor authentication (OTP) challenges. This skill is essential for agents requiring real-time access to sensitive personal or institutional records while maintaining strict security protocols and handling document attachments seamlessly.
Use Cases
- Financial Monitoring: Retrieve real-time bank balances and transaction histories from configured banking providers to assist with personal or business accounting.
- Healthcare Management: Access medical records, upcoming appointments, and download clinical visit summaries or lab results directly through secure health service integrations.
- Government Document Retrieval: Check the status of official applications and securely download government-issued documents like permits or status reports.
- Secure Authentication Flow: Handle multi-factor authentication (MFA) by identifying OTP requirements and guiding the user through the verification process for protected services.
- Automated Attachment Handling: Identify, fetch, and deliver service-related documents (e.g., PDFs) from external providers to the user's communication channel.
| name | external-provider |
|---|---|
| description | Access configured sidecar providers (health, banking, government) via WebFetch. |
| allowed-tools | Read, WebFetch, Bash |
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 configuration 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)
If the schema includes
credentialFields, use them to explain which fields an operator must configure (never ask users for credentials).
How to Use
CRITICAL: You MUST read references/provider-schema.md BEFORE making any WebFetch calls.
Never guess or fabricate URLs. The schema file contains the exact base URL and available endpoints.
First, read the schema file to get the provider's base URL and available endpoints:
Read references/provider-schema.mdThis file shows the exact base URL (e.g.,
http://provider-sidecar:3001) and all available service endpoints.Then fetch data via WebFetch to the provider's REST API (POST for service endpoints):
- Use the EXACT base URL from the schema (do NOT use localhost, 127.0.0.1, or made-up hostnames)
- Use the EXACT endpoint paths from the schema (e.g.,
/v1/{service}/{action})
WebFetch({ url: "<exact-base-url-from-schema>/v1/{service}/{endpoint}", method: "POST", body: "{\"subjectUserId\":\"<target-user-id>\",\"params\":{...}}" })- Telclaude injects
x-actor-user-idfor provider calls automatically; do not fabricate headers - If the user is requesting their own data, omit
subjectUserId. - Use
/v1/healthwith GET only when checking provider status.
Parse the JSON response. Expected shape (provider-defined fields may vary):
{ "status": "ok" | "auth_required" | "challenge_pending" | "error" | "<provider-specific>", "data": { "noResults": "Optional - if present, means no data found (valid response)", "items": [], ... }, "confidence": 0.0-1.0, "lastUpdated": "ISO timestamp", "error": "message if status indicates failure", "partial": { ... }, "challenge": { "id": "challenge-id", "type": "<provider-specific challenge type>", "hint": "sent to ***1234", "service": "service-name", "prompt": "SMS verification code", "captureMethod": "text" | "browser", "interactUrl": "https://... (if browser-based)", "instructions": "Optional instructions" }, "attachments": [ { "id": "att_abc123.<expires>.<sig>", "filename": "document.pdf", "mimeType": "application/pdf", "size": 12345, "expiresAt": "ISO timestamp", "inline": "base64-content-if-small" } ] }Handle status codes:
ok: Present the data. IMPORTANT: Check fornoResultsfield in data - if present, tell user "no records found" (this is NOT an error, just empty results)auth_required: Inform user that service needs authentication setup (never ask for credentials)challenge_pending: Ask user to complete verification via/otp <service> <code>(or includechallengeIdif provided)parse_error/extraction_error(if returned): Some data couldn't be extracted; checkpartialfor available data anderrorfor detailserror: Show error message to user
Handle attachments (if present):
- The
idis a signed token:att_<hash>.<expiresTimestamp>.<signature> - Small files (≤256KB) may include
inlinebase64 content - Large files omit
inline- the relay must fetch via/v1/attachment/{id}using the full signed ID - Attachments expire after ~15 minutes (check
expiresAt) - Mention available attachments to the user (filename, type, size)
- The
Delivering Attachments to Users (READ_ONLY compatible)
When a provider response includes attachments and the user wants the file delivered:
Use WebFetch to the relay attachment endpoint (no auth headers needed; telclaude injects them). Use the relay base URL (Docker default:
http://telclaude:8790):WebFetch({ url: "http://telclaude:8790/v1/attachment/fetch", method: "POST", body: JSON.stringify({ providerId: "<provider-id>", attachmentId: "<attachment.id>", filename: "<attachment.filename>", mimeType: "<attachment.mimeType>", size: <attachment.size>, inlineBase64: "<attachment.inline>" // if present (small files) }) })inlineBase64is only for small attachments that includeinline.- Omit
inlineBase64for large files; the relay will fetch via/v1/attachment/{id}.
The response contains the saved file path:
{ "status": "ok", "path": "/media/outbox/documents/visit_summary-1737099600-abc123.pdf" }Include the path in your response - the relay automatically sends files from
/media/outbox/documents/to Telegram:"I've downloaded your document: /media/outbox/documents/visit_summary-1737099600-abc123.pdf"
Example:
WebFetch({
url: "http://telclaude:8790/v1/attachment/fetch",
method: "POST",
body: JSON.stringify({
providerId: "<provider-id>",
attachmentId: "att_abc123.1737100000.sig",
filename: "attachment.pdf",
mimeType: "application/pdf"
})
})
Note: Only fetch attachments when the user explicitly requests the file. First tell them what's available, then offer to send it.
Important Rules
- Never ask for credentials - The provider handles authentication separately
- Never guess URLs - Only call endpoints documented by the provider
- Show confidence levels - If confidence < 1.0, mention data may be incomplete
- Show freshness - Always tell user when data was last updated
- Handle challenges gracefully - If OTP needed, explain the
/otp <service> <code>command - Browser challenges - If
captureMethodisbrowserorinteractUrlis present, give the user the link and instructions to complete it
Example Responses
Successful data fetch:
"Your next appointment is on January 15th at 2:30 PM with Dr. Cohen (Cardiology). This information was last updated 5 minutes ago."
Challenge pending:
"To access your bank balance, please complete verification. Check your phone for an SMS code, then reply with /otp <service> <code>."
Auth required:
"This service needs to be set up first. Please ask the operator to configure authentication for the banking service."
No results found (status ok, but noResults field present):
"I checked your hospital summaries but there are no records available. This means there are no discharge summaries on file for the selected hospital."
Partial/parse error:
"I couldn't fully retrieve your data - some information may be missing. Here's what I found: [partial data]. The service may need maintenance if this persists."
Attachment available:
"I found your visit summary from January 10th. There's a PDF document available (visit_summary_2024-01-10.pdf, 245 KB). Would you like me to send it to you?"
Attachment delivered:
"I've downloaded your visit summary: /media/outbox/documents/visit_summary_2024-01-10.pdf"
Endpoints Reference
Common provider endpoints (actual availability depends on configuration). For the authoritative list, see the Provider Schemas section below.
| Endpoint | Description |
|---|---|
/v1/{service}/summary |
Overview/dashboard data |
/v1/{service}/appointments |
Upcoming appointments |
/v1/{service}/transactions |
Recent transactions |
/v1/{service}/balance |
Current balance |
/v1/health |
Provider health status |
/v1/challenge/respond |
OTP submission (relay-only) |
/v1/attachment/{id} |
Download attachment by signed ID |
/v1/attachment/fetch |
Relay endpoint - fetch and save attachment for Telegram delivery |
Provider Schemas (auto-generated)
See references/provider-schema.md for the latest schema fetched from /v1/schema.