docs
/
AI skills

AI assistant for the website chat or a phone line

An AI assistant that answers visitors on the website chat or callers on one of the business's numbers, from the business's own reference text and records, with only the tools it needs — tested first, put live only after a yes.

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:

sourceTypereferenceWhat happens
customthe text itselfPut into its instructions. It answers from it directly. No tool needed.
collectiona collection name, e.g. product or faqIt 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.
documenta page record's idquery_knowledge reads a site page by id.
urla web addressNever 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.

FieldValue
nameits handle: letters, digits, -, _, unique, e.g. website-chat
titlewhat people call it, e.g. Harbor Grill helper
statusinactive for now (active, inactive, archived)
personalityhow it talks: "warm, brief, plain words"
behaviorRulesrules it must follow, one per item
capabilitiesbuilt-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.
toolsthe list of what it may do (below). Always send a list.
channelswhere it answers: chat, voice, email, sms, whatsapp, facebook, instagram, … Empty means every channel.
knowledgeSourcesfrom step 1
safety{ restrictedTopics: [...], escalationContact: "<email>" }
onboardingPromptits 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:

KeyWhat it doesReaches people?
query_knowledgereads the collection and document sourcesno
search_products, check_product_availabilitythe catalog and stockno
get_reservation_types, check_availabilityservices and free slotsno
create_reservation, modify_reservation, cancel_reservationreal bookings, with a confirmationyes
create_ticket, create_lead, take_messagea ticket, a lead, a message for the teamno (records only)
confirm_order_statusan order's statusno
transfer_chat_to_agenthands the chat to a personno
check_transfer_targetwho on the phone it may transfer tono
send_email, send_sms, send_whatsapp, send_chat_messagesends a messageyes
make_callplaces a phone callyes, 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.greeting on the config is sent word for word instead. The designer has no field for it; set it with update_record_partial if 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 to chat_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 url or 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

  • url and file knowledge is not read. Only custom text, collections and page records are.
  • Switching it to inactive doesn't take it off the phone. A number set to it still answers with it. Take the number off it (set inboundMode back to ring) or remove voice from its channels.
  • permissions and limits.retryCount do nothing. Only tools limits what it does. limits.timeoutSeconds is 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 tools out. 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.