An AI assistant is a set of instructions the platform runs the moment a visitor writes or a caller rings. It answers at once, as the business, with the tools you tick. It has no user and asks nobody before acting. For a member of staff that works through a queue, see Set up an AI employee for a role, which also compares the two.
This job builds the assistant and tests it. Pointing the live chat or a live number at it is a separate yes.
Ask first
- Where does it answer? The website chat, a phone number (which one), or both.
- What should it know? The words: opening hours, prices, policies, the questions people ask. And which collections hold answers it should look up (products, a FAQ collection).
- What may it do? Answer only, or also look up orders, book appointments, open tickets, take messages. Name each.
- Who does it hand over to? A person's email, for when it can't help. And what it must never talk about.
- On the phone: its greeting, and the voice. On the chat: a fixed first message, or one it writes.
Steps
1. AI Assistant: what it knows
An assistant's knowledge is a list of knowledgeSources, each { sourceType, reference }. Only two kinds are really read:
sourceType | reference | What happens |
|---|---|---|
custom | the text itself | Put into its instructions. It answers from it directly. No tool needed. |
collection | a collection name, e.g. product or faq | It searches that collection's records by words with the query_knowledge tool, and reads each hit's title and description. Needs query_knowledge in its tools. |
document | a page record's id | query_knowledge reads a site page by id. |
url | a web address | Never fetched. It is told it has not read it. |
The editor's document picker stores a file path, but the lookup reads a page by id, so a picked file is never found. A url is never read. Put what it must know as custom text, or in a collection.
Write the custom text from what the person gave you: short facts, one per line. Don't add prices, hours or promises they didn't give.
For the product catalog, search_products searches it the way the shop does. For bookings, the scheduling tools read the real calendar. Those beat copying the facts into text.
Hands on: the knowledge sources.
2. AI Assistant: the assistant, switched off
Create it: call_appengine POST /crm/ai-assistant (it checks the handle, the channels and each source; create_record skips that). Start it inactive.
| Field | Value |
|---|---|
name | its handle: letters, digits, -, _, unique, e.g. website-chat |
title | what people call it, e.g. Harbor Grill helper |
status | inactive for now (active, inactive, archived) |
personality | how it talks: "warm, brief, plain words" |
behaviorRules | rules it must follow, one per item |
capabilities | built-in playbooks by id, from GET /crm/ai-assistant/capabilities: answer_questions, provide_support, schedule_appointments, qualify_leads, process_orders, product_recommendations, lead_nurturing, lead_follow_up, data_collection, appointment_setting. Or { name, description } with your own steps. |
tools | the list of what it may do (below). Always send a list. |
channels | where it answers: chat, voice, email, sms, whatsapp, facebook, instagram, … Empty means every channel. |
knowledgeSources | from step 1 |
safety | { restrictedTopics: [...], escalationContact: "<email>" } |
onboardingPrompt | its first message to someone new, if the person wrote one |
tools has three states, and they are enforced when it runs, not just told to it:
- left out (or
null): every tool, including sending texts, emails and placing calls; []: none. It can talk but not act;- a list
[{ "key": "query_knowledge", "enabled": true }, …]: only those.
The keys come from GET /crm/ai-assistant/tools. The ones that matter here:
| Key | What it does | Reaches people? |
|---|---|---|
query_knowledge | reads the collection and document sources | no |
search_products, check_product_availability | the catalog and stock | no |
get_reservation_types, check_availability | services and free slots | no |
create_reservation, modify_reservation, cancel_reservation | real bookings, with a confirmation | yes |
create_ticket, create_lead, take_message | a ticket, a lead, a message for the team | no (records only) |
confirm_order_status | an order's status | no |
transfer_chat_to_agent | hands the chat to a person | no |
check_transfer_target | who on the phone it may transfer to | no |
send_email, send_sms, send_whatsapp, send_chat_message | sends a message | yes |
make_call | places a phone call | yes, and costs per minute |
Give it only what the person named. permissions is a sentence it is told, not a lock: to stop an action, leave its tool out.
For the phone, also set its voice: voice (from GET /phone/voice/voices) and voiceProvider (elevenlabs or openai-realtime). speakingSpeed (0.7 to 1.2) is kept only on an update, so set it after create with PUT /crm/ai-assistant/<sk>.
Set channels to where it really answers. An assistant whose channels are empty or include voice takes phone calls, and with no assistant on a number, a number's "hand to the AI assistant" failover uses the business's first active one. A chat-only assistant should say ["chat"].
Hands on: the assistant's sk and name.
Check: open it (/ai-assistant?openId=<sk>). The bar at the bottom says how many tools it has and how many channels it answers.
3. AI Assistant: try it
The test needs the assistant active: an inactive one answers AI Assistant is inactive. Activate this training assistant before running a test. Before you switch it on, make sure nothing points at it yet: no triggers, not on a chat config, not on a number.
Stop. A test runs with its real tools, and each test is charged as AI use. If its list includes send_*, make_call or create_reservation, a test question can send a real message or make a real booking. Say which tools it has, and ask before testing with any of those.
Then PUT /crm/ai-assistant/<sk> with { "status": "active" }, and POST /crm/ai-assistant/<sk>/test with { "task": "<a question a customer would ask>" }. The answer has reply (what it said) and run (the tools it called). In the Studio it is Test it on the assistant.
Ask what the person's customers ask: the opening hours, a product, something it should refuse. Check each answer against the text from step 1. If it invents a fact, tighten custom text and behaviorRules.
Hands on: the test answers.
Check: the Activity Logs tab shows each run and each tool call. GET /crm/ai-assistant/<sk>/activities is the same list.
4a. Chat Designer: the website chat
A chat widget is a chat_config. Its ai field names the assistant. Set it to the assistant's sk: replies work with the name or the sk, but the hand-off when the assistant fails looks it up by sk only, so with the name its safety.escalationContact is never told (appengine chat/chat.gateway.ts 552–581). The Chat Designer saves the name; the Site Config Set up chat wizard saves the sk. Find the config (find_records on chat_config) and set data.ai (update_record_partial). defaultPath: "/chat-ai" opens the widget on the AI chat. In the Studio: Chat Designer (/chat-designer) › AI assistant.
What visitors get:
- a first message the assistant writes when a new visitor connects. (A
data.greetingon the config is sent word for word instead. The designer has no field for it; set it withupdate_record_partialif the person wants fixed words.); - its answers, as it writes them;
- a person, when it calls
transfer_chat_to_agent: the chat goes to the chat queue for staff (and any AI employee listening tochat_queue); - if it fails or is not
active: Sorry, our assistant is unavailable right now. A team member will reply shortly. and the chat is queued for a person.
Stop. If this widget is already on the live website, saving ai changes what visitors get on their next message. Show the person the assistant, its tools and two test answers, and wait for yes. Putting a new widget on the site is Live chat on the website.
Hands on: the chat config's sk. Check: the widget on a test page greets as the assistant. The conversation shows on the agent desk.
4b. Phone & SMS: a phone line
The assistant must take calls: channels empty or with voice, and a voice set.
Stop. Pointing a number at it moves that number's real callers to the AI from the next call. AI voice is charged per minute on top of the call (see service rates). Show the person the number, who answers it now, the greeting, and the tools it has on a call. After a yes:
call_appengine PUT /phone/numbers/<phone sk> with
{ "voiceConfig": { "inboundMode": "ai", "ai": { "assistantId": "<assistant sk>", "greeting": "<first words>", "context": "<what callers need to know about this line>" } } }Send all three ai fields: the ai block is replaced as a whole. A number can have only one AI; a second is refused with 409 NUMBER_HAS_AI, naming who has it. Menus, business hours and failover are Business phone number and call routing.
When the business's balance can't pay for AI voice, or its monthly spend limit is reached, calls ring people instead and the owner is told.
Hands on: the number.
Check: on Phone & SMS (/phone-system) › the number › Configure, Call Handling shows AI assistant with this assistant chosen.
5. AI Assistant: email, social and texts (only if asked)
To answer inbound email, Facebook and Instagram messages, comments and WhatsApp, add a trigger on message.received. Texts are sms.received. Each trigger is { events: [...], filter, instructions }: filter is a plain-words condition it judges ("when they ask about a refund"), instructions what to do then. accounts limits it to some pages, numbers or inboxes. handoff.pauseAfterHumanReplyMinutes (default 120) keeps it quiet after a person replies on social.
Stop. A trigger answers every matching message from then on. There is no cap on how many replies it sends. Show the channels, the accounts and the filter before saving it on an active assistant.
When it's done
Tell the person:
- the assistant's name and whether it is active;
- what it knows (the text, the collections) and what it doesn't read (any
urlor file); - each tool it has, and which of them reach customers;
- where it answers: the chat config, the number, any triggers;
- who it hands over to.
Open the assistant (/ai-assistant?openId=<sk>).
What it can't do yet
urland file knowledge is not read. Onlycustomtext, collections and page records are.- Switching it to
inactivedoesn't take it off the phone. A number set to it still answers with it. Take the number off it (setinboundModeback toring) or removevoicefrom its channels. permissionsandlimits.retryCountdo nothing. Onlytoolslimits what it does.limits.timeoutSecondsis used.- No reply cap. A burst of messages gets a burst of replies.
GET /crm/ai-assistant/<name>is refused. The API wants the sk. The Studio opens either.
Don'ts
- Don't leave
toolsout. That is every tool. - Don't test an assistant that can send or book without saying so first.
- Don't put facts in its text that the person didn't give.
- Don't point a live chat or number at it without a yes.
- Don't set the same channel on an assistant and an AI employee. Both will answer.