Ingfah
This skill answers questions, advises users on their setup, and carries out
supported tasks:
- Answers questions about Ingfah from the bundled user guide — see
"Answering questions about Ingfah" below. No API key needed.
- Writes FAQ files for the knowledge base (คลังความรู้) — read
references/faq-authoring.md first. No API key needed.
- Calls the Ingfah client API with the user's client API key, using only
the routes listed below.
- 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:
- Run
ingfah --version. If it prints ingfah 0.1.0 or newer, use the ingfah CLI for every request.
- 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:
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.
1---2name: ingfah3description: "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 / ผลลัพธ์หลังวางสาย. Do not use backoffice APIs or JWT-only client APIs."4metadata:5 source: https://skillmd.com/skills/100x-fi/ingfah6---78# Ingfah910This skill answers questions, advises users on their setup, and carries out11supported tasks:12131. **Answers questions about Ingfah** from the bundled user guide — see14 "Answering questions about Ingfah" below. No API key needed.152. **Writes FAQ files for the knowledge base** (คลังความรู้) — read16 `references/faq-authoring.md` first. No API key needed.173. **Calls the Ingfah client API** with the user's client API key, using only18 the routes listed below.194. **Recommends a practical setup or improvement** for the user's business20 goal. Read `references/consulting.md` for discovery, tradeoffs, pilot plans,21 and worked examples. No API key is needed for advice.2223The default Ingfah API base URL is `https://api.ingfah.ai`. Use another base URL only when the user explicitly provides one.2425This file holds the rules that apply to every task. The detail for each area26is in `references/`; **read the matching file before working in that area**:2728| Task | Read first |29|---|---|30| Recommend a setup, assess suitability, plan a pilot, or improve business results | `references/consulting.md`, then the matching technical reference and user-guide page |31| Answer a question about Ingfah or how to use the dashboard | `references/user-guide/INDEX.md`, then the matching page |32| Write, convert, or update an FAQ or knowledge file | `references/faq-authoring.md` |33| 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 |34| 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 |35| 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 |36| Create, pause, resume, or cancel an outbound batch | `references/outbound-batches.md` |37| Read, write, or test-run a Tool | `references/tools.md` |38| A voice agent should transfer a call to a person, or the client asks how transfers work | `references/voice-handoff.md` |39| 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` |40| Design disposition outcomes or an outcome metadata schema | `references/outcome-design.md` |41| 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 |42| Create or edit a postprocessor | `references/postprocessors.md` |43| Set up a Chat Automation (webhook, do-not-contact) | `references/automations.md` |44| Translate a field name the user reads in the dashboard | `references/dashboard-terms.md` |45| The user complains about something they see (a wrong summary, label, answer, or voice; missed calls) | `references/troubleshooting.md` |46| Analytics, text chat inbox, channels, or why outbound calls failed | `references/reporting.md` |47| Check capacity before an inbound SIP transfer, or list customer tags | `references/reporting.md` |48| Create, edit, or delete a customer template | `references/outbound-batches.md` |4950## Answering questions about Ingfah5152`references/user-guide/` is a copy of the public Thai user guide53(https://docs.ingfah.ai), one Markdown file per page: overview and services,54plans and standards, onboarding, telephony (IP Peering, SIP Registration),55every dashboard guide (AI Agent, Flow, prompting, Tools, knowledge base,56inbound and outbound, results, all calls, settings), and the release notes.5758- **Find the page, then read it.** Start from `INDEX.md`, which lists every59 page with its description. For a specific term, search the folder, e.g.60 `grep -ril "say-as" references/user-guide`. Read the whole page before61 answering; steps and caveats are often in a later section or a `:::caution`.62- **Ground capability claims in the guide** and the other references in this63 skill. Give recommendations that follow from those capabilities and the64 user's goal, and label them as recommendations. Do not invent platform65 behavior, pricing, limits, delivery dates, or guaranteed business results.66 When a capability is undocumented, say so and suggest asking the Ingfah team.67- **Answer in the user's language**, in the dashboard's words. The guide is68 in Thai; for English speakers translate, and give the Thai menu name the69 first time (e.g. Knowledge — คลังความรู้) since the dashboard shows Thai.70- **Link the page.** End with the public URL from the page's `Source:` line71 so the user can see the screenshots, which are not copied here.72- **Give steps as menu paths**, e.g. ทีม AI Agent → เปิดทีม → ตั้งค่าผลลัพธ์หลังวางสาย.73- **"What's new" or "when did X ship"** — read `release-notes.md`.74- **Offer to do it.** When the answer is a task the client API can perform75 (the routes below), offer to do it for the user; when it is76 dashboard-only, say so (see "Dashboard-only tasks").7778For how the platform behaves through the API — field names, state rules,79request bodies — the other `references/` files are more precise than the80guide, which describes the dashboard.8182## Advising users8384For "what should we use?", "how should we set this up?", or "how can we improve?",85give a recommendation and explain the tradeoff. Follow `references/consulting.md`.86Connect the goal to the agent, team, data, Tools, post-call results, and channels87that are needed. Propose a small test and say how the user can judge its result.88Ask only for missing facts that change the recommendation. Advice does not89require an API key or authorize a platform write.9091## Client API9293Pick the client once per session:94951. Run `ingfah --version`. If it prints `ingfah 0.1.0` or newer, use the `ingfah` CLI for every request.962. 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.9798Both 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.99100If 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.101102Switch 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.103104### The `ingfah` CLI105106`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:107108| Script | CLI |109|---|---|110| `python3 scripts/ingfah_api.py METHOD PATH` | `ingfah api METHOD PATH` |111| `--confirm` | `--yes` |112| `--json FILE` or `--json '{...}'` | `--body @FILE` or `--body '{...}'` |113| `--query '?a=b&c=d'` | `-q a=b -q c=d` |114| `--output F` | `--out F` |115| `--allow-tool-drop` | `--allow-tool-drop` |116117- **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.118- **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.119- **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.120121## Naming: what the user calls things122123The API's names and the dashboard's names differ, and most users speak in124dashboard words — often Thai. Translate their words to the API entity below,125and **answer in their words**, not the API's: say "ทีม AI Agent" or "AI Agent126Team", not "product". When a term is ambiguous, name both ("the AI Agent Team127— `product` in the API") once, then stay in their language.128129| API entity | Dashboard (EN) | Dashboard (TH) |130|---|---|---|131| `product` | AI Agent Team | ทีม AI Agent |132| automation | Chat Automation | Chat Automation |133| agent | AI Agent | AI Agent |134| revision (unpublished) | Draft / Has Draft | แบบร่าง / มีแบบร่าง |135| revision (published) | Published / Currently Published | เผยแพร่ / เผยแพร่อยู่ |136| publish a revision | Publish | เผยแพร่ |137| chat session (voice) | Call — All Calls | สาย — สายทั้งหมด |138| chat session (text) | Chat — Chats | แชท |139| transcript / messages | Conversation | การสนทนา |140| outbound batch | Batch — Batch Listing | Batch — รายการ Batch |141| outbound option | Template — Manage Templates | เทมเพลตข้อมูลลูกค้า — จัดการเทมเพลต |142| plugin function | Tool | Tool |143| phone tool | Tool (Calling category) | Tool (หมวดการโทร) |144| `direction: inbound` | Inbound | สายเข้า / รับสาย |145| `direction: outbound` | Outbound | สายออก / โทรออก |146| `channel_type: audio` | Voice | เสียง |147| `channel_type: text` | Text | ข้อความ |148| `visibility` | Private / Public | ส่วนตัว / สาธารณะ |149| `starting_agent_id` | Start (starting agent) | จุดเริ่มต้น |150| SIP number | Phone Numbers | เบอร์โทรศัพท์ |151| knowledge base | Knowledge | คลังความรู้ |152| API key | API Keys | จัดการ API Keys |153154Field-level dashboard names — postprocessor, agent prompt, and Tool fields, and155the batch and record status words — are in `references/dashboard-terms.md`.156157## Working with the user158159Most users are not developers. They know the dashboard, not the API, so the160work should end where they can see it.161162### When the user reports a problem163164Users describe what they see, not which setting to change. Before saying165something cannot be done, **trace what they see back to the setting that166produces it**, then consult: look at the current setting and a few example167calls, name the cause in dashboard words, propose one concrete change with168its exact text, and apply it only after they confirm. The full map and the169common complaints are in `references/troubleshooting.md`. The ones most often170missed:171172| What they see | Change this, not the agent's prompt |173|---|---|174| 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. |175| Outcome label (ผลลัพธ์) is wrong, or everything is สรุปไม่ได้ | each outcome's `prompt` (criteria) in the `disposition` postprocessor |176| A Metadata field is empty or badly formatted | that key's `description` in the `outcome_metadata` `json_schema` |177| "I changed it but nothing changed" | changes apply to new calls only; check that the revision was **published** |178| 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 |179| Many outbound calls unanswered or busy | `GET /client/outbound/call-data-records` for the SIP reason, then the batch schedule |180181If you told the user earlier that something was not possible and a route182exists for it, correct yourself plainly.183184- **Point to where the change shows up.** After a write, name the dashboard185 page the user can open to check it — e.g. "ทีม AI Agent → เปิดทีม →186 ตั้งค่าผลลัพธ์หลังวางสาย" for a postprocessor, or the **Metadata** column on187 สายทั้งหมด for extracted results.188- **Suggest a test before going live, and more than one run.** After drafting or publishing an agent,189 tell the user to open the agent, pick **แบบร่าง** or **เผยแพร่**, and use the190 arrow beside **ทดลอง** → **ตั้งค่าและทดลอง**. Test calls are free and use no191 real phone line. Choosing the job type **รับสาย** there shows every variable,192 so customer context can be filled in by hand. Their transcripts are then193 readable with `GET /client/agents/{slug}/chat-session-tests`. The agent194 varies between calls, so one test call proves little: suggest the same195 scenario two or three times, the main paths as well as the edited one, and196 the go-live checklist in `references/prompt-authoring.md` → "Testing a change".197 For an agent that will be edited more than once, also offer an automated198 test suite (`references/testing.md`).199- **Say when something is dashboard-only.** Some tasks have no client API200 route. Give the user the path in the table below instead of trying another201 endpoint.202203### Before building a new agent204205Collect these first, and ask for whatever is missing rather than inventing it:206207- the agent's role, **gender**, personality, and tone208- the company or brand it represents209- who it will call or answer, e.g. customers who are overdue or just ordered210- what it must say on every call, e.g. a recording consent notice, the due211 date, the amount owed212- the goal — what the customer should agree to or provide213- hard rules — things it must never do or always do214- what should be recorded after the call — the outcome, a promised date, and215 so on; this becomes the disposition outcomes and outcome metadata216217### Dashboard-only tasks218219| Task | Where in the dashboard |220|---|---|221| Create, rename, or delete an API key | การตั้งค่า → API Keys |222| Assign a phone number to an inbound team | เบอร์โทรศัพท์ → ⋮ → แก้ไข → ทีมรับสายเข้า |223| Upload knowledge files | คลังความรู้ → อัปโหลด; attach in the agent → แก้ไขแบบร่าง → คลังความรู้ icon → บันทึกแบบร่าง |224| Copy a customer template (create, edit, and delete work through the API) | สายออก → จัดการเทมเพลต |225| Upload a batch from a CSV file | สายออก → สร้าง Batch |226| Make a test call or chat | the agent → ทดลอง → ตั้งค่าและทดลอง |227| Add a cloned voice | a service requested from the Ingfah team |228| Data retention, billing, activity logs, guest access | การตั้งค่า — **Owner** only |229| Add or edit a text channel (LINE, Facebook, …) | การตั้งค่า → Channels — **Owner** only |230| Mute the bot, reply as a human, or reassign a chat | แชท |231232Knowledge files must be `.pdf`, `.docx`, `.txt`, or `.md`, and must reach233**พร้อมใช้งาน** before they are attached; FAQ files work best as `.md` or234`.txt` written per `references/faq-authoring.md`. A batch CSV must be at most 25 MB,235with column names matching its template.236237A missing phone number on เบอร์โทรศัพท์ or on batch creation means no line is238connected yet: the user connects their own telephony or asks the Ingfah team239for a number, which is billed separately.240241## Authentication242243- Send the key only in the `X-Api-Key` request header.244- If no key is available, ask the user to provide their Ingfah client API key.245 If they have none, tell them to create one at **การตั้งค่า → API Keys →246 สร้าง API Key** on https://ingfah.ai/login. The key is shown **once** only; a247 lost key cannot be recovered, so they create a new one and delete the old.248 A new key has the full access of its account.249- Never echo, log, save, commit, or include the key in generated files, URLs, or error messages.250- Do not ask the user to put the key in this repository.251- Treat the key as available only for the current task unless the user explicitly requests persistent configuration.252- Use HTTPS and the configured Ingfah API base URL.253- Before making a request, explain when the requested operation requires a write scope.254- 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.255- Redact secrets from all displayed request and response details.256257The 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.258259Examples:260261```bash262python3 scripts/ingfah_api.py GET /client/products263python3 scripts/ingfah_api.py GET /client/outbound/batches/7/records --query '?per_page=20&status=called'264python3 scripts/ingfah_api.py --confirm POST /client/outbound/batches --json request.json265python3 scripts/ingfah_api.py --confirm POST /client/outbound/batches/7/pause266python3 scripts/ingfah_api.py GET /client/chat-sessions/{uuid}/record/download --output call.ogg267```268269`--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.270271## Client API-key scopes and routes272273### `client_products:read`274275- `GET /client/ai-agent-teams`276- `GET /client/disposition-outcomes`277- `GET /client/ai-agent-teams/{id}/customer-context-variables`278- `GET /client/products`279- `GET /client/products/{id}`280- `GET /client/products/{id}/automations`281- `GET /client/products/{id}/automations/catalog`282- `GET /client/automations/trigger-variables`283- `GET /client/text-channel-configs`284- `GET /client/text-channel-configs/{id}`285- `GET /client/text-channel-config-providers`286- `GET /client/products/{id}/tts-dictionaries`287288### `client_products:write`289290- `POST /client/products`291- `POST /client/products/{id}/automations`292- `PUT /client/products/{id}/automations/{automationId}`293- `DELETE /client/products/{id}/automations/{automationId}`294- `PUT /client/products/{id}`295- `PUT /client/products/{id}/visibility`296- `DELETE /client/products/{id}`297- `POST /client/products/{id}/postprocessors`298- `PUT /client/products/{id}/postprocessors/{postprocessorId}`299- `DELETE /client/products/{id}/postprocessors/{postprocessorId}`300- `POST /client/products/{id}/tts-dictionaries`301- `PUT /client/products/{id}/tts-dictionaries`302- `DELETE /client/products/{id}/tts-dictionaries/{ttsDictionaryId}`303304### `ai_agents:read`305306- `GET /client/ai-agents`307- `GET /client/ai-agents/browse`308- `GET /client/ai-agent-folders`309- `GET /client/agent-templates`310- `GET /client/agents/{slug}`311- `GET /client/agents/{slug}/revisions`312- `GET /client/agents/{slug}/revisions/{id}`313- `GET /client/phone-tools`314- `GET /client/phone-tools/catalog`315- `GET /client/phone-tools/{id}`316- `GET /client/text-chat-tools`317- `GET /client/plugin-functions`318- `GET /client/plugin-functions/{id}`319- `GET /client/plugin-function-integrations`320- `GET /client/voices`321322### `ai_agents:write`323324- `POST /client/agents`325- `DELETE /client/agents/{slug}`326- `PUT /client/agents/{slug}/profile`327- `PUT /client/agents/{slug}/description`328- `PUT /client/agents/{slug}/visibility`329- `PUT /client/agents/{slug}/folder`330- `POST /client/ai-agent-folders`331- `PUT /client/ai-agent-folders/{id}`332- `PUT /client/ai-agent-folders/{id}/parent`333- `DELETE /client/ai-agent-folders/{id}`334- `POST /client/agents/{slug}/revisions`335- `POST /client/agents/{slug}/revisions/{id}/publish`336- `POST /client/agents/{slug}/publish` (publishes the newest revision; prefer the route above, which fails if someone drafted after you)337- `DELETE /client/agents/{slug}/revisions/{id}`338- `POST /client/phone-tools`339- `PATCH /client/phone-tools/{id}`340- `DELETE /client/phone-tools/{id}`341- `POST /client/plugin-functions`342- `PUT /client/plugin-functions/{id}`343- `DELETE /client/plugin-functions/{id}`344- `POST /client/plugin-functions/{id}/duplicate`345- `POST /client/plugin-functions/{id}/test-run`346- `POST /client/plugin-functions/test-code`347348### `chat_sessions:read`349350- `GET /client/chat-sessions`351- `GET /client/chat-sessions/{uuid}`352- `GET /client/chat-sessions/{uuid}/record`353- `GET /client/chat-sessions/{uuid}/record/download`354- `GET /client/chat-sessions/{uuid}/record/checksum`355- `GET /client/chat-sessions-list`356- `GET /client/chat-sessions-list/csv`357- `GET /client/agents/{slug}/chat-session-tests`358- `GET /client/agents/{slug}/chat-session-tests/{uuid}`359- `GET /client/products/{id}/chat-session-tests`360- `GET /client/products/{id}/chat-session-tests/{uuid}`361- `GET /client/text-chats/conversations`362- `GET /client/text-chats/tags`363- `GET /client/text-chats/conversations/{uuid}`364- `GET /client/text-chats/chat-sessions-list`365- `GET /client/text-chats/chat-sessions-list/csv`366367### `analytics:read`368369- `GET /client/analytics/summary`370- `GET /client/analytics/short-calls`371- `GET /client/analytics/hourly-charts`372- `GET /client/analytics/duration-histogram`373- `GET /client/analytics/heatmap`374- `GET /client/analytics/speech-ratio`375- `GET /client/analytics/report/download` (XLSX; use `--output`)376- `GET /client/text-analytics/summary`377- `GET /client/text-analytics/messages-hourly`378- `GET /client/text-analytics/heatmap`379380### `text_chat_conversations:write`381382- `PUT /client/chat-conversations/{uuid}` (body `{"bot_enabled": bool}` only)383- `PUT /client/text-chats/{provider_type}/channels/{channel_identifier}/conversations/{provider_conversation_id}` (same switch, named by the provider's ids)384385### `client_outbound_options:read`386387- `GET /client/outbound/options`388- `GET /client/outbound/options/{id}`389390### `client_outbound_options:write`391392- `POST /client/outbound/options`393- `PUT /client/outbound/options/{id}`394- `DELETE /client/outbound/options/{id}`395396### `client_outbound_batches:read`397398- `GET /client/outbound/batches`399- `GET /client/outbound/batches/{id}`400- `GET /client/outbound/batches/{id}/records`401- `GET /client/outbound/batches/{id}/records-summary`402- `GET /client/outbound/batches/{id}/records/download`403- `GET /client/outbound/call-data-records`404405### `client_outbound_batches:write`406407- `POST /client/outbound/batches`408- `PATCH /client/outbound/batches/{id}/records/{recordId}`409- `POST /client/outbound/batches/{id}/pause`410- `POST /client/outbound/batches/{id}/resume`411- `POST /client/outbound/batches/{id}/cancel`412413### `tts_dictionaries:read`414415- `GET /client/tts-dictionaries`416- `GET /client/tts-dictionaries/{id}`417- `GET /client/tts-dictionaries/{id}/csv`418- `GET /client/tts-dictionaries/{id}/words`419420### `tts_dictionaries:write`421422- `POST /client/tts-dictionaries`423- `PUT /client/tts-dictionaries/{id}`424- `DELETE /client/tts-dictionaries/{id}`425- `POST /client/tts-dictionaries/{id}/csv`426- `POST /client/tts-dictionaries/{id}/words`427- `PUT /client/tts-dictionaries/{id}/words/{wordId}`428- `DELETE /client/tts-dictionaries/{id}/words/{wordId}`429430### `secrets:write`431432- `GET /client/secrets` (list; scope name is write)433- `POST /client/secrets`434- `PUT /client/secrets/{id}`435- `DELETE /client/secrets/{id}`436437### `share_links:read`438439- `GET /client/share-links`440- `GET /client/share-links/{id}/views`441442### `share_links:write`443444- `POST /client/share-links`445- `DELETE /client/share-links/{id}`446447### `crm_client_users:read`448449- `GET /crm/user`450- `GET /crm/users`451- `GET /crm/users/{id}`452453### `crm_client_users:write`454455- `POST /crm/user`456- `PATCH /crm/user`457- `PATCH /crm/users/{id}`458459### `inbound_admission:read`460461- `GET /client/calls/inbound-admission` checks whether the account can accept462 one more inbound call. A 200 response can contain `allow: false`; inspect463 the body before recommending a transfer. See `references/reporting.md`.464465## Scope handling466467Before 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.468469The automation routes are live but absent from the OpenAPI spec; see470`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`.471472## Rules that apply in every area473474The reference files hold the detail; these are the rules not to miss even475without opening one.476477- **Real-world effects need a preview and explicit confirmation immediately478 before sending.** Creating a batch places real calls. Publishing a revision479 changes a live agent. Test-running a Tool sends its real request. An480 automation sends customer data to a third party on every matching call.481- **Read before writing.** Revisions, Tool updates, postprocessor updates, and482 team `transferabilities` replace what they are given rather than patching it.483 Read the current state, change only the fields being edited, and send the484 whole body.485- **Never publish a revision that unbinds tools.** A revision stores only the486 tool ids it is sent (`phone_tools`, `ai_plugin_function_ids`), and the487 revision read does not return them. Copy them from `GET /client/agents/{slug}`488 into every revision body, list them in the preview, and re-read the agent489 after publishing. The script refuses a revision that would drop a bound490 tool; `--allow-tool-drop` is only for removing a tool on purpose. Getting491 this wrong leaves an agent that reads out492 `transfer_to_human_agent{}` instead of transferring, and cannot hang up.493- **Verify after writing.** Read the object back and report what was actually494 stored, not what the write response implied. `POST /client/agents` in495 particular drops the prompt fields sent with it. For a revision, compare the496 agent's `phone_tools` and `ai_plugin_functions` too, not only the prompt.497- **Report state rules as state rules.** A `403` on visibility means the key's498 admin did not create the object; a `409` or `422` on delete means something499 still uses it. Neither is an authentication failure.500- **Postprocessor and automation changes apply to new calls only.** Calls that501 already ended are not reprocessed.502- **Redact.** Never show API keys, webhook auth headers, or `hmac_secret`.503 Treat outcome metadata and transcripts as personal data.504505## Response handling506507Return 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.508509### Call recordings510511A voice call's recording is read three ways, all under `chat_sessions:read`:512513- `GET /client/chat-sessions/{uuid}/record` returns a link to the audio,514 valid for 15 minutes, with its SHA-256 checksum. Anyone holding the link can515 play the call until it expires, so treat it like personal data: do not paste516 it into shared places, and give it only to the user who asked.517- `GET /client/chat-sessions/{uuid}/record/download` returns the Ogg file518 itself. Save it with `--output` only when the user asks for the file.519- `GET /client/chat-sessions/{uuid}/record/checksum` returns only the520 checksum, for checking a download.521522Opening a recording through the link or the download route is written to the523account's activity log under the API key. A `404` with `no audio recording524available` means no recording is stored for that session, as with any525text chat.526527Recordings, transcripts, and batch data are deleted automatically once they528pass the account's data-retention period, set by an Owner under การตั้งค่า →529การเก็บรักษาข้อมูล. When an old call has no recording or transcript, mention530retention as a likely reason rather than reporting a fault.