# FAQs

> Create question/answer lists with `POST /v1/faqs`, attach them via `faqs`, and let the agent answer verbatim through `get_faq_answers`.

An FAQ is a named list of question-and-answer pairs you wrote. Attach it to an agent or an
[agent task](https://docs.talqing.com/tasks/overview.md) with `config.faqs`: the questions go into the prompt, and the
agent fetches the written answer when one is asked. Use it for stable facts asked often —
hours, refund policy, delivery areas. Behaviour belongs in the [prompt](https://docs.talqing.com/agents/prompting.md);
per-caller data belongs in a [tool](https://docs.talqing.com/tools/overview.md). There is no document upload or
retrieval over files.

## Create an FAQ

Dashboard: **Build → FAQs → New FAQ**. API:

```bash cURL
curl -X POST https://api.talqing.com/v1/faqs \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Store FAQ",
    "entries": [
      { "question": "What are your opening hours?", "answer": "We are open nine to six, Monday to Saturday." },
      { "question": "Do you deliver on Sundays?", "answer": "No. Orders placed on Saturday go out on Monday." }
    ]
  }'
```

```typescript TypeScript
const faq = await talqing.faqs.create({
  faqDefinition: {
    name: "Store FAQ",
    entries: [
      { question: "What are your opening hours?", answer: "We are open nine to six, Monday to Saturday." },
      { question: "Do you deliver on Sundays?", answer: "No. Orders placed on Saturday go out on Monday." },
    ],
  },
});
```

```python Python
faq = talqing.faqs.create(
    name="Store FAQ",
    entries=[
        {"question": "What are your opening hours?", "answer": "We are open nine to six, Monday to Saturday."},
        {"question": "Do you deliver on Sundays?", "answer": "No. Orders placed on Saturday go out on Monday."},
    ],
)
```

The response is the FAQ (`id`, `name`, `entry_count`, …) with `entries`, each with its own
`id`.

Writing entries: phrase questions the way a caller asks them (paraphrases need no extra
entries); keep voice answers to one or two speakable sentences; do not repeat the answers
in the prompt.

### Editing entries

Entries are appended or edited individually, never replaced as a list:

```bash
# Append (1–500 entries, all or nothing)
curl -X POST https://api.talqing.com/v1/faqs/7d1c9e52-3b4a-4f86-a0d7-5e8c2b6f9a13/entries \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entries": [{"question": "Is there parking?", "answer": "Yes, free parking behind the store."}]}'

# Change one entry
curl -X PATCH https://api.talqing.com/v1/faqs/7d1c9e52-3b4a-4f86-a0d7-5e8c2b6f9a13/entries/c41e7a90-6d2b-4b35-8f1a-9e0d3c5b7a24 \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"answer": "We are open nine to seven, Monday to Saturday."}'
```

The dashboard's **Import CSV** appends a file with header `question,answer` (up to 500
rows) as one all-or-nothing append. The API has no import route; send the rows to
`POST /v1/faqs/{faq_id}/entries`.

## Attach it

```json
{ "faqs": [{ "faq_id": "7d1c9e52-3b4a-4f86-a0d7-5e8c2b6f9a13" }] }
```

`faqs` is a list, so a PATCH replaces it whole. Attaching is a config change: publish the
agent for callers to get it.

An item may carry an inline `faq` (`name` plus at least one entry) instead of `faq_id`:

| Sent on | Result |
| --- | --- |
| Agent or task create/update | Created as a stored FAQ; the saved config holds its `faq_id`. A taken name is a `409` |
| A call request (`agent`, `agent_override`, `agent_team`, batch, chat) | Used for that session only. On a batch, prefer `faq_id` — the plan is stored per call |

## How the agent uses it

At session start, the questions of every attached FAQ are appended to the system prompt
under `## FAQ` with short ids (`q1`, `q2`, …). The agent gets a `get_faq_answers` tool
(`{"ids": ["q3"]}`) returning the written answers.

- The questions cost tokens every turn; answers only when fetched.
- On voice and video the agent says it is checking in the same turn as the tool call.
- FAQ text is **never templated** — `{{userdata.name}}` in an answer is read literally.
- A question matching nothing is answered from the prompt and tools as usual; write a
  refusal rule into the prompt if you want one.
- `get_faq_answers` is a reserved tool name.

## Edits are live

FAQs have no draft or versions. Entry changes reach every attached agent and task **from
its next session**, without publishing; a running session keeps what it loaded. Publishing
an agent freezes *which* FAQs are attached, not their content.

> **Warning:**
> A wrong answer saved to an FAQ is what the next caller hears. Reading is open to every
> member; writing needs the editor role.

## Deleting

`DELETE /v1/faqs/{faq_id}` is refused with a `409` while any agent's or task's draft or
current published version attaches it (`this FAQ is attached to agent '…' — detach it there
before deleting it`). Older versions do not block it.

## Limits and errors

| Limit | Value |
| --- | --- |
| `name` | 1–80 characters, unique in the workspace (case-insensitive) |
| `question` | 1–300 characters, unique within the FAQ (case-insensitive, trimmed) |
| `answer` | 1–2,000 characters |
| Entries per FAQ / per append | 500 / 1–500 |
| FAQs per agent or task | 10 |

| Cause | Status |
| --- | --- |
| Name already used | `409` `an FAQ named '…' already exists` |
| Duplicate question in the request, or one the FAQ already has | `422` |
| Append past 500 entries | `422` |
| Unknown `faq_id`, or the same FAQ attached twice | `400` |
| Attached FAQ with no entries | Warning at validate/publish |

Endpoints: `GET`/`POST /v1/faqs`, `GET`/`PATCH`/`DELETE /v1/faqs/{faq_id}` (PATCH renames),
`POST /v1/faqs/{faq_id}/entries`, `PATCH`/`DELETE /v1/faqs/{faq_id}/entries/{entry_id}` —
SDK `faqs.*` and `faqs.entries.*`. See the [API reference](https://docs.talqing.com/api-reference/introduction.md).

## Next

- [Prompting](https://docs.talqing.com/agents/prompting.md): What belongs in the prompt instead.
- [Versions](https://docs.talqing.com/agents/versions.md): What a publish freezes.