# Ingfah

> Answer questions about Ingfah (อิงฟ้า) from its bundled user guide (คู่มือ), recommend practical setups and improvements for business goals, plan pilots, write FAQ files for its knowledge base (คลังความรู้), and work with the Ingfah client platform through client API-key authenticated APIs. Use when the user asks anything about Ingfah — services, how to do something in the dashboard, telephony, onboarding, settings, billing, release notes — wants an FAQ or knowledge document for an AI Agent, asks to inspect or manage products, AI agents, chat sessions, tools, customer templates, outbound batches, or analytics, or reports something wrong in what they see (a bad call summary or title, wrong outcome labels, an agent saying the wrong thing, missed calls) and wants it fixed, including in the dashboard's English or Thai words: AI Agent Team / ทีม AI Agent, batch / Batch โทรออก, calls / สายทั้งหมด, chats / แชท, templates / เทมเพลตข้อมูลลูกค้า, tools / Tool, knowledge / คลังความรู้, post-call results / ผลลัพธ์หลังวาง

- Skill: `100x-fi/ingfah` (Agent Skill, multi-file: 128 files)
- Install (CLI): `npx get-skill add 100x-fi/ingfah`
- Raw SKILL.md: https://api.skillmd.com/api/skills/100x-fi/ingfah/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: 100x-fi (https://skillmd.com/u/100x-fi)
- Updated: 2026-11-19
- Page: https://skillmd.com/skills/100x-fi/ingfah

---


# Ingfah

This skill answers questions, advises users on their setup, and carries out
supported tasks:

1. **Answers questions about Ingfah** from the bundled user guide — see
   "Answering questions about Ingfah" below. No API key needed.
2. **Writes FAQ files for the knowledge base** (คลังความรู้) — read
   `references/faq-authoring.md` first. No API key needed.
3. **Calls the Ingfah client API** with the user's client API key, using only
   the routes listed below.
4. **Recommends a practical setup or improvement** for the user's business
   goal. Read `references/consulting.md` for discovery, tradeoffs, pilot plans,
   and worked examples. No API key is needed for advice.

The default Ingfah API base URL is `https://api.ingfah.ai`. Use another base URL only when the user explicitly provides one.

This file holds the rules that apply to every task. The detail for each area
is in `references/`; **read the matching file before working in that area**:

| Task | Read first |
|---|---|
| Recommend a setup, assess suitability, plan a pilot, or improve business results | `references/consulting.md`, then the matching technical reference and user-guide page |
| Answer a question about Ingfah or how to use the dashboard | `references/user-guide/INDEX.md`, then the matching page |
| Write, convert, or update an FAQ or knowledge file | `references/faq-authoring.md` |
| Write or edit an agent's prompt | `references/prompt-authoring.md` — a prompt that bakes per-call data into its body is incorrect, not merely suboptimal. Its Jinja section lists engine traps that fail silently, and "Testing a change" has the go-live checklist |
| Create or edit an agent, a revision, or an AI Agent Team | `references/agents-and-teams.md` — every revision must re-send the agent's tool ids, which the revision read does not return |
| Design, build, or change a team of several agents that hand a call between them | `references/multi-agent-teams.md` — handoff tools are minted from the team's edges and named after the target agent's slug; each agent still binds its own tools |
| Create, pause, resume, or cancel an outbound batch | `references/outbound-batches.md` |
| Read, write, or test-run a Tool | `references/tools.md` |
| A voice agent should transfer a call to a person, or the client asks how transfers work | `references/voice-handoff.md` |
| A text (LINE / chat) agent should hand a chat to a person, or the AI should be switched on or off for one conversation | `references/text-chat-handoff.md` |
| Design disposition outcomes or an outcome metadata schema | `references/outcome-design.md` |
| Set up automated tests for an agent, or run them before publishing | `references/testing.md`, with the template in `templates/promptfoo-suite/`. The user supplies a model API key and each run costs money |
| Create or edit a postprocessor | `references/postprocessors.md` |
| Set up a Chat Automation (webhook, do-not-contact) | `references/automations.md` |
| Translate a field name the user reads in the dashboard | `references/dashboard-terms.md` |
| The user complains about something they see (a wrong summary, label, answer, or voice; missed calls) | `references/troubleshooting.md` |
| Analytics, text chat inbox, channels, or why outbound calls failed | `references/reporting.md` |
| Check capacity before an inbound SIP transfer, or list customer tags | `references/reporting.md` |
| Create, edit, or delete a customer template | `references/outbound-batches.md` |

