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.

{
  "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.

{
  "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.
{
  "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.