# Update the chat bot's Playbook, FAQ and greeting

> Read and change your chat bot's Playbook, its questions and answers, and the greeting new conversations open with, with a preview first.

Your chat bot answers customers on LINE, Facebook, Instagram and web chat. Three things you write shape what it says:

- **Playbook:** your own instructions to the bot, such as what to recommend first, how to talk and what to say about delivery.
- **FAQ:** questions and answers the bot answers from, such as delivery times, payment and returns.
- **Greeting:** what a new conversation on LINE, Facebook or Instagram opens with: your text, then up to 10 videos, pictures or sets of product cards, each with an optional message under it.

All three are the same as **Bot settings** in the dashboard. Changing them needs the `bot:write` permission; reading them needs only `catalog:read`.

- Connector: `get_bot_playbook_and_faq`, then `preview_playbook_update` / `apply_playbook_update` or `preview_faq_update` / `apply_faq_update`. The greeting can't be changed through the connector yet.
- API: `GET /bot`, `POST /bot/playbook`, `POST /bot/faq`, `POST /bot/greeting` and `POST /bot/greeting/media`.

## Read them first

`GET /bot` answers the Playbook, the FAQ and the greeting. Read them before a change, so the change keeps what you want kept.

## Playbook

The text you send **replaces the whole Playbook**, so start from the saved text and change only what you want different. Up to 20,000 characters; `""` clears it.

```json
{
  "dry_run": true,
  "playbook": "แนะนำรถเหล็ก Majorette และฟิกเกอร์ Jada ที่มาใหม่ก่อน เมื่อลูกค้าถามหาของขวัญ\nตอบสุภาพ ลงท้ายด้วยค่ะ"
}
```

- A dry run answers `updated` or `unchanged` and changes nothing.
- Sent for real, the bot reloads with the new Playbook. That takes about 20 seconds, and the answer comes once the bot has it (`reloaded: true`).
- If the answer is `502`, the text was saved but the bot didn't reload. Send the same request with `"reload": true`.

## FAQ

Each row is a `question` (up to 500 characters) and an `answer` (up to 5,000). Up to 200 questions.

```json
{
  "dry_run": true,
  "faq": [
    { "question": "ส่งของกี่วันถึง", "answer": "ส่งภายใน 1-2 วันทำการ ได้รับใน 2-3 วันค่ะ" },
    { "question": "รับชำระเงินช่องทางไหนบ้าง", "answer": "โอนผ่านพร้อมเพย์ หรือจ่ายด้วยบัตรผ่านลิงก์ชำระเงินในแชทค่ะ" }
  ]
}
```

- **Questions are matched** to the saved ones ignoring case and extra spaces. A matched question takes your answer and your wording, and keeps any pictures or videos added in the dashboard.
- **`mode: "merge"`** (the default) adds new questions at the end, updates matched ones and keeps every other question.
- **`mode: "replace"`** makes the FAQ exactly the questions you send, in your order. The others come back as `removed`. `"faq": []` with `replace` removes every question.
- Each row answers `created`, `updated` (with `changed`), `unchanged` or `removed`.
- The bot answers from the new FAQ from its next message.

Pictures and videos on a FAQ answer are added in the dashboard; the API keeps them but can't add them.

## Greeting

The greeting goes, word for word, with the first message of a new conversation on LINE, Facebook or Instagram (and again after 7 quiet days), before the bot's reply. It is never sent on Shopee, Lazada or TikTok.

1. Upload each new video or picture with `POST /bot/greeting/media`: a `multipart/form-data` request with one file in the field `file`, an MP4 of at most 25 MB or a JPEG, PNG or WebP picture of at most 8 MB. A video also needs its preview picture: upload a frame of it the same way. Each answers the file's `url`.
2. Send the greeting with `dry_run: true` and check the answer.
3. Send it again without `dry_run`.

```json
{
  "dry_run": true,
  "text": {
    "line": "สวัสดีค่ะ ผู้ช่วย AI ของร้านค่ะ ถามได้ทุกเรื่อง หรือส่งรูปของเล่นที่ตามหามาได้เลยค่ะ",
    "meta": "สวัสดีค่ะ ผู้ช่วย AI ของร้านค่ะ แอด LINE ของร้านไว้ สั่งของผ่าน LINE Mini App ได้ด้วยค่ะ",
    "ig": "สวัสดีค่ะ ผู้ช่วย AI ของร้านค่ะ แอด LINE ของร้านไว้ สั่งของผ่าน LINE Mini App ได้ด้วยค่ะ"
  },
  "items": [
    { "type": "video", "url": "https://seller-side.sgp1.digitaloceanspaces.com/welcome/how-to-chat-AB12CD.mp4", "thumbnail_url": "https://seller-side.sgp1.digitaloceanspaces.com/welcome/how-to-chat-frame-EF34GH.jpg", "description": "How to chat with the bot and order in the LINE Mini App" },
    { "type": "image", "url": "https://seller-side.sgp1.digitaloceanspaces.com/welcome/sale-1free1-IJ56KL.jpg", "description": "Buy 1 get 1 free on Tomica cars until 15 November", "message": "🎁 Tomica ซื้อ 1 แถม 1 ถึง 15 พ.ย. นี้ค่ะ" },
    { "type": "products", "products": ["TM-001", "TM-011"] }
  ]
}
```

- **What you leave out stays.** Send only `text` to change the words, or `"enabled": false` to stop sending it (the text and items are kept).
- **`text`:** one string for every channel, or `line`, `meta` (Facebook Messenger) and `ig` separately. Up to 1,000 characters each; `""` sends your Welcome message instead.
- **`items`:** the whole list, in order, up to 10. It replaces the saved items; `[]` sends the text alone. A set of `products` is 1 to 10 SKUs, shown as one swipeable message of cards with price and an "Interested" button.
- **`message`:** sent word for word right after its item, up to 1,000 characters: a product's name and sale price under its picture, for example. `"show_message": false` keeps it without sending it. A picture a customer already got is skipped with its message.
- **`description`:** what a video or picture shows. Customers don't see it; the bot reads it to answer a customer who asks about that picture. Write one for each.
- **Each video and picture goes to a customer once.** Send the same link again to keep that; a new upload goes once more. Product cards go every time.
- **On LINE**, a reply holds 5 messages: the text, each item and each message count one. The rest, and the bot's answer after it, go out as LINE push messages, which count toward your LINE plan.

## Common errors

- **`403 Y35`:** the key or connection doesn't have `bot:write`. Create a key with it, or reconnect the assistant and tick it.
- **The same question twice** in one request: send each question once.
- **More than 200 questions** after a merge: remove some, or send the list to keep with `replace`.
- **"upload the image with POST /bot/greeting/media"**: a greeting picture or video must be uploaded there first (or already be in the greeting).
- **"a video needs its preview picture"**: upload a frame of the video and send it as `thumbnail_url`.