## Answering questions about Ingfah

`references/user-guide/` is a copy of the public Thai user guide
(https://docs.ingfah.ai), one Markdown file per page: overview and services,
plans and standards, onboarding, telephony (IP Peering, SIP Registration),
every dashboard guide (AI Agent, Flow, prompting, Tools, knowledge base,
inbound and outbound, results, all calls, settings), and the release notes.

- **Find the page, then read it.** Start from `INDEX.md`, which lists every
  page with its description. For a specific term, search the folder, e.g.
  `grep -ril "say-as" references/user-guide`. Read the whole page before
  answering; steps and caveats are often in a later section or a `:::caution`.
- **Ground capability claims in the guide** and the other references in this
  skill. Give recommendations that follow from those capabilities and the
  user's goal, and label them as recommendations. Do not invent platform
  behavior, pricing, limits, delivery dates, or guaranteed business results.
  When a capability is undocumented, say so and suggest asking the Ingfah team.
- **Answer in the user's language**, in the dashboard's words. The guide is
  in Thai; for English speakers translate, and give the Thai menu name the
  first time (e.g. Knowledge — คลังความรู้) since the dashboard shows Thai.
- **Link the page.** End with the public URL from the page's `Source:` line
  so the user can see the screenshots, which are not copied here.
- **Give steps as menu paths**, e.g. ทีม AI Agent → เปิดทีม → ตั้งค่าผลลัพธ์หลังวางสาย.
- **"What's new" or "when did X ship"** — read `release-notes.md`.
- **Offer to do it.** When the answer is a task the client API can perform
  (the routes below), offer to do it for the user; when it is
  dashboard-only, say so (see "Dashboard-only tasks").

For how the platform behaves through the API — field names, state rules,
request bodies — the other `references/` files are more precise than the
guide, which describes the dashboard.

## Advising users

For "what should we use?", "how should we set this up?", or "how can we improve?",
give a recommendation and explain the tradeoff. Follow `references/consulting.md`.
Connect the goal to the agent, team, data, Tools, post-call results, and channels
that are needed. Propose a small test and say how the user can judge its result.
Ask only for missing facts that change the recommendation. Advice does not
require an API key or authorize a platform write.

## Client API

Pick the client once per session:

1. Run `ingfah --version`. If it prints `ingfah 0.1.0` or newer, use the `ingfah` CLI for every request.
2. Otherwise use `scripts/ingfah_api.py`. It needs only `python3`, so it is the client on claude.ai, Claude Desktop, and any machine without the CLI.

Both clients enforce the same route allowlist, mutation confirmation, and tool-drop guard. Do not substitute `curl`, `requests`, or an ad-hoc script, even if asked to for speed. Doing so bypasses the guardrails, and requests without a client's `User-Agent` header are rejected by Cloudflare with a 403 error-1010.

If the script prints `warning: this Python ... cannot use TLS 1.3`, tell the user once per session that their `python3` will stop reaching Ingfah when TLS 1.3 becomes required, and suggest installing the `ingfah` CLI or a Python from python.org or Homebrew. The request itself still ran.

Switch from the CLI to the script only when the CLI cannot reach the API: a connection error, or a 403 error-1010. Never switch after the CLI refuses a request (exit code 3). A refusal is a guard working, and the script would refuse it too.

### The `ingfah` CLI

`ingfah api` prints the same `{status, data, pagination}` envelope as the script. The examples in this skill use the script's flags. Translate them for the CLI:

| Script | CLI |
|---|---|
| `python3 scripts/ingfah_api.py METHOD PATH` | `ingfah api METHOD PATH` |
| `--confirm` | `--yes` |
| `--json FILE` or `--json '{...}'` | `--body @FILE` or `--body '{...}'` |
| `--query '?a=b&c=d'` | `-q a=b -q c=d` |
| `--output F` | `--out F` |
| `--allow-tool-drop` | `--allow-tool-drop` |

- **Confirm every write.** Preview it with `--dry-run`, which prints the request and sends nothing. Get the user's yes, then rerun the same command with `--yes`. Never pass `--yes` before the user confirms. Without a terminal the CLI refuses a write that lacks `--yes`, so `--yes` is your confirmation, not a convenience flag.
- **Revise and publish agents with the typed commands.** Use `ingfah agents revise SLUG` and `ingfah agents publish SLUG --revision ID` rather than raw `ingfah api` calls. `revise` copies every field from the newest revision and the tool links from the agent, then reads the new revision back. `publish` refuses a revision that is not the newest or that drops a tool, and re-reads the agent afterwards.
- **Keep the key out of the chat.** The CLI reads `INGFAH_API_KEY`, or the key stored by `ingfah auth login`. Suggest the user run `ingfah auth login` in their own terminal. It prompts for the key and keeps it in the system keyring.

## Naming: what the user calls things

The API's names and the dashboard's names differ, and most users speak in
dashboard words — often Thai. Translate their words to the API entity below,
and **answer in their words**, not the API's: say "ทีม AI Agent" or "AI Agent
Team", not "product". When a term is ambiguous, name both ("the AI Agent Team
— `product` in the API") once, then stay in their language.

| API entity | Dashboard (EN) | Dashboard (TH) |
|---|---|---|
| `product` | AI Agent Team | ทีม AI Agent |
| automation | Chat Automation | Chat Automation |
| agent | AI Agent | AI Agent |
| revision (unpublished) | Draft / Has Draft | แบบร่าง / มีแบบร่าง |
| revision (published) | Published / Currently Published | เผยแพร่ / เผยแพร่อยู่ |
| publish a revision | Publish | เผยแพร่ |
| chat session (voice) | Call — All Calls | สาย — สายทั้งหมด |
| chat session (text) | Chat — Chats | แชท |
| transcript / messages | Conversation | การสนทนา |
| outbound batch | Batch — Batch Listing | Batch — รายการ Batch |
| outbound option | Template — Manage Templates | เทมเพลตข้อมูลลูกค้า — จัดการเทมเพลต |
| plugin function | Tool | Tool |
| phone tool | Tool (Calling category) | Tool (หมวดการโทร) |
| `direction: inbound` | Inbound | สายเข้า / รับสาย |
| `direction: outbound` | Outbound | สายออก / โทรออก |
| `channel_type: audio` | Voice | เสียง |
| `channel_type: text` | Text | ข้อความ |
| `visibility` | Private / Public | ส่วนตัว / สาธารณะ |
| `starting_agent_id` | Start (starting agent) | จุดเริ่มต้น |
| SIP number | Phone Numbers | เบอร์โทรศัพท์ |
| knowledge base | Knowledge | คลังความรู้ |
| API key | API Keys | จัดการ API Keys |

Field-level dashboard names — postprocessor, agent prompt, and Tool fields, and
the batch and record status words — are in `references/dashboard-terms.md`.

## Working with the user

Most users are not developers. They know the dashboard, not the API, so the
work should end where they can see it.

### When the user reports a problem

Users describe what they see, not which setting to change. Before saying
something cannot be done, **trace what they see back to the setting that
produces it**, then consult: look at the current setting and a few example
calls, name the cause in dashboard words, propose one concrete change with
its exact text, and apply it only after they confirm. The full map and the
common complaints are in `references/troubleshooting.md`. The ones most often
missed:

| What they see | Change this, not the agent's prompt |
|---|---|
| Call title (หัวข้อสนทนา) or summary is wrong, generic, or misreads the business | the team's `summary` postprocessor `instruction`. With none, the team uses a global default that knows nothing about the business, so add one. |
| Outcome label (ผลลัพธ์) is wrong, or everything is สรุปไม่ได้ | each outcome's `prompt` (criteria) in the `disposition` postprocessor |
| A Metadata field is empty or badly formatted | that key's `description` in the `outcome_metadata` `json_schema` |
| "I changed it but nothing changed" | changes apply to new calls only; check that the revision was **published** |
| The agent reads a tool name aloud (`transfer_to_human_agent{}`), promises a transfer that never happens, or repeats its goodbye without hanging up | the agent's tool bindings (`GET /client/agents/{slug}` `phone_tools`) first; a revision posted without them unbinds every tool. Then the prompt around the tool |
| Many outbound calls unanswered or busy | `GET /client/outbound/call-data-records` for the SIP reason, then the batch schedule |

If you told the user earlier that something was not possible and a route
exists for it, correct yourself plainly.

- **Point to where the change shows up.** After a write, name the dashboard
  page the user can open to check it — e.g. "ทีม AI Agent → เปิดทีม →
  ตั้งค่าผลลัพธ์หลังวางสาย" for a postprocessor, or the **Metadata** column on
  สายทั้งหมด for extracted results.
- **Suggest a test before going live, and more than one run.** After drafting or publishing an agent,
  tell the user to open the agent, pick **แบบร่าง** or **เผยแพร่**, and use the
  arrow beside **ทดลอง** → **ตั้งค่าและทดลอง**. Test calls are free and use no
  real phone line. Choosing the job type **รับสาย** there shows every variable,
  so customer context can be filled in by hand. Their transcripts are then
  readable with `GET /client/agents/{slug}/chat-session-tests`. The agent
  varies between calls, so one test call proves little: suggest the same
  scenario two or three times, the main paths as well as the edited one, and
  the go-live checklist in `references/prompt-authoring.md` → "Testing a change".
  For an agent that will be edited more than once, also offer an automated
  test suite (`references/testing.md`).
- **Say when something is dashboard-only.** Some tasks have no client API
  route. Give the user the path in the table below instead of trying another
  endpoint.

### Before building a new agent

Collect these first, and ask for whatever is missing rather than inventing it:

- the agent's role, **gender**, personality, and tone
- the company or brand it represents
- who it will call or answer, e.g. customers who are overdue or just ordered
- what it must say on every call, e.g. a recording consent notice, the due
  date, the amount owed
- the goal — what the customer should agree to or provide
- hard rules — things it must never do or always do
- what should be recorded after the call — the outcome, a promised date, and
  so on; this becomes the disposition outcomes and outcome metadata

### Dashboard-only tasks

| Task | Where in the dashboard |
|---|---|
| Create, rename, or delete an API key | การตั้งค่า → API Keys |
| Assign a phone number to an inbound team | เบอร์โทรศัพท์ → ⋮ → แก้ไข → ทีมรับสายเข้า |
| Upload knowledge files | คลังความรู้ → อัปโหลด; attach in the agent → แก้ไขแบบร่าง → คลังความรู้ icon → บันทึกแบบร่าง |
| Copy a customer template (create, edit, and delete work through the API) | สายออก → จัดการเทมเพลต |
| Upload a batch from a CSV file | สายออก → สร้าง Batch |
| Make a test call or chat | the agent → ทดลอง → ตั้งค่าและทดลอง |
| Add a cloned voice | a service requested from the Ingfah team |
| Data retention, billing, activity logs, guest access | การตั้งค่า — **Owner** only |
| Add or edit a text channel (LINE, Facebook, …) | การตั้งค่า → Channels — **Owner** only |
| Mute the bot, reply as a human, or reassign a chat | แชท |

Knowledge files must be `.pdf`, `.docx`, `.txt`, or `.md`, and must reach
**พร้อมใช้งาน** before they are attached; FAQ files work best as `.md` or
`.txt` written per `references/faq-authoring.md`. A batch CSV must be at most 25 MB,
with column names matching its template.

A missing phone number on เบอร์โทรศัพท์ or on batch creation means no line is
connected yet: the user connects their own telephony or asks the Ingfah team
for a number, which is billed separately.

## Authentication

- Send the key only in the `X-Api-Key` request header.
- If no key is available, ask the user to provide their Ingfah client API key.
  If they have none, tell them to create one at **การตั้งค่า → API Keys →
  สร้าง API Key** on https://ingfah.ai/login. The key is shown **once** only; a
  lost key cannot be recovered, so they create a new one and delete the old.
  A new key has the full access of its account.
- Never echo, log, save, commit, or include the key in generated files, URLs, or error messages.
- Do not ask the user to put the key in this repository.
- Treat the key as available only for the current task unless the user explicitly requests persistent configuration.
- Use HTTPS and the configured Ingfah API base URL.
- Before making a request, explain when the requested operation requires a write scope.
- Ask for explicit confirmation immediately before creating, deleting, pausing, resuming, or cancelling anything, and before turning the AI on or off in a customer's conversation.
- Redact secrets from all displayed request and response details.

The script reads `INGFAH_API_KEY` from the process environment. When the user provides a key conversationally, pass it to the script only for the current process; never write it to a file or include it in a command shown to the user.

Examples:

```bash
python3 scripts/ingfah_api.py GET /client/products
python3 scripts/ingfah_api.py GET /client/outbound/batches/7/records --query '?per_page=20&status=called'
python3 scripts/ingfah_api.py --confirm POST /client/outbound/batches --json request.json
python3 scripts/ingfah_api.py --confirm POST /client/outbound/batches/7/pause
python3 scripts/ingfah_api.py GET /client/chat-sessions/{uuid}/record/download --output call.ogg
```

`--json` accepts either a path to a JSON file or an inline JSON document. `--output` saves the response body to a new file instead of printing it; binary responses are refused without it. Run the script from the skill directory, or give its absolute path.

## Client API-key scopes and routes

### `client_products:read`

- `GET /client/ai-agent-teams`
- `GET /client/disposition-outcomes`
- `GET /client/ai-agent-teams/{id}/customer-context-variables`
- `GET /client/products`
- `GET /client/products/{id}`
- `GET /client/products/{id}/automations`
- `GET /client/products/{id}/automations/catalog`
- `GET /client/automations/trigger-variables`
- `GET /client/text-channel-configs`
- `GET /client/text-channel-configs/{id}`
- `GET /client/text-channel-config-providers`
- `GET /client/products/{id}/tts-dictionaries`

### `client_products:write`

- `POST /client/products`
- `POST /client/products/{id}/automations`
- `PUT /client/products/{id}/automations/{automationId}`
- `DELETE /client/products/{id}/automations/{automationId}`
- `PUT /client/products/{id}`
- `PUT /client/products/{id}/visibility`
- `DELETE /client/products/{id}`
- `POST /client/products/{id}/postprocessors`
- `PUT /client/products/{id}/postprocessors/{postprocessorId}`
- `DELETE /client/products/{id}/postprocessors/{postprocessorId}`
- `POST /client/products/{id}/tts-dictionaries`
- `PUT /client/products/{id}/tts-dictionaries`
- `DELETE /client/products/{id}/tts-dictionaries/{ttsDictionaryId}`

### `ai_agents:read`

- `GET /client/ai-agents`
- `GET /client/ai-agents/browse`
- `GET /client/ai-agent-folders`
- `GET /client/agent-templates`
- `GET /client/agents/{slug}`
- `GET /client/agents/{slug}/revisions`
- `GET /client/agents/{slug}/revisions/{id}`
- `GET /client/phone-tools`
- `GET /client/phone-tools/catalog`
- `GET /client/phone-tools/{id}`
- `GET /client/text-chat-tools`
- `GET /client/plugin-functions`
- `GET /client/plugin-functions/{id}`
- `GET /client/plugin-function-integrations`
- `GET /client/voices`

### `ai_agents:write`

- `POST /client/agents`
- `DELETE /client/agents/{slug}`
- `PUT /client/agents/{slug}/profile`
- `PUT /client/agents/{slug}/description`
- `PUT /client/agents/{slug}/visibility`
- `PUT /client/agents/{slug}/folder`
- `POST /client/ai-agent-folders`
- `PUT /client/ai-agent-folders/{id}`
- `PUT /client/ai-agent-folders/{id}/parent`
- `DELETE /client/ai-agent-folders/{id}`
- `POST /client/agents/{slug}/revisions`
- `POST /client/agents/{slug}/revisions/{id}/publish`
- `POST /client/agents/{slug}/publish` (publishes the newest revision; prefer the route above, which fails if someone drafted after you)
- `DELETE /client/agents/{slug}/revisions/{id}`
- `POST /client/phone-tools`
- `PATCH /client/phone-tools/{id}`
- `DELETE /client/phone-tools/{id}`
- `POST /client/plugin-functions`
- `PUT /client/plugin-functions/{id}`
- `DELETE /client/plugin-functions/{id}`
- `POST /client/plugin-functions/{id}/duplicate`
- `POST /client/plugin-functions/{id}/test-run`
- `POST /client/plugin-functions/test-code`

### `chat_sessions:read`

- `GET /client/chat-sessions`
- `GET /client/chat-sessions/{uuid}`
- `GET /client/chat-sessions/{uuid}/record`
- `GET /client/chat-sessions/{uuid}/record/download`
- `GET /client/chat-sessions/{uuid}/record/checksum`
- `GET /client/chat-sessions-list`
- `GET /client/chat-sessions-list/csv`
- `GET /client/agents/{slug}/chat-session-tests`
- `GET /client/agents/{slug}/chat-session-tests/{uuid}`
- `GET /client/products/{id}/chat-session-tests`
- `GET /client/products/{id}/chat-session-tests/{uuid}`
- `GET /client/text-chats/conversations`
- `GET /client/text-chats/tags`
- `GET /client/text-chats/conversations/{uuid}`
- `GET /client/text-chats/chat-sessions-list`
- `GET /client/text-chats/chat-sessions-list/csv`

### `analytics:read`

- `GET /client/analytics/summary`
- `GET /client/analytics/short-calls`
- `GET /client/analytics/hourly-charts`
- `GET /client/analytics/duration-histogram`
- `GET /client/analytics/heatmap`
- `GET /client/analytics/speech-ratio`
- `GET /client/analytics/report/download` (XLSX; use `--output`)
- `GET /client/text-analytics/summary`
- `GET /client/text-analytics/messages-hourly`
- `GET /client/text-analytics/heatmap`

### `text_chat_conversations:write`

- `PUT /client/chat-conversations/{uuid}` (body `{"bot_enabled": bool}` only)
- `PUT /client/text-chats/{provider_type}/channels/{channel_identifier}/conversations/{provider_conversation_id}` (same switch, named by the provider's ids)

### `client_outbound_options:read`

- `GET /client/outbound/options`
- `GET /client/outbound/options/{id}`

### `client_outbound_options:write`

- `POST /client/outbound/options`
- `PUT /client/outbound/options/{id}`
- `DELETE /client/outbound/options/{id}`

### `client_outbound_batches:read`

- `GET /client/outbound/batches`
- `GET /client/outbound/batches/{id}`
- `GET /client/outbound/batches/{id}/records`
- `GET /client/outbound/batches/{id}/records-summary`
- `GET /client/outbound/batches/{id}/records/download`
- `GET /client/outbound/call-data-records`

### `client_outbound_batches:write`

- `POST /client/outbound/batches`
- `PATCH /client/outbound/batches/{id}/records/{recordId}`
- `POST /client/outbound/batches/{id}/pause`
- `POST /client/outbound/batches/{id}/resume`
- `POST /client/outbound/batches/{id}/cancel`

### `tts_dictionaries:read`

- `GET /client/tts-dictionaries`
- `GET /client/tts-dictionaries/{id}`
- `GET /client/tts-dictionaries/{id}/csv`
- `GET /client/tts-dictionaries/{id}/words`

### `tts_dictionaries:write`

- `POST /client/tts-dictionaries`
- `PUT /client/tts-dictionaries/{id}`
- `DELETE /client/tts-dictionaries/{id}`
- `POST /client/tts-dictionaries/{id}/csv`
- `POST /client/tts-dictionaries/{id}/words`
- `PUT /client/tts-dictionaries/{id}/words/{wordId}`
- `DELETE /client/tts-dictionaries/{id}/words/{wordId}`

### `secrets:write`

- `GET /client/secrets` (list; scope name is write)
- `POST /client/secrets`
- `PUT /client/secrets/{id}`
- `DELETE /client/secrets/{id}`

### `share_links:read`

- `GET /client/share-links`
- `GET /client/share-links/{id}/views`

### `share_links:write`

- `POST /client/share-links`
- `DELETE /client/share-links/{id}`

### `crm_client_users:read`

- `GET /crm/user`
- `GET /crm/users`
- `GET /crm/users/{id}`

### `crm_client_users:write`

- `POST /crm/user`
- `PATCH /crm/user`
- `PATCH /crm/users/{id}`

### `inbound_admission:read`

- `GET /client/calls/inbound-admission` checks whether the account can accept
  one more inbound call. A 200 response can contain `allow: false`; inspect
  the body before recommending a transfer. See `references/reporting.md`.

## Scope handling

Before calling an endpoint, identify its required scope and check the user's intended action against that scope. If the API returns an authorization or insufficient-scope error, explain the missing scope without exposing the API key.

The automation routes are live but absent from the OpenAPI spec; see
`references/automations.md`. Do not call backoffice routes, API-key management routes, or client routes not listed in this file. Do not infer that a JWT-only route is available to an API-key caller. Never call `POST /v1/synthesize` through this skill: it uses `speechBearer`, not a client API key, and is hard-denied in `scripts/ingfah_api.py`.

## Rules that apply in every area

The reference files hold the detail; these are the rules not to miss even
without opening one.

- **Real-world effects need a preview and explicit confirmation immediately
  before sending.** Creating a batch places real calls. Publishing a revision
  changes a live agent. Test-running a Tool sends its real request. An
  automation sends customer data to a third party on every matching call.
- **Read before writing.** Revisions, Tool updates, postprocessor updates, and
  team `transferabilities` replace what they are given rather than patching it.
  Read the current state, change only the fields being edited, and send the
  whole body.
- **Never publish a revision that unbinds tools.** A revision stores only the
  tool ids it is sent (`phone_tools`, `ai_plugin_function_ids`), and the
  revision read does not return them. Copy them from `GET /client/agents/{slug}`
  into every revision body, list them in the preview, and re-read the agent
  after publishing. The script refuses a revision that would drop a bound
  tool; `--allow-tool-drop` is only for removing a tool on purpose. Getting
  this wrong leaves an agent that reads out
  `transfer_to_human_agent{}` instead of transferring, and cannot hang up.
- **Verify after writing.** Read the object back and report what was actually
  stored, not what the write response implied. `POST /client/agents` in
  particular drops the prompt fields sent with it. For a revision, compare the
  agent's `phone_tools` and `ai_plugin_functions` too, not only the prompt.
- **Report state rules as state rules.** A `403` on visibility means the key's
  admin did not create the object; a `409` or `422` on delete means something
  still uses it. Neither is an authentication failure.
- **Postprocessor and automation changes apply to new calls only.** Calls that
  already ended are not reprocessed.
- **Redact.** Never show API keys, webhook auth headers, or `hmac_secret`.
  Treat outcome metadata and transcripts as personal data.

## Response handling

Return concise, structured summaries. Preserve identifiers, statuses, timestamps, and relevant error details, but remove credentials and unrelated personal or sensitive data. For downloads, save or present the result only when the user explicitly requests it.

### Call recordings

A voice call's recording is read three ways, all under `chat_sessions:read`:

- `GET /client/chat-sessions/{uuid}/record` returns a link to the audio,
  valid for 15 minutes, with its SHA-256 checksum. Anyone holding the link can
  play the call until it expires, so treat it like personal data: do not paste
  it into shared places, and give it only to the user who asked.
- `GET /client/chat-sessions/{uuid}/record/download` returns the Ogg file
  itself. Save it with `--output` only when the user asks for the file.
- `GET /client/chat-sessions/{uuid}/record/checksum` returns only the
  checksum, for checking a download.

Opening a recording through the link or the download route is written to the
account's activity log under the API key. A `404` with `no audio recording
available` means no recording is stored for that session, as with any
text chat.

Recordings, transcripts, and batch data are deleted automatically once they
pass the account's data-retention period, set by an Owner under การตั้งค่า →
การเก็บรักษาข้อมูล. When an old call has no recording or transcript, mention
retention as a likely reason rather than reporting a fault.

