My Website

# Chat settings Source: https://docs.weav.com/agents/email-settings Learn what each chat setting does and how to configure your agent as a chatbot. ## Overview Your agent’s **Chat settings** control how your website chat widget looks, how it behaves, and how safely it handles conversations. If you only change one thing in this area, start here: make sure your chat feels on-brand and has sensible safety limits. These settings are about the **chat experience on your website**.\ They are different from the agent’s core behavior settings (like tone and prohibited phrases). *** ## Why this matters Good chat settings help you: * **Build trust** with a polished, branded chat experience * **Capture leads** with the right form at the right time * **Reduce missed handoffs** with escalation assignment/rules * **Prevent abuse** with session and rate limits * **Increase conversions** by guiding users with quick prompts *** ## Quick-start If you want a strong setup fast: * Use your brand color and a clear welcome message * Show lead form as **Optional** (or **Required** for sales-heavy use cases) * Set `Message limit` to around `100` . *The maximum number of messages allowed per chat customer session* * Set `Rate limit` to around `10` per minute. *The maximum number of messages a customer can send per minute* * Add 2-3 quick prompts for common questions * Set an escalation assignee so customer questions get routed to the right user *** ## Section 1: Deploy This section helps you get chat live and route escalations correctly. ### Installation You’ll see an embed code snippet to copy and paste into your website (near the end of the `` tag). *** ### Escalation assignee Pick a teammate who should be assigned to conversations when a conversation needs to be escalated from the agent to a human user. ### Escalation rules Create rules for when chats should be escalated based on customer input (for example, “cancel account”, “legal”, “speak to manager”). Screenshot2026 02 28at8 03 53AM

Rule-level assignees take priority over the general escalation assignee. *** ## Section 2: Appearance This section controls how your widget looks and feels to customers. ### Title The visible name at the top of the widget. * Example: `Support Team`, `Weav Assistant` **Best practice:** keep it short and recognizable. *** ### Icon The avatar/logo shown in the chat widget. **Best practice:** use a clear, high-contrast icon that matches your brand. *** ### Theme (Light or Dark) Sets the visual style of the chat interface. **Best practice:** match your site’s theme so chat feels native. *** ### Primary color Used across key widget elements (bubbles, titles, accents). **Best practice:** use your primary brand color, but keep contrast readable. *** ### Chat bubble icon Changes the launcher icon style. **Best practice:** pick the icon style that feels most familiar to your audience. *** ### Alignment (Left or Right) Controls where the widget sits on the page. **Best practice:** place chat where it won’t cover critical CTAs or sticky elements. *** ### Welcome message The first message visitors see. **Good example:** `Hey! How can I help you?` *** ### Message placeholder Hint text in the input box. **Good example:** `Ask about plans, integrations, or setup` **Bad example:** `Type...` Why: specific placeholder text nudges better questions. *** ### Footer text Optional text at the bottom of the widget (often links to privacy/terms). **Good use cases:** * Privacy policy link * Terms link * Compliance note *** ### Quick prompts Clickable prompts shown above the input to help users start quickly. Screenshot2026 02 28at8 05 03AM

You can create prompts as: * **Question prompts** (ask the agent directly) * **External link prompts** (sends the customer to a URL) **Value:** reduces blank-page anxiety and increases first interaction rate. **Good starter prompts:** * `What plans do you offer?` * `How long does setup take?` * `Book a demo` *** ## Section 3: Leads This section controls your lead capture form. Leads

### Visibility Choose if the form is: * **Do not show** * **Show (optional)** * **Show (required)** **How to choose:** * Use **Optional** for support-first chat experiences * Use **Required** when lead capture is the primary goal * Use **Hidden** if you only want free-form chat without customer information *** ### Form title and introduction Sets the context before users fill the form. **Good example title:** `Let us know how to contact you`\ **Good example intro:** `Our team will follow up within 1 business day.` *** ### Form fields Choose and arrange what to collect (name, phone, email, etc.). * You can add, edit, delete, and reorder fields * Email is typically kept as a required core field **Best practices:** * Ask for only what you’ll actually use * Keep forms short (2–4 fields is usually enough) * Make fields required only when truly necessary *** ## Section 4: Security This section protects your chat from spam and misuse. ### Message limit Maximum number of messages in a customers chat session. The customer can always start another chat session in the chat interface. **Value:** prevents endless sessions that consume resources. *** ### Rate limit Maximum number of messages a customer can send per minute. **Value:** slows spam/flooding and protects quality of service. If legitimate users are blocked, increase limits slightly and monitor results. *** ## How all chat settings work together A typical visitor journey: 1. They see your branded launcher and open the widget 2. Your welcome message and quick prompts guide their first action 3. Lead form appears based on your visibility setting 4. They chat within your message/rate limits 5. If needed, escalation sends the conversation to the right teammate When configured well, this feels smooth, helpful, and trustworthy. *** ## Best-practice checklist * Brand-matched title, icon, and primary color * Welcome message that states what the assistant can help with * 3–6 high-value quick prompts * Lead form set to Optional or Required based on business goal * Escalation assignee always set * Message/rate limits set and reviewed monthly * Footer includes privacy/terms if needed *** ## FAQ ### Do I need technical skills to use Chat settings? No. Most options are form fields and dropdowns designed for non-technical teams. ### What should I configure first? Start with Appearance (welcome message + quick prompts), then Leads, then Security limits. ### How do I know if settings are working? Check conversation quality, lead form completion, escalation handoff speed, and spam volume after changes. # Email settings Source: https://docs.weav.com/agents/emails Learn how email assignment and auto-send threshold work, and when your AI agent drafts, auto-sends, or escalates for human review. ## Overview The **Email** settings page controls how your agent handles inbound email conversations for your workspace. For most teams, the two most important settings are: 1. **Assignment** (which agent is in charge of responding to emails) 2. **Auto-send threshold** (how confident the agent must be before sending automatically) *** ## How email assignment works

### What “Assignment” does When you click **Assign to email** on an agent: * That agent becomes the workspace’s **active email agent** * Any previously assigned email agent is automatically unassigned * Only **one** agent can be assigned to email at a time Think of this as selecting your workspace’s “primary AI email teammate.” ### What happens to conversations after assignment Assignment mainly affects **new inbound email conversations** and conversations that don’t already have an agent attached. For incoming email conversations, Weav assigns the active email agent to the conversation ### Important nuance (where confusion usually happens) Changing assignment does **not** mass-migrate every existing conversation automatically. So if a conversation is already assigned elsewhere, that existing assignment will stay as-is until reassigned by your team. *** ## How auto-send threshold works This setting decides whether the AI response should be: * escalated (no AI reply sent), * saved as a draft for human user review, * or auto-sent reply. ### The mental model (simple version) For each eligible customer email: 1. The AI generates a draft and confidence score 2. Weav compares confidence against routing thresholds 3. Weav chooses one path: **escalate**, **draft**, or **auto-send** *** ## Confidence levels in the UI Your slider options map to stricter or looser auto-send behavior.

| Setting | Meaning | Effect | | -------------------- | ----------------------- | ----------------------------------------------- | | Low confidence | Lower bar for auto-send | More replies auto-send; fewer drafts | | Medium confidence | Balanced bar | Mix of auto-sent and reviewed drafts | | High confidence | Conservative default | Only stronger replies auto-send | | Very high confidence | Strictest bar | Most replies become drafts | | Never auto-send | Auto-send is disabled | AI can prepare drafts, but will never auto-send | *** ## Exactly when each outcome happens ### 1) AI does **not** auto-respond (human path / escalation) This happens when confidence is too low (below the safety floor) or escalation conditions are met. Typical result: * Conversation is routed toward a human * AI draft is not used as the final response path ### 2) AI creates a **draft for review** This happens when confidence is acceptable but not high enough for auto-send. Typical result: * Draft appears for a teammate to review/edit/send * Human stays in control of final outbound message ### 3) AI **auto-sends** This happens when confidence meets/exceeds your selected threshold and auto-send is allowed. Typical result: * Response is treated as safe enough to send automatically * Faster response times with less manual effort *** ## When the agent won’t reply automatically (common reasons) Even with assignment configured, auto-replies may not occur for specific messages: * Conversation is not assigned to an agent workflow path * Message is classified as notification/system-style email * Message is internal/non-customer * Billing/trial access for AI resolution is unavailable * Confidence falls into escalate-or-review paths instead of auto-send This is expected safety behavior, not failure. *** ## Recommended rollout (to build team confidence) If your team is new to AI email automation: 1. Start with **High** or **Very high** 2. Review draft quality for a week 3. Add/adjust escalation rules and assignees 4. Move to **Medium** only after quality is consistently strong A gradual rollout helps teams trust the system while protecting customer experience. *** ## Additional email settings ### Escalation assignee Who receives conversations when escalation is needed. ### Escalation rules Specific triggers that force handoff to a human teammate. Screenshot2026 02 28at8 03 53AM 1

### Signature Appended signature format for agent-generated email content (supports using `{agent_name}` as a variable which gets replaced by the name of the agent in the signature). ### Notice Optional banner text shown at the top of agent emails (hidden, first email only, or all emails). This is helpful for instances when you want emails to always show a notice so you don't have to repeat yourself. This is helpful for things like holiday promotions or communicating that you're aware of an outage happening. *** ## Best practices * Keep exactly one clear owner for email assignment * Use conservative thresholds first, then loosen gradually * Treat drafts as a training signal: edit patterns tell you what to improve * Pair auto-send with strong escalation coverage for sensitive topics * Revisit threshold monthly as your agent quality improves # Escalation Rules Source: https://docs.weav.com/agents/escalation-rules Control when your AI agent hands off conversations to your team using escalation rules. ## What are escalation rules? Escalation rules tell your Weav AI agent **when** to hand off a conversation to a human teammate instead of answering it. When a customer message matches a rule, the agent stops replying as usual, sends a short handoff message, and the conversation is assigned to a teammate (or to your inbox if you use a default escalation assignee). Rules are defined as **conditions** in plain language. A separate AI step evaluates each new customer message against your rules and picks the **first** matching rule, if any. That way you can prioritize (e.g. “speak to a human” before “billing question”) by ordering your rules. Escalation rules are configured **per channel**: you can have different rules (and different assignees) for **Chat** and **Email**. *** ## How escalation rules are evaluated 1. **When**: After the customer sends a message and the agent has enough context, Weav checks escalation **before** generating a normal reply. Only the **latest customer message** in the thread is used for the check. 2. **Matching**: An internal classifier compares that message to each of your rules in order. It returns the **first** rule whose condition “clearly relates” to what the customer said. If none match, the agent continues and answers as usual. 3. **Result**: If a rule matches, the conversation is escalated: the agent sends a single handoff message (e.g. “I’m sorry about the frustration — let me get you to a teammate who can help.”), the conversation is reassigned to the rule’s assignee (or your default escalation assignee), and a system note is added. The agent does **not** generate a full answer in that turn. Rules are **not** simple keyword filters. The system uses semantic understanding so that phrases like “I need to talk to someone real” can match a rule such as “If the customer asks to speak with a human,” even if the exact words differ. *** ## Where to configure escalation rules * **Chat**: In the Weav dashboard, open your **Agent** → **Chat** settings → **Deploy** section → **Escalation rules** (Manage). * **Email**: Same agent → **Email** settings → **Deploy** section → **Escalation rules** (Manage). Each rule has: * **Condition**: A short description of when to escalate (e.g. “If the customer mentions a refund or return”). * **Assignee** (optional): A teammate to assign the conversation to. If you leave this blank, Weav uses the channel’s **Escalation assignee** (the default person for that channel). Rule order matters: the first matching rule wins. Put the most important or urgent cases at the top. *** ## Good examples of escalation conditions These are clear, intent-based conditions that work well with the classifier: | Condition | Why it works well | | ----------------------------------------------------------------- | --------------------------------------------------------------------- | | If the customer sounds angry, frustrated, or upset | Describes a state; matches many ways of expressing frustration. | | If the customer asks or demands to speak with a human | Clear intent; catches “real person,” “human agent,” “not a bot,” etc. | | If the customer asks to speak with a manager or supervisor | Specific request type; easy for the model to recognize. | | If the customer requests a refund or return | Concrete topic; covers “refund,” “return,” “money back,” etc. | | If the customer mentions a legal threat or legal action | Sensitive topic; good to escalate consistently. | | If the customer says they want to cancel their account | Clear business outcome; avoids the agent trying to “save” them alone. | | If the customer reports a security concern or compromised account | High-priority, sensitive; benefits from human handling. | *** ## Examples to avoid These tend to be too vague, too narrow, or too literal and can lead to missed or wrong escalations: | Condition | Why to avoid | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | Refund | Too short; no “if” or context. Prefer: “If the customer requests a refund or return.” | | When they say the word “manager” | Too literal; “I’ll ask my manager” might false-positive. Prefer intent: “If the customer asks to speak with a manager.” | | Complaints | Too broad; almost any negative message could match. Be more specific (e.g. “If the customer is angry or demands to speak with a human”). | | If the customer writes more than 100 words | Not about intent or topic; the classifier is built for meaning, not length. | | If the customer uses ALL CAPS | Focuses on formatting, not content; unreliable and often irrelevant. | | If the message contains “@” or “#” | Same issue; symbols don’t reliably indicate when to escalate. | *** ## Tips for writing escalation rules 1. **Use “If…”**\ Start with “If the customer…” so the condition reads like a single, clear criterion. 2. **Describe intent or topic, not exact words**\ “If the customer asks for a refund or return” is better than “If the customer says refund.” 3. **One main idea per rule**\ Keep each rule to one situation (e.g. human handoff, refunds, legal, security). Split into two rules if you have two distinct cases. 4. **Order by priority**\ Put “speak to a human” and “angry/frustrated” above “billing question” if you want those to take precedence. 5. **Use the default escalation assignee**\ Set a default assignee for the channel so rules without a specific assignee still go to someone. Rule-level assignees override the default. *** ## What happens after an escalation? * The customer sees one agent message that explains they’re being transferred (tone is adjusted if they seem frustrated). * The conversation is assigned to the chosen teammate (or unassigned if no assignee is set). * A system event is recorded (e.g. “escalated to \[Name]” or “unassigned via escalation”). * The conversation appears in the Inbox for your team to pick up; you can filter or report on “escalated” conversations. Escalation rules only apply when the conversation is **assigned to the agent**. If a human is already assigned, the escalation step is skipped and the agent does not run. *** ## Summary * **Escalation rules** = conditions (in plain language) that tell the agent when to hand off to a human. * They are evaluated by a separate AI step on the **latest customer message**; the first matching rule wins. * Configure them **per channel** (Chat and Email) in your agent’s Deploy settings. * Write **clear, intent-based conditions** (good examples above) and avoid **vague or literal wording** (bad examples). * Order rules by priority and use the default escalation assignee so every escalation has an owner. # General settings Source: https://docs.weav.com/agents/general-settings Learn what each setting does in the agent Settings tab, with practical guidance for tone, response length, prohibited phrases, and context. This page is different from the **Chat** and **Email** tabs.\ The settings below affect the agent’s core identity and response behavior. *** ## General settings ### Name Your internal display name for this agent. * Shows in the Agents sidebar and settings screens * Helps teammates identify the right agent quickly **Best practices** * Use role-based names (`Support Assistant`, `Billing Assistant`) * Avoid ambiguous names (`Agent 1`, `Test Bot`) *** ### Avatar Profile image used for this agent in UI previews and agent lists. * Purely visual/identity * Does not change model behavior **Best practices** * Use a clear, brand-aligned icon * Keep style consistent across all agents in a workspace *** ### ID Read-only unique ID for the agent, with copy-to-clipboard. * Useful for support/debugging * Safe to share internally when referencing a specific agent config *** ## Guidance settings (behavior controls) These are the most important controls for output quality. ### Tone Controls *how* the agent says things. Available options: * `Warm` * `Neutral` * `Professional` * `Direct` * `Witty` #### When to use each tone | Tone | Best for | Watch out for | | ------------ | ------------------------------------------ | ------------------------------------- | | Warm | Customer support, high-empathy moments | Can become verbose or too casual | | Neutral | Mixed workloads, general support | Can feel generic if overused | | Professional | B2B, compliance-heavy, formal comms | Can sound rigid if over-formal | | Direct | High-volume queues, urgent troubleshooting | Can sound abrupt if not softened | | Witty | Brand voice with personality | Can sound flippant in sensitive cases | #### Tone best practices * Choose one tone per agent and keep it stable * Match tone to audience (B2B vs consumer) * If you use Witty, add clear prohibited phrases and context guardrails *** ### **Response length** Controls *how much detail* the agent gives. Available options: * Short * Standard * Long #### How to choose | Length | Best for | Risk | | -------- | ---------------------------------------------- | ------------------------ | | Short | High-volume support, quick confirmations | May omit required detail | | Standard | Most support teams (default recommendation) | Low risk | | Long | Complex technical issues, policy-heavy answers | Can overwhelm customers | *** ### **Prohibited phrases** A managed list of words/phrases the agent should avoid using when generating responses. Examples: * “That’s our policy” * “I can’t help with that” * “As an AI language model” #### How it works * You maintain the list by clicking **Manage** * The system instructs the model to never use these phrases For strict compliance needs, include phrase variants and continuously review responses. *** ### **Context** Business context that helps the agent understand your business. Think of this as important knowledge that you want your agent to know about your business. #### What to include * Product/service scope * Support boundaries (what you do and don’t support) * Contact and escalation paths * Key policies (refunds, SLAs, shipping windows) * Canonical links or docs to trust #### What not to include * Secrets (API keys, passwords, private credentials) * Time-sensitive data likely to go stale quickly * Ambiguous or conflicting policy text #### Good context example > Weav is a B2B customer support platform for SMB teams. > > Support hours: Mon–Fri, 9am–6pm ET. > > Refund policy: monthly plans can be refunded within 14 days of first payment. > > For billing disputes, route customers to [billing@weav.com](mailto:billing@weav.com) and ask for invoice ID. > > Do not provide legal advice or respond to questions unrelated to Weav. For security requests, escalate to [security@weav.com](mailto:security@weav.com). #### Bad context example > We are the best support company. Be helpful and nice. We do many things. #### Context best practices * Write for decisions, not marketing * Use short bullets and explicit rules * Update when policy/process changes * Add examples of edge cases your team sees often *** ## **How these settings work together** At generation time, the agent is guided by: 1. Base system prompt 2. Your **Context** 3. Your **Response length** 4. Your **Tone** 5. Your **Prohibited phrases** This means all four guidance settings are cumulative. A weak or vague context can still reduce quality even if tone and length are configured well. # Playground Source: https://docs.weav.com/agents/playground Test your AI agent’s real response behavior safely. ## What the Agent Playground is The **Agent Playground** is a built-in testing panel on the agent settings page that lets you ask your agent questions and see how it responds in real time. It's main purpose is to **validate agent behavior before you deploy it to your customers**. *** ## Why teams use the Playground Playground helps you: * Test answers without embedding the chat on your site or sending emails * Validate training data quality before launch * Check if tone, response length, and prohibited phrases are properly configured * Confirm escalation behavior in a safe environment * Catch weak or hallucinated answers early Think of Playground as your “staging environment” for agent quality. *** ## What is different from production Playground is **safe and non-production**. It does **not** behave exactly like a live customer conversation in every way. ### Not saved to inbox Conversations in Playground are **not** written to your inbox as customer conversations. ### No customer-facing side effects Playground tests do not send real customer emails or create live chat messages. ### Session is temporary Your test thread exists in the sidebar session and can be reset using the refresh control or refreshing your browser. *** ## Best ways to use the Playground ### 1) Smoke test before publishing changes After updating instructions, context, training, or prohibited phrases: * Ask 5–10 representative customer questions * Confirm answers are accurate and on-brand * Verify sources look relevant ### 2) Test edge cases Try hard prompts such as: * Ambiguous questions * Policy exceptions * Escalation-sensitive requests * Out-of-scope questions ### 3) Run “before vs after” checks Use the same test prompts before and after major changes to see whether quality improved. ### 4) Verify source quality If response sources look weak or unrelated, improve your training data before deployment. *** ## Tips for non-technical users * Start with your top 10 real customer questions * Keep a reusable prompt set so testing is consistent * If output quality drops, review training data first * Save settings before testing if you see an “unsaved changes” notice (so preview reflects latest config) # Prohibited Phrases Source: https://docs.weav.com/agents/prohibited-phrases Control what your AI agent never says by listing phrases it must avoid in every response. ## What are prohibited phrases? Prohibited phrases are words or short phrases you tell your Weav agent **never to use** in its replies. When the agent generates an answer (in chat, email, or the playground), its system instructions include your list and tell the model: “Never use the following phrases in your responses.” That keeps the agent from saying things that are off-brand, dismissive, or risky—like “That’s our policy,” “As I already told you,” or competitor names. Prohibited phrases apply to **all** channels and flows that use that agent: chat widget, email drafts, playground, and any API-driven generation. There is one list per agent; you manage it in the dashboard and it’s saved with the agent. *** ## How prohibited phrases are used 1. **Where they go**: When the agent builds its system prompt (the instructions that define how it should answer), your prohibited phrases are appended as a block like: * “**Prohibited Phrases:** Never use the following phrases in your responses:” followed by each phrase on its own line. 2. **When they apply**: That full system prompt (including the prohibited list) is sent to the model for every reply. The model is not asked to “detect” or “classify” phrases; it is instructed up front to avoid them while generating. 3. **Refinement**: If a response is later refined (e.g. “make it shorter”), the refinement instructions also tell the model to keep adhering to tone, length, and **prohibited phrases**, so revised answers stay within the same guardrails. So the feature is **prompt-based**: the AI sees “never use these” in its system instructions and is expected to avoid them in its own wording. It works best when phrases are concrete and easy to recognize. *** ## Where to configure prohibited phrases In the Weav dashboard: open your **Agent** → **Guidance** section → **Prohibited phrases** → **Manage**. You can add as many phrases as you need, one per line. Save when done; the list is applied the next time the agent generates or refines a response. *** ## Good examples of prohibited phrases These are specific, easy for the model to avoid, and address real tone or policy concerns: | Phrase | Why it works well | | ------------------------------ | --------------------------------------------------------------------------------- | | As I already told you | Dismissive; agents should re-explain or clarify instead. | | That's our policy | Often sounds rigid; better to explain the reason in your own words. | | I'm not sure | Undermines trust; the agent can say “Let me find out” or offer a clear next step. | | \[Competitor name] | Keeps the agent from recommending or mentioning competitors. | | You're wrong | Confrontational; the agent can correct gently without this wording. | | Sorry, we can't help with that | Sounds like a dead end; better to offer alternatives or escalation. | | No problem | Fine to prohibit if you prefer “You’re welcome” or similar. | | Just contact support | Vague; better to give a concrete action (e.g. “Contact support at X”). | Short, exact phrases and common variants (e.g. “That’s our policy” / “It’s our policy”) are best added as separate lines if you care about both. *** ## Examples to avoid These are harder to enforce or less useful: | Phrase or approach | Why to avoid | | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Very long sentences (e.g. a full paragraph) | The model may need to say the same idea in different words; a long “phrase” is hard to avoid without changing meaning. | | Single common words like “the” or “and” | Would block normal grammar and hurt readability. | | Anything negative / anything that might upset the customer | Too vague; the model can’t reliably apply it. Prefer specific phrases. | | Slang or idioms that have many variants | If you only list one form, the model might use a synonym. List the main variants you care about. | | Phrases that are essential to your answers | If you must sometimes say “We’re closed on Sundays,” don’t prohibit “We’re closed”; prohibit only the exact wording you never want (e.g. “We’re closed, period.”). | *** ## Tips for writing prohibited phrases 1. **Use exact wording**\ Add the precise phrase you want to avoid (e.g. “That’s our policy”), not a description (“anything about policy”). 2. **Keep entries short**\ A few words or one short sentence per line works best. Long sentences are hard for the model to avoid without paraphrasing in ways you might not want. 3. **Add variants if needed**\ If you want to block “I don’t know” and “I'm not sure,” add both. The model follows the list literally. 4. **Focus on tone and risk**\ Prioritize phrases that sound dismissive, confrontational, off-brand, or that mention competitors or sensitive topics. 5. **Review after incidents**\ If the agent says something you don’t want again, add that exact phrase (or a shortened form) to the list and save. *** ## What prohibited phrases don’t do * **They don’t block the customer.** Prohibited phrases only restrict what the **agent** says. Customer messages are not filtered by this list. * **They don’t guarantee 100% avoidance.** The model is instructed not to use the phrases; it usually complies, but slips can happen. **Making it more specific can help.** * **They don’t replace escalation.** If you want certain topics to go to a human, use **escalation rules**. Prohibited phrases only control wording. *** ## Summary * **Prohibited phrases** = a list of words/phrases the agent must never use in its replies. * They are added to the **system prompt** and apply to chat, email, playground, and refinement. * Use **short, exact phrases** and add **variants** you care about; avoid long sentences and vague rules. * Configure them under **Agent → Guidance → Prohibited phrases** in the Weav dashboard. # Chat Quick Prompts Source: https://docs.weav.com/agents/quick-prompts Add one-tap question buttons or links above the chat input so customers can start conversations quickly. ## What are chat quick prompts? Chat quick prompts are optional **buttons** (or “chips”) that appear in your embedded chat widget **above the message input** when the conversation is still empty. They give visitors a one-tap way to ask a common question or open a link instead of typing. There are two kinds: 1. **Ask the AI a question** – You define a **label** (what’s on the button) and the **question text** (what gets sent). When the visitor clicks, that question is sent as their first message and the agent replies to it like any other message. 2. **Link to an external URL** – You define a **label** and a **URL**. When the visitor clicks, the link opens in a new tab. No message is sent to the agent. Quick prompts only show when there are **no messages yet** in the thread. After the first message, they disappear so the input stays clear. If you use a lead-capture form that must be filled before chatting, quick prompts are hidden until the form is completed or skipped (if allowed). *** ## How quick prompts work * **Where they appear**: In the chat widget, above the text input, only when the conversation is empty (and not blocked by the lead form). * **What the visitor sees**: The **label** you set for each prompt (e.g. “Opening hours”, “Contact sales”). * **Question type**: Clicking sends the **prompt text** as the visitor’s message. The agent receives it like a normal customer message and answers using its system prompt, knowledge base, and tools. There is no special handling—the AI simply replies to that text. * **Link type**: Clicking opens the **URL** in a new browser tab. No message is sent to the agent. * **Order**: Prompts are shown in the order they are listed in the dashboard (typically the order you added them). *** ## Where to configure quick prompts In the Weav dashboard: open your **Agent** → **Chat** tab → **Appearance** section → **Quick prompts** → **Manage**. Add, edit, or remove prompts and choose for each one: * **Label** – The short text on the button (e.g. “Opening hours”, “Pricing”). * **Type** – “Ask AI agent a question” or “Link to an external URL”. * **Question** (for question type) – The exact text sent as the visitor’s message (e.g. “What are your opening hours?”). * **URL** (for link type) – The full URL (e.g. `https://example.com/contact`). Each prompt is either a question or a link; you cannot set both for the same prompt. *** ## Good examples **Question prompts** – Clear label + question that matches what the agent can answer: | Label | Question | Why it works | | ------------- | ------------------------------------------------- | ------------------------------------------------- | | Opening hours | What are your opening hours? | Short, clear; agent can answer from knowledge. | | Shipping info | What are the shipping options and delivery times? | Specific; fits one reply. | | Returns | What is your return policy? | Common intent; easy for the agent to handle. | | Talk to sales | I’d like to speak to someone in sales. | Can trigger escalation if you have a rule for it. | **Link prompts** – When the answer lives on a page or you want to send users elsewhere: | Label | URL example | Why it works | | ----------- | ---------------------------------------------------------- | ----------------------------------- | | Book a demo | [https://example.com/demo](https://example.com/demo) | Direct path to conversion. | | Help center | [https://help.example.com](https://help.example.com) | Self-serve without using the agent. | | Contact us | [https://example.com/contact](https://example.com/contact) | Clear next step. | *** ## Examples to avoid | Approach or label | Why to avoid | | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | | Label and question don’t match (e.g. label “Hours”, question “Tell me about your company”) | Confusing; the agent answers the question, so the question should reflect the label. | | Very long question (e.g. a full paragraph) | Works technically but is heavy as a one-tap starter; keep it to a short sentence. | | Vague label (e.g. “Click here”, “More”) | Doesn’t tell the visitor what they’ll get; use a clear, specific label. | | Broken or non-HTTPS link for link type | Unreliable or insecure; use a valid, HTTPS URL. | | Same idea as both question and link | Pick one: either let the agent answer (question) or send them to a page (link). | *** ## Tips for writing quick prompts 1. **Keep labels short** – A few words (e.g. “Opening hours”, “Returns”) so buttons stay readable. 2. **Match the question to your knowledge** – Use question prompts for things your agent is trained on; use link prompts for pages, forms, or tools. 3. **Order by importance** – Put the most common or important prompts first so they’re easy to spot. 4. **Use question text the customer might type** – The prompt is sent as their message; phrasing it like a real question (e.g. “What are your opening hours?”) helps the agent answer naturally. 5. **Use links for signup, demos, or long content** – If the best answer is “go to this page,” use a link prompt instead of a long agent reply. *** ## What quick prompts don’t do * **They don’t change the agent’s behavior** – Question prompts are just pre-filled customer messages. The agent uses the same system prompt, prohibited phrases, and escalation rules. * **They don’t show after the first message** – They only appear when the thread is empty so the UI stays simple once the conversation has started. * **They aren’t separate “flows”** – The agent doesn’t treat a quick-prompt message differently; it’s one more user message in the thread. *** ## Summary * **Quick prompts** = optional buttons above the chat input when the conversation is empty. * **Question type**: Label on the button; click sends the question text as the visitor’s message; the agent replies normally. * **Link type**: Label on the button; click opens the URL in a new tab; no message to the agent. * Configure under **Agent → Chat → Appearance → Quick prompts**. Use short, clear labels and questions (or URLs) that match what you want the visitor to get. # Create agent Source: https://docs.weav.com/api-reference/agents/create-agent /api-reference/openapi.json post /agents The model is set automatically to gpt-4o-mini. # Delete agent Source: https://docs.weav.com/api-reference/agents/delete-agent /api-reference/openapi.json delete /agents/{id} # Get agent Source: https://docs.weav.com/api-reference/agents/get-agent /api-reference/openapi.json get /agents/{id} # List agents Source: https://docs.weav.com/api-reference/agents/list-agents /api-reference/openapi.json get /agents # Update agent Source: https://docs.weav.com/api-reference/agents/update-agent /api-reference/openapi.json put /agents/{id} Model updates are not supported via this endpoint. # Programmable Chatbot Source: https://docs.weav.com/api-reference/chatbot ## Overview The Weav Chatbot Widget is a lightweight, embeddable chat interface that lets you add AI-powered customer support to any website. It renders a customizable launcher button that opens a chat interface in an iframe, and it can be controlled through a simple JavaScript API. The configuration options below are to provide developers with more flexibility of the Weav chatbot experience. Most of these features can be controlled within the Weav application for non developers. ## Features * Fully customizable appearance, including colors, icons, text, position, and theme * Mobile responsive with optimized layouts * Accessible, including ARIA labels and keyboard support with the `Esc` key * Lightweight with minimal performance impact * Secure iframe isolation * JavaScript API for initialization, teardown, and event handling *** ## Installation ### Basic usage 1. Include the widget script near the end of your `` tag. 2. Call `window.WeavWidget.init()` once the script has loaded. ```html theme={null} ``` The widget automatically injects its mount node and lazy-loads the iframe the first time it opens. ## Quick start example ```html theme={null} My Website ``` *** ## JavaScript API Once loaded, the script registers a single global object: `window.WeavWidget`. | Method | Description | | :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `init(options?: InitializeOptions)` | Mounts the widget with the provided configuration. Calling `init()` again tears down the current instance and mounts a fresh one with the new options. | | `destroy()` | Unmounts the widget, clears queued actions, and removes any DOM nodes created by the widget. | | `open()` | Programmatically opens the widget. Throws if called before `init()`. | | `close()` | Programmatically closes the widget. Throws if called before `init()`. | | `sendMessage(message: string)` | Sends a message to the chat on behalf of the visitor. Call `open()` first if the widget is not already visible. Throws if called before `init()` or with an empty string. | | `on(event, listener)` | Subscribes to widget lifecycle events: `opened` and `closed`. Returns an unsubscribe function. | | `off(event, listener)` | Unsubscribes a previously registered listener. | | `isInitialized()` | Returns `true` when the widget is currently mounted. | *** ## Configuration options Pass configuration through the object supplied to `init()`. `agentSlug` is required. All other properties are optional. ### Top-level options | Option | Type | Default | Description | | | :--------------- | :------------ | :----------- | :------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | | `agentSlug` | `string` | **Required** | Unique identifier for your AI agent. You can get this from [https://app.weav.com/agents](https://app.weav.com/agents) → Chat tab | | | `launcherZIndex` | \`number | string\` | `2147483000` | CSS `z-index` for widget elements | | `launcherHidden` | `boolean` | `false` | Hides the launcher button when set to `true`. The widget can still be opened programmatically with `open()` | | | `mountElement` | `HTMLElement` | Auto-created | Optional DOM node to render into instead of creating one automatically | | ### Branding options Use the `branding` object to customize the launcher button. | Option | Type | Default | Description | | | :---------------------- | :------- | :-------- | :----------------------------------------------- | ----------------------------------------------------------------------------- | | `branding.accent_color` | `string` | `#0f172a` | Primary accent color for the launcher background | | | `branding.icon` | \`string | null\` | `null` | Icon shown on the launcher. Can be an emoji, text, or an image URL | | `branding.name` | \`string | null\` | `null` | Name used in the launcher button ARIA label, such as `Chat with AI Assistant` | ### Widget options Use the `widget` object to customize behavior and appearance. | Option | Type | Default | Description | | | :--------------------------- | :------- | :------------- | :--------------------------------- | ---------------------------------------------- | | `widget.mode` | `enum` | `light` | Visual theme of the widget | | | `widget.button_icon` | `enum` | `chat` | Icon type for the launcher button | | | `widget.button_position` | `enum` | `bottom-right` | Position of the launcher button | | | `widget.welcome_message` | \`string | null\` | `Hello! How can I help you today?` | Welcome message shown in the chat interface | | `widget.message_placeholder` | \`string | null\` | `Ask me anything...` | Placeholder text for the message input | | `widget.footer_text` | \`string | null\` | `null` | Custom footer text shown in the chat interface | *** ## Widget modes | Value | Description | | :------ | :---------------------------------- | | `light` | Light theme with a white background | | `dark` | Dark theme with a dark background | ## Button icons | Value | Description | | :----- | :---------------- | | `chat` | Default chat icon | ## Button positions | Value | Description | | :------------- | :---------------------------------- | | `bottom-right` | Bottom-right corner of the viewport | | `bottom-left` | Bottom-left corner of the viewport | ## Examples ### Minimal configuration ```text theme={null} ``` ### Custom branding ```text theme={null} ``` ### Custom icon using an image URL ```text theme={null} ``` ### Left-aligned launcher button ```text theme={null} ``` ### Dark mode widget ```text theme={null} ``` ### Custom widget messages ```text theme={null} ``` ### High z-index for complex sites ```text theme={null} ``` *** ## Programmatic control * Use `window.WeavWidget.open()` to open the widget without user interaction * Use `window.WeavWidget.close()` to close it programmatically * Use `window.WeavWidget.destroy()` to remove the widget entirely * Use `window.WeavWidget.init(newOptions)` at any time to re-initialize the widget with updated configuration\\ Queued `open()` and `close()` calls made immediately after `init()` run as soon as the React tree is ready, so you do not need to wait for a callback. *** ## Events Use `on()` and `off()` to react to widget lifecycle events. ```text theme={null} ``` Listeners run inside a guard so thrown errors are logged without breaking other listeners. *** ## Custom mount point Provide `mountElement` if you want to render the widget inside your own container. ```text theme={null}

``` The widget clears the provided element before rendering. Calling `destroy()` leaves the element in place so you can reuse it for future mounts. *** ## Triggering the widget from custom elements You can open the widget and optionally send a pre-filled message from any element on your page. This is useful when you want buttons, links, or other UI elements to start a specific conversation. ### Open and send a message by element ID ```text theme={null} ``` ### Open and send a message by class name ```text theme={null} ``` ### Multiple trigger buttons You can attach different messages to different elements. ```text theme={null} ``` *** ## Advanced usage ### Programmatic control only The launcher button is visible by default. To hide it and control the widget entirely through JavaScript, set `launcherHidden: true` and use `open()` and `close()`. ```text theme={null} ``` When `launcherHidden` is `true`, the launcher button is completely hidden and the widget can only be opened with `window.WeavWidget.open()`. This is useful when you want to integrate the widget into your own custom UI. ### Re-initializing with new options ```text theme={null} window.WeavWidget.destroy() window.WeavWidget.init({ agentSlug: '{agent slug}', branding: { accent_color: '#22d3ee', }, }) ``` Re-initializing ensures updated configuration values are applied cleanly. # Create company Source: https://docs.weav.com/api-reference/companies/create-company /api-reference/openapi.json post /companies # Delete company Source: https://docs.weav.com/api-reference/companies/delete-company /api-reference/openapi.json delete /companies/{id} # Get company Source: https://docs.weav.com/api-reference/companies/get-company /api-reference/openapi.json get /companies/{id} # List companies Source: https://docs.weav.com/api-reference/companies/list-companies /api-reference/openapi.json get /companies # List customers for company Source: https://docs.weav.com/api-reference/companies/list-customers-for-company /api-reference/openapi.json get /companies/{id}/customers # Update company Source: https://docs.weav.com/api-reference/companies/update-company /api-reference/openapi.json put /companies/{id} # Create conversation Source: https://docs.weav.com/api-reference/conversations/create-conversation /api-reference/openapi.json post /conversations Assignment rules: - Assignees must belong to the same workspace as the API key. - Chat conversations can be assigned to users, unassigned, or only the conversation's original chat agent. - Email conversations can be assigned to users, unassigned, or only the workspace's active email agent. # Delete conversation Source: https://docs.weav.com/api-reference/conversations/delete-conversation /api-reference/openapi.json delete /conversations/{id} # Get conversation Source: https://docs.weav.com/api-reference/conversations/get-conversation /api-reference/openapi.json get /conversations/{id} # List conversations Source: https://docs.weav.com/api-reference/conversations/list-conversations /api-reference/openapi.json get /conversations # List messages in conversation Source: https://docs.weav.com/api-reference/conversations/list-messages-in-conversation /api-reference/openapi.json get /conversations/{id}/messages # Update conversation Source: https://docs.weav.com/api-reference/conversations/update-conversation /api-reference/openapi.json put /conversations/{id} Assignment rules: - Assignees must belong to the same workspace as the API key. - Chat conversations can be assigned to users, unassigned, or only the conversation's original chat agent. - Email conversations can be assigned to users, unassigned, or only the workspace's active email agent. # Create customer Source: https://docs.weav.com/api-reference/customers/create-customer /api-reference/openapi.json post /customers # Delete customer Source: https://docs.weav.com/api-reference/customers/delete-customer /api-reference/openapi.json delete /customers/{id} # Get customer Source: https://docs.weav.com/api-reference/customers/get-customer /api-reference/openapi.json get /customers/{id} # List customer conversations Source: https://docs.weav.com/api-reference/customers/list-customer-conversations /api-reference/openapi.json get /customers/{id}/conversations # List customers Source: https://docs.weav.com/api-reference/customers/list-customers /api-reference/openapi.json get /customers # Update customer Source: https://docs.weav.com/api-reference/customers/update-customer /api-reference/openapi.json put /customers/{id} # Introduction Source: https://docs.weav.com/api-reference/introduction Build secure, real-time customer support integrations with the Weav API and webhooks. # Build on Weav The Weav Developer Platform helps you integrate AI-powered customer support directly into your product stack. Use the API to manage agents, conversations, messages, customers, companies, and training data in your workspace, with predictable, organization-scoped behavior that’s built for production integrations. Authentication is token-based and ability-scoped. Endpoints are versioned under `/v1`, return consistent JSON structures, and include clear error signaling—making it easier to handle retries, validation issues, and long-term maintenance as your integration grows. Webhooks complement the API by delivering real-time events to your systems when conversations, customers, agents, or training data change. Together, the API and webhooks give you the complete integration loop: send commands into Weav and react to updates from Weav in near real time. ### What you can build * Sync conversations and customer records with your CRM * Trigger automations from live support events * Manage AI agents and training data programmatically * Build internal tooling for support operations and analytics 1. Your app calls the Weav API to create or update resources. 2. Weav emits webhook events as those resources change. 3. Your backend processes events and updates your downstream systems. * Use idempotent handlers for webhook processing * Retry safely on transient failures * Log request IDs and event IDs for traceability *** # Authentication The Weav External API uses **Bearer token authentication** with workspace-scoped API keys. All external endpoints are versioned under `/v1` and require a valid token in the `Authorization` header. ``` Authorization: Bearer YOUR_API_KEY ``` > Your API key inherits your workspace context. Requests can only access resources within that workspace. *** ### Get an API Key You can create API keys in the Weav dashboard: 1. Go to **Settings → API Tokens** 2. Click **Create API token** 3. Enter a name (and optional expiration) 4. Create the token 5. Copy the token immediately and store it securely > ⚠️ **Important**\ > The plain-text token is shown only once at creation time.\ > If you lose it, delete the token and create a new one. *** ### Use the Key in Requests Example using `curl`: ```bash theme={null} curl -X GET "https://api.weav.com/v1/agents" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json" ``` *** ### Common Authentication Failures ### 401 — Unauthenticated Usually means the token is missing, malformed, or invalid. ```json theme={null} { "error": "Unauthenticated", "code": "UNAUTHENTICATED" } ``` *** ### 403 — Insufficient Token Ability The token is valid but does not include the ability required for the HTTP method. ```json theme={null} { "error": "Token missing required ability: external-api:write", "code": "INSUFFICIENT_TOKEN_ABILITY" } ``` *** ### Authentication Best Practices * Store API keys in a secure secrets manager (never in frontend code) * Set expirations where possible * Rotate keys regularly * Delete unused keys immediately * Send requests server-to-server over HTTPS only *** # Error handling The Weav External API uses predictable HTTP status codes and machine-readable error codes for most authorization and business-rule failures. For client integrations, treat all non-2xx responses as failures, branch first on HTTP status, then on the error code when available. Most endpoint failures use a standard JSON envelope with `error` and optional `code`. Validation failures use Laravel’s validation shape (`message` + `errors`). A small number of endpoint-specific business-state responses may return custom payloads, so clients should handle both patterns safely. ### Error response formats ### Standard API error envelope ```json theme={null} { "error": "Human-readable description", "code": "ERROR_CODE", "errors": {} } ``` * `error` *(string)*: human-readable message * `code` *(string, optional)*: machine-readable identifier * `errors` *(object, optional)*: additional context/details ### Validation errors (422) Use this format when payload/query/path validation fails. ```json theme={null} { "message": "The given data was invalid.", "errors": { "field_name": ["Validation message"] } } ``` ### Endpoint-specific business-state error example (422) Some flows can return a custom shape such as: ```json theme={null} { "success": false, "message": "No completed URLs found to resync" } ``` > Treat this as a non-retryable business-state error unless your app changes input/state before retrying. ### HTTP status codes to handle | Status | Meaning | Typical cause | Retry guidance | | -----: | ----------------------------------- | ----------------------------------------------- | -------------------------- | | 400 | Bad request / business rule failure | Invalid assignment type, invalid type/code path | Usually no | | 401 | Unauthenticated | Missing/invalid bearer token | No (fix auth) | | 403 | Forbidden | Missing token ability or prohibited operation | No (fix permissions/input) | | 404 | Not found | Resource missing or outside workspace scope | No (fix ID/scope) | | 422 | Validation/business-state failure | Invalid fields, unsupported state | No (fix payload/state) | | 500 | Server error | Internal processing/creation failure | Sometimes (with backoff) | ### Common error codes | Code | Status | Description | | ---------------------------- | -----: | --------------------------------------------------------------------------- | | `UNAUTHENTICATED` | 401 | Request is not authenticated | | `INSUFFICIENT_TOKEN_ABILITY` | 403 | Token lacks required ability (`external-api:read` or `external-api:write`) | | `FORBIDDEN` | 403 | Operation blocked by business rule (for example protected agent operations) | | `RESOURCE_NOT_FOUND` | 404 | Resource doesn’t exist in current workspace scope | | `INVALID_SENDER` | 400 | Invalid message sender reference | | `INVALID_ASSIGNEE` | 400 | Invalid assignee reference | | `INVALID_ASSIGNEE_TYPE` | 400 | Assignee type violates conversation/channel rules | | `INVALID_TYPE` | 400 | Unsupported training data type | | `INVALID_AGENT` | 400 | Agent missing or outside current workspace | | `URL_DISCOVERY_REQUIRED` | 422 | URL training must use URL process endpoint | | `NO_URLS_PROVIDED` | 422 | URL process request had no valid URLs | | `PROCESSING_FAILED` | 500 | URL/training processing failed server-side | | `CREATION_FAILED` | 500 | Resource creation failed server-side | ### Best practices * Log status, code, and response body for all non-2xx responses. * Treat 4xx as request/integration issues, 5xx as transient/system issues. * Only retry idempotent operations, with exponential backoff and jitter. * Surface validation details from `errors` directly in developer tooling. # Weav MCP Source: https://docs.weav.com/api-reference/mcp Learn how to connect AI tools to your Weav workspace with the Model Context Protocol (MCP). Authenticate with OAuth, then search conversations, help customers, and update training data. # Model Context Protocol (MCP) > Connect AI tools to your Weav workspace so they can search conversations, help customers, and update your knowledge base. The Weav MCP server lets AI tools access your workspace through the [Model Context Protocol](https://modelcontextprotocol.io/introduction). After a workspace admin or owner completes OAuth consent, those tools can work with conversations, customers, and training data in that workspace. Use it to: * Search and open support conversations from an AI assistant * Look up customer profiles and recent history * Reply to conversations or update status, priority, and assignee * Search, add, resync, or delete knowledge base items Only a workspace **admin** or **owner** can finish consent. Other teammates can start the connection, but Weav will ask an admin or owner to approve it. *** ## What is Model Context Protocol? MCP is a protocol that lets AI tools connect to Weav in a secure, standardized way. It gives models a structured way to: * Find and retrieve Weav data (conversations, customers, and knowledge base items) * Call specific tools Weav exposes * Keep workspace context while you work in an AI assistant *** ## How MCP works Weav hosts a remote MCP server that follows the authenticated remote MCP specification. The server handles requests from AI tools and exposes workspace data through a secure interface. **Connection URL:** `https://mcp.weav.com/mcp` When an AI tool needs access to Weav: 1. The tool connects to `https://mcp.weav.com/mcp`. 2. Weav opens a browser consent screen. Sign in if you are not already signed in. 3. A workspace admin or owner approves access. 4. The tool can call Weav tools for that workspace until the connection is revoked. Use the full URL, including `/mcp`. Discovery metadata advertises this endpoint; the hostname alone is not the MCP server. *** ## Benefits of using MCP * **Secure access** — All data access is authenticated. Consent is limited to admins and owners, and tokens are scoped to one workspace. * **Standardized interface** — The same connection pattern works across MCP-compatible AI tools. * **Workspace context** — Assistants can work with your inbox, customers, and knowledge base instead of copying data by hand. * **Faster support work** — Triage conversations, reply to customers, and update training data from the tools you already use. *** ## Available tools The Weav MCP server provides **11 tools**. Search tools return up to 50 results (default 15). IDs are workspace-scoped UUIDs. ### Conversations #### search\_conversations Search support conversations the same way the Weav inbox does. Only conversations with at least one message are returned. Spam is excluded unless `spam` is `true`. | Parameter | Required | Type | Description | | --------- | -------- | ------- | --------------------------------------------------------------------------------------- | | `query` | No | string | Search subject, customer name, or email. Max 255 characters. | | `status` | No | string | `open` or `closed`. | | `channel` | No | string | `email` or `chat`. | | `spam` | No | boolean | When `true`, return spam conversations instead of inbox conversations. Default `false`. | | `limit` | No | integer | Maximum results (1–50). Default `15`. | #### get\_conversation Get a conversation, including recent messages. | Parameter | Required | Type | Description | | ----------------- | -------- | ------ | ---------------------------------------------- | | `conversation_id` | Yes | string | Conversation UUID from `search_conversations`. | #### send\_reply Post a reply to a conversation as a workspace teammate. | Parameter | Required | Type | Description | | ----------------- | -------- | ------ | ------------------ | | `conversation_id` | Yes | string | Conversation UUID. | | `content` | Yes | string | Reply body. | #### update\_conversation Update a conversation’s status, priority, or assignee. This tool does not delete conversations. | Parameter | Required | Type | Description | | ----------------- | -------- | ------ | --------------------------------------------------------------------- | | `conversation_id` | Yes | string | Conversation UUID. | | `status` | No | string | `open` or `closed`. | | `priority` | No | string | `low`, `normal`, `high`, or `urgent`. | | `assignee_id` | No | string | User or agent UUID. Omit to leave unchanged. Send `null` to unassign. | | `assignee_type` | No | string | `user` or `agent`. Required when setting `assignee_id`. | *** ### Customers #### search\_customers Search customers by name or email. | Parameter | Required | Type | Description | | --------- | -------- | ------- | ------------------------------------- | | `query` | No | string | Search name or email. | | `limit` | No | integer | Maximum results (1–50). Default `15`. | #### get\_customer Get a customer profile, company, and recent conversations. | Parameter | Required | Type | Description | | ------------- | -------- | ------ | -------------------------------------- | | `customer_id` | Yes | string | Customer UUID from `search_customers`. | *** ### Knowledge base #### search\_training\_data Search knowledge base (training data) items by title, description, type, or source. | Parameter | Required | Type | Description | | --------- | -------- | ------- | ---------------------------------------- | | `query` | No | string | Search title, description, or source. | | `type` | No | string | `text`, `url`, `file`, `video`, or `qa`. | | `limit` | No | integer | Maximum results (1–50). Default `15`. | #### get\_training\_data Get a single knowledge base item. | Parameter | Required | Type | Description | | ------------------ | -------- | ------ | ----------------------------------------------- | | `training_data_id` | Yes | string | Training data UUID from `search_training_data`. | #### add\_training\_data Add knowledge base content as text, Q\&A, or a website URL. Every agent in the workspace is given access automatically. MCP can add `text`, `qa`, and `url` sources. File and video sources can be searched if they already exist in Training; they cannot be uploaded through this tool. | Parameter | Required | Type | Description | | ---------- | ---------------------------- | --------- | ----------------------------------------------------------------------------------------------- | | `type` | Yes | string | `text`, `qa`, or `url`. | | `content` | When `type` is `text` | string | The text to train on. | | `title` | No | string | Optional title. Max 255 characters. | | `question` | When `type` is `qa` | string | The question. | | `answer` | When `type` is `qa` | string | The answer. | | `url` | When crawling a site | string | Website URL to crawl. Weav discovers pages on the site and trains on them. Max 2048 characters. | | `urls` | When training specific pages | string\[] | Specific page URLs to train without crawling the rest of the site. Max 100 URLs. | Use `url` for a whole website. Use `urls` when you only want listed pages. #### delete\_training\_data Delete a knowledge base item. For website/URL sources, this also deletes discovered URLs and chunks. Deleting training data cannot be undone from the MCP client. | Parameter | Required | Type | Description | | ------------------ | -------- | ------ | ------------------- | | `training_data_id` | Yes | string | Training data UUID. | #### resync\_training\_data Re-scrape an existing URL knowledge base item. | Parameter | Required | Type | Description | | ------------------ | -------- | ------ | --------------------------------- | | `training_data_id` | Yes | string | UUID of a URL training data item. | *** ## Setting things up ### Authentication The MCP server uses **OAuth**. When you connect, Weav opens a browser consent screen. * Only a workspace **admin** or **owner** can finish consent * Access is scoped to that workspace * Admins can disconnect a client later in Settings There is no API-key or bearer-token shortcut. Connect through OAuth. Path: **Settings → Developers → MCP connections** 1. Open **Settings**. 2. Go to **Developers**. 3. Select **MCP connections**. 4. Review connected clients, or disconnect one to revoke access immediately. *** ### Configuration examples The example below is a generic template. Always refer to your AI tool’s official documentation for the latest MCP setup steps. Details vary between tools and versions. ```json theme={null} { "mcpServers": { "weav": { "command": "npx", "args": [ "mcp-remote", "https://mcp.weav.com/mcp" ] } } } ``` After you save the config, restart the AI tool. The first connection opens a browser window for Weav sign-in and consent. *** ## Permissions The Weav MCP server issues tokens with the `mcp:use` ability. That ability is granted when an admin or owner completes consent for the workspace. If consent is declined, or the connection is disconnected in Settings, tool calls fail until someone reconnects. *** ## Debugging and troubleshooting ### Authentication problems If the browser consent flow is stuck or the client keeps asking you to sign in: ```text theme={null} # Stop existing mcp-remote processes pkill -f mcp-remote # Clear the local MCP auth cache rm -rf ~/.mcp-auth ``` Then restart the AI tool and connect again. ## Connection testing ```text theme={null} # Starts the OAuth browser flow npx mcp-remote https://mcp.weav.com/mcp ``` ## View active MCP connections ```text theme={null} ps aux | grep mcp-remote | grep -v grep ``` ### Error handling * Authentication failures — Restart the OAuth flow. Confirm a workspace admin or owner completed consent. * 401 Unauthorized — The access token is missing, expired, or the connection was revoked in Settings. * Tool errors — Confirm the IDs you pass belong to the connected workspace. ### Troubleshooting tips Check that: * The URL is `https://mcp.weav.com/mcp` (including `/mcp`) * You restarted the AI tool after changing the config * A workspace admin or owner completed the browser consent screen * The client still appears under Settings → Developers → MCP connections * Conversation, customer, and training data IDs are UUIDs from this workspace If a client is stuck, disconnect it in Settings and connect again. # Create message Source: https://docs.weav.com/api-reference/messages/create-message /api-reference/openapi.json post /messages Note: API currently validates sender_type as customer|user. The API does not accept `metadata` or `is_ai_assisted` in requests. # Delete message Source: https://docs.weav.com/api-reference/messages/delete-message /api-reference/openapi.json delete /messages/{id} # Get message Source: https://docs.weav.com/api-reference/messages/get-message /api-reference/openapi.json get /messages/{id} # List messages Source: https://docs.weav.com/api-reference/messages/list-messages /api-reference/openapi.json get /messages # Check if a URL already exists Source: https://docs.weav.com/api-reference/training-data/check-if-a-url-already-exists /api-reference/openapi.json get /training-data/url/exists # Create training data Source: https://docs.weav.com/api-reference/training-data/create-training-data /api-reference/openapi.json post /training-data Supported types: - text: requires content - file: requires multipart file upload - video: requires video_url - qa: requires question + answer - url: not accepted directly in this endpoint (use POST /training-data/url/process) The API does not accept `metadata` in requests. # Delete training data Source: https://docs.weav.com/api-reference/training-data/delete-training-data /api-reference/openapi.json delete /training-data/{id} # Get training data Source: https://docs.weav.com/api-reference/training-data/get-training-data /api-reference/openapi.json get /training-data/{id} # List training data Source: https://docs.weav.com/api-reference/training-data/list-training-data /api-reference/openapi.json get /training-data # Manually trigger URL resync Source: https://docs.weav.com/api-reference/training-data/manually-trigger-url-resync /api-reference/openapi.json post /training-data/{id}/resync-now # Process URLs into training data Source: https://docs.weav.com/api-reference/training-data/process-urls-into-training-data /api-reference/openapi.json post /training-data/url/process Creates URL training data from the provided URLs. In production, URL processing jobs are queued and run asynchronously. # Update training data Source: https://docs.weav.com/api-reference/training-data/update-training-data /api-reference/openapi.json put /training-data/{id} The API does not accept `metadata` in requests. # Webhook delivery Source: https://docs.weav.com/api-reference/webhooks/webhook-delivery /api-reference/openapi.json webhook organization.event When subscribed events occur, Weav sends an HTTPS POST request to your configured webhook URL. Verification headers: - `X-Weav-Event`: event type - `X-Weav-Signature`: HMAC SHA-256 of the raw JSON body using your webhook secret - `Content-Type`: `application/json` Delivery behavior: - Any `2xx` response is treated as success - `410 Gone` deactivates the webhook immediately - Other non-2xx responses are retried up to 10 attempts with exponential backoff (1m, 2m, 4m, ...) - Webhooks are auto-deactivated after repeated permanent failures This section is reference-only to document payload shape and verification guidance. # Add DNS records at your domain provider Source: https://docs.weav.com/inbox/dns-settings Configure the DKIM and Return Path DNS records at Cloudflare, GoDaddy, Namecheap, or Squarespace so you can send email from your custom domain in Weav. ## Overview To send email from your own domain (e.g. [support@yourdomain.com](mailto:support@yourdomain.com)) through Weav, you must add **two DNS records** at the place where your domain’s DNS is managed. Weav will show you the exact values when you set up outbound messaging for a domain. **The two records Weav uses:** 1. **DKIM (TXT record)** – Proves that messages sent from Weav are authorized for your domain. This supports DKIM alignment for DMARC so your emails are more likely to reach the inbox. 2. **Return Path (CNAME record)** – Sets the return-path domain used when Weav sends mail for you. This supports SPF alignment for DMARC. You add these in your **domain provider’s DNS settings** (e.g. Cloudflare, GoDaddy, Namecheap, Squarespace), then return to Weav and click **Verify** so Weav can confirm they’re correct. **Where to get the values in Weav:**\ Go to **Settings → Email**, add or select the domain you’re verifying, and open **Setup outbound messaging**. You’ll see: * **DKIM (TXT):** a **Key** (host name) and **Value** (TXT content) * **Return Path (CNAME):** a **Key** (host name) and **Value** (target the CNAME points to) Copy the **Key** and **Value** from Weav into your provider’s DNS screens as described below. Use the exact values shown in Weav; do not substitute example.com or other placeholders. **Note:** Some DNS providers want the **full host name** (e.g. `pm._domainkey.yourdomain.com`) in the “Name” or “Host” field, while others want only the **subdomain part** (e.g. `pm._domainkey`). If a provider’s docs say to use the full domain, enter the Weav host as a full name (e.g. `pm._domainkey.yourdomain.com`). Check your provider’s documentation for their rules. *** ## Cloudflare 1. Log in at [https://dash.cloudflare.com/login](https://dash.cloudflare.com/login) with your Cloudflare account. 2. On the homepage, select the **domain** you want to authenticate from the domains table. 3. In the left sidebar go to **DNS** → **Records**. 4. **Add the DKIM TXT record:** * Click **Add record** and choose type **TXT**. * In **Name**, enter the DKIM host from Weav (e.g. `pm._domainkey` or the full name if your provider requires it). * In **Content**, paste the DKIM **Value** from Weav. * Set **TTL** to **Auto** (or 3600 if Auto is not available). Save the record. 5. **Add the Return Path CNAME record:** * Click **Add record** and choose type **CNAME**. * In **Name**, enter the Return Path host from Weav. * In **Target**, paste the Return Path **Value** from Weav. * Set **Proxy status** to **DNS only** (grey cloud). Do not proxy CNAME records used for email. * Set **TTL** to **Auto**. Save the record. 6. Return to Weav, open the outbound setup for that domain, and click **Verify**. **If verification fails in Weav:** * Ensure the CNAME is **DNS only**, not **Proxied** (orange cloud). * Ensure **CNAME flattening** is not applied to this CNAME (use DNS only so the record is a normal CNAME). See [Cloudflare’s guide to DNS records](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/) for more detail. *** ## Squarespace 1. Log in at [https://login.squarespace.com/](https://login.squarespace.com/) with your Squarespace account. 2. Click **Domains** (next to the Dashboard tab) and select the **domain** you want to authenticate. 3. In the left-hand menu select **DNS**. 4. Scroll to the **Custom records** section and add the records: **DKIM (TXT):** * Click **Add record** and choose type **TXT**. * In **Host**, enter the DKIM host from Weav. * In **Text data** (or **Value**), paste the DKIM **Value** from Weav. Save the record. **Return Path (CNAME):** * Click **Add record** and choose type **CNAME**. * In **Host**, enter the Return Path host from Weav. * In **Alias data** (or **Target**), paste the Return Path **Value** from Weav. Save the record. 5. Return to Weav and click **Verify** for that domain. *** ## GoDaddy 1. Log in at [https://sso.godaddy.com/](https://sso.godaddy.com/) with your GoDaddy account. 2. In the left menu go to **Domain**, then click **Manage DNS** for the domain you want to authenticate. 3. **Add the DKIM TXT record:** * Click **Add new record** and choose type **TXT**. * In **Name**, enter the DKIM host from Weav. * In **Value**, paste the DKIM **Value** from Weav. * Set **TTL** if required (e.g. ½ hour or 3600). Save the record. 4. **Add the Return Path CNAME record:** * Click **Add new record** and choose type **CNAME**. * In **Name**, enter the Return Path host from Weav. * In **Value** (or **Points to**), paste the Return Path **Value** from Weav. * Set **TTL** if required (e.g. ½ hour). Save the record. 5. Return to Weav and click **Verify** for that domain. See [GoDaddy’s guide to managing DNS records](https://www.godaddy.com/help/add-a-cname-record-19236) for more detail. *** ## Namecheap 1. Log in at [https://www.namecheap.com/myaccount/login/](https://www.namecheap.com/myaccount/login/) with your Namecheap account. 2. Go to **Domain list** in the left menu, then click **Manage** for the domain you want to authenticate. 3. Open **Advanced DNS** and in the **Host Records** section click **Add New Record**. 4. **Add the DKIM TXT record:** * Choose **TXT Record**. * In **Host** (or **Name**), enter the DKIM host from Weav. * In **Value**, paste the DKIM **Value** from Weav. * Set **TTL** to **Automatic** (or 3600). Save the record. 5. **Add the Return Path CNAME record:** * Click **Add New Record** and choose **CNAME Record**. * In **Host**, enter the Return Path host from Weav. * In **Target**, paste the Return Path **Value** from Weav. * Set **TTL** to **Automatic**. Save the record. 6. Return to Weav and click **Verify** for that domain. See [Namecheap’s guide to host records](https://www.namecheap.com/support/knowledgebase/article.aspx/319/2237/how-can-i-set-up-an-a-address-record-for-my-domain/) for general DNS guidance. *** ## After adding the records * **Propagation:** DNS changes can take from a few minutes up to 24–48 hours. If **Verify** in Weav fails at first, wait a bit and try again. * **Verify in Weav:** In **Settings → Email**, open the outbound setup or DNS view for the domain and click **Verify**. Weav checks the records; when both DKIM and Return Path are correct, the domain is marked verified and you can send from that domain in Weav. * **Typo check:** Ensure there are no extra spaces or missing parts in the **Name**/Host and **Value**/Target you pasted. Some providers add the domain automatically to the host—if so, enter only the part Weav shows (e.g. `pm._domainkey`) unless the provider’s docs say otherwise. # Email forwarding Source: https://docs.weav.com/inbox/email-forwarding How to forward emails from your email address to Weav using Google Workspace, Microsoft 365, or other providers. ## Overview To receive customer emails in Weav, you forward messages from your support address (e.g. [support@yourdomain.com](mailto:support@yourdomain.com)) to your **Weav inbox address** (e.g. @[weav-mail.com](http://weav-mail.com)). Weav then turns those emails into conversations in your inbox. **What you need:** 1. Your **Weav inbox address** – You get this in Weav under **Settings → Email**. Add your support email address, then open **Setup inbound messaging** by clicking on the Verify button in the incoming column and copy the address shown (it looks like `workspace@weav-mail.com`). 2. **Admin or mailbox access** at your email provider so you can change forwarding or routing rules. 3. After configuring forwarding at your provider, return to Weav and use **Send test email** so Weav can verify that forwarding is working. Use the instructions below for your provider. For **Google Workspace** and **Microsoft 365**, we include step-by-step guidance. For **other providers** (e.g. Gmail, Outlook.com, iCloud), we summarize options and limitations. *** ## Configure email forwarding in Google Workspace This method is **recommended** for Google. It uses routing rules instead of a single mailbox, so it avoids per-user rate limits and you don’t need to create a dedicated mailbox. **You need:** Administrator access to Google Workspace. ### Step-by-step 1. Log in to the **Google Workspace Admin Console** at [https://admin.google.com/](https://admin.google.com/) with an admin account. 2. Go to **Apps** → **Google Workspace** → **Gmail**. 3. In the **Gmail** settings, find **Default routing** and click **Configure** to add a new routing rule. 4. When adding the rule: * In **Envelope recipient**, enter the support address that should be forwarded (e.g. [support@yourdomain.com](mailto:support@yourdomain.com)). * Under the envelope recipient option, choose **Change envelope recipient** and in **Replace recipient** enter your **Weav inbox address** (the one you copied from Weav, e.g. [yourworkspace@weav-mail.com](mailto:yourworkspace@weav-mail.com)). * Save the rule in the Admin Console. 5. Edit the rule you just created and in **Options** set: * **Perform this action on non-recognized and recognized addresses.** 6. In Weav, go to **Settings → Email**, open the inbound setup for that address, and click **Send test email** to verify forwarding. 7. **Check:** In Gmail settings, ensure the option to **disable forwarding** is not turned on for the affected address, or it can block messages from reaching Weav. **Note:** Changes in Google Workspace can take up to 24 hours to apply, though they often work sooner. *** ## Configure email forwarding in Microsoft 365 **You need:** Access to the Microsoft 365 Admin Center (admin or appropriate permissions). ### Step-by-step 1. Log in to the **Microsoft 365 Admin Center** at [https://admin.microsoft.com/](https://admin.microsoft.com/) with your admin account. 2. Choose the mailbox you want to forward: * **Shared mailbox:** Go to **Teams & groups** → **Shared mailboxes**, select the mailbox, then in **Email forwarding** click **Edit**. * **User mailbox:** Go to **Users** → **Active users**, select the user, open the **Mail** tab, and in **Email forwarding** click **Manage email forwarding**. 3. Turn on **Forward all email sent to this mailbox** and enter your **Weav inbox address** (the one you copied from Weav). Save and exit the Admin Center. 4. In Weav, go to **Settings → Email**, open the inbound setup for that address, and click **Send test email** to verify forwarding. **Important:** * Configure forwarding in the **Microsoft 365 Admin Center**, not in Outlook on the web (OWA). * If you see **"Your organization does not allow external forwarding"**, your admin must allow external forwarding (e.g. in the Microsoft Defender portal under anti-spam outbound policy). Changes can take up to an hour to apply. * If your organization uses strict outbound policies, ensure **automatic forwarding** is allowed in the relevant anti-spam/outbound policy before verifying in Weav. *** ## Configure email forwarding in other providers These methods work for **low volume** only. Provider rate limits can delay or block messages if you exceed them. ### Gmail (personal or non–Google Workspace) * Use **Settings → Forwarding and POP/IMAP** and add a forwarding address. Enter your Weav inbox address. * Be aware: Gmail limits how many messages you can send per day and how many recipients per message; forwarding counts toward those limits. * Avoid using **Google Groups** as the forwarding step if it changes the **From** header; that can break threading and identification in Weav. Prefer direct mailbox forwarding or, for higher volume, Google Workspace routing (see above). ### Outlook (outlook.com / personal) * Prefer **redirect** over **forward** when your provider offers both. Redirect keeps the original sender, so replies and threading in Weav stay correct. Forward can make messages appear “from” the mailbox and may break threading. * Configure in the web Outlook settings (e.g. **Mail → Forwarding**) and enter your Weav inbox address. ### iCloud Mail * Use **Settings → Mail → Forwarding** (or the equivalent in your iCloud Mail settings) and add your Weav inbox address. * Suitable for low volume; watch for any iCloud sending or forwarding limits. ### General recommendation * Use a **direct mailbox** for forwarding when possible so the original sender and headers are preserved. * Avoid setups that change or strip the **From** header (e.g. some Google Groups configurations). Use **Google Workspace Default Routing** for higher volume with a Gmail/Workspace address. # Set up a custom email Source: https://docs.weav.com/inbox/forward-emails-to-weav Connect your own email address (like help@yourcompany.com) so your team can send and receive branded emails in Weav. ## Overview A custom email lets your workspace use branded addresses like `help@yourcompany.com` instead of only the default Weav address. Every workspace already has an internal fallback email: [workspace@weav-mail.com](mailto:workspace@weav-mail.com) You can configure a custom address for: * **Inbound** (receive customer emails in Weav) * **Outbound** (send emails from your domain) * **Both** (two-way email) Inbound and outbound are verified separately: * Inbound requires a successful forwarding test * Outbound requires domain authentication (DKIM + Return-Path) ## Before you begin Make sure you have: * Access to **Settings → Inbox Settings** in Weav * Access to your mailbox provider settings (Gmail, Outlook, etc.) * Access to your DNS provider (Cloudflare, GoDaddy, Namecheap, etc.) *** ## Step 1: Add a custom email address

1. Go to **Settings → Inbox Settings** 2. Click **Add Email Address** 3. Enter your address (example: `help@yourcompany.com`) 4. Choose usage: * Inbound * Outbound * Both 5. Save When you add a non-`weav-mail.com` address, Weav automatically links it to the domain for your workspace. *** ## Step 2: Configure inbound email (receiving) Inbound works by forwarding your custom mailbox to your workspace’s internal Weav address. Forward

### 2.1 Copy your internal Weav address In Inbox Settings, copy: [workspace@weav-mail.com](mailto:workspace@weav-mail.com) ### 2.2 Create forwarding in your mailbox provider Create a forwarding rule so emails sent to your custom support address are forwarded to the internal Weav address ([workspace@weav-mail.com](mailto:workspace@weav-mail.com)). ### 2.3 Run **Test Forwarding** in Weav 1. In Weav, click **Test Forwarding** for that email address 2. Weav sends a test message from `Weav ` 3. If forwarding is configured correctly, the address will automatically be marked verified for inbound use when we detect the forwarded email If inbound is enabled before verification, Weav will block it until forwarding is verified. *** ## Step 3: Configure outbound email (sending) Outbound requires domain authentication to improve deliverability and trust. Dns

### 3.1 Open domain setup in Weav Weav provides the DNS records required for your domain (typically DKIM and Return-Path CNAMEs). ### 3.2 Add records in your DNS provider Add the exact records shown in Weav. ### 3.3 Verify domain in Weav After DNS propagation, verify/refresh domain status in Weav. * If checks pass, status becomes **Verified** * If DNS is still propagating, status remains **Pending** until checks complete Outbound cannot be enabled until domain verification is complete. This can take up to 24-48 hours. *** ## Status reference | Status | Meaning | What to do | | :--------- | :----------------------------------------- | :------------------------------------- | | Verified | Setup is complete for that step | No action needed | | Pending | Waiting for DNS or forwarding confirmation | Wait a few minutes, then refresh/retry | | Not tested | Forwarding test has not been run | Run Test Forwarding | | Failed | Verification did not pass | Review setup and retry | *** ## Common errors and fixes ### “Cannot enable inbound email until email is verified” Run **Test Forwarding** and confirm your custom mailbox forwards to `{workspace}@weav-mail.com`. ### “Cannot enable outbound email until domain is verified” Check DNS records, wait for propagation, then refresh verification in Weav. ### “Cannot set as default outbound unless outbound is enabled” Enable outbound first (requires verified domain), then set default outbound. ### “This domain is already being used by another organization” That domain is already connected to another workspace. Use a different domain or disconnect it there first. *** ## Best practices * Use team aliases like `support@`, `help@`, or `billing@` * Keep forwarding enabled for reliable inbound delivery. Don't disable it after setup is complete or it will stop working * Do not remove DNS authentication records after setup * Keep one default outbound sender for consistency *** ## FAQ ### Can I add multiple custom email addresses? Yes. A workspace can have multiple custom addresses. ### Do I need to own the domain? Yes. You need DNS control for outbound setup. ### Can I remove a domain later? Yes, but only after no email addresses are using that domain. # Connect a Google Workspace Group inbox Source: https://docs.weav.com/inbox/google-groups-setup ## Overview A **Google Group** is a shared address (like `support@yourcompany.com`) that delivers email to several people at once. It’s not a normal mailbox — it’s more like a list. That makes connecting it to Weav slightly different from connecting a regular email address. You have two ways to connect a Google Group to Weav. Both work; one needs Google Workspace **admin** access, and one only needs **Group owner** access. | Method | Who can do it | When to use it | | :-------------------------------- | :------------------------- | :----------------------------------------------------------------------------------------------------------------- | | **Default Routing (recommended)** | Google Workspace **admin** | You want the cleanest setup. Works for any group, with no changes to the group itself. | | **Add Weav as a Group member** | **Group owner** | You don’t have admin access to Google Workspace, or you want the group to keep working normally for your team too. | This guide covers the **inbound** side — receiving customer emails sent to your group. To **send replies** from your group address (e.g. `support@yourcompany.com`), you’ll also need to set up your domain — see [Add DNS records at your domain provider](/inbox/dns-settings). *** ## Before you begin Make sure you have: * A Google Group already set up (e.g. `support@yourcompany.com`) * Either **Google Workspace admin** access (for Method 1), **or** access to manage your Group as an **owner** (for Method 2) * Access to **Settings → Inbox Settings** in Weav You’ll also need your **Weav inbox address** — a special address Weav gives you that looks like `workspace@weav-mail.com (This is only an example, use the workspace email given to you in Weav)`. You’ll see it in Weav after you add your group address. *** ## Step 1: Add your group address in Weav Do this in **Weav** first — it gives you the Weav inbox address you’ll need on the Google side. 1. In Weav, go to **Settings → Email** 2. Click **Add Email Address** 3. Enter your **Group’s email address** (e.g. `support@yourcompany.com`) 4. Choose: * **Inbound** if you only want to receive emails into Weav * **Both** if you also want to send replies from this address 5. Click **Save** 6. Find your new address in the list and click **Verify** in the **Incoming** column. Weav will show you an internal address that looks like `workspace@weav-mail.com` — **copy this address**, you’ll paste it into Google in the next step. Keep this Weav tab open. After you finish the Google steps, you’ll come back here to run the **Test Forwarding** step. *** ## Step 2: Send group emails to Weav (pick one method) ### Method 1: Default Routing (recommended, requires Google Workspace admin) This is the cleanest setup. You’ll add a routing rule in the Google Workspace Admin Console that automatically sends emails for your group address to Weav. The group itself doesn’t change — your team can still receive group mail normally. #### In Google Workspace 1. Sign in to the **Google Workspace Admin Console** at [admin.google.com](https://admin.google.com) with an admin account. 2. Go to **Apps → Google Workspace → Gmail**. 3. Scroll to **Default routing** and click **Configure**. 4. Set up the rule: * In **Envelope recipient**, choose **Single recipient** and enter your **group address** (e.g. `support@yourcompany.com`). * In the action section, check **Also deliver to** and enter the **Weav inbox address** you copied in Step 1 (e.g. `workspace@weav-mail.com`). * Under **Options**, select **Perform this action on non-recognized and recognized addresses**. 5. Click **Save** at the bottom of the rule. We use **Also deliver to**, not **Change envelope recipient**. This way, your group keeps receiving messages as it does today — Weav just gets a copy. #### In Weav 1. Return to **Settings → Inbox Settings**. 2. Click **Test Forwarding** (or the **Verify** button) for your group address. 3. Weav sends a test email from `Weav `. As soon as that test email reaches Weav through your routing rule, the address is automatically marked verified. Default Routing changes can take up to **24 hours** to apply, though they often work within a few minutes. If verification doesn’t succeed right away, wait a few minutes and click **Test Forwarding** again. *** ### Method 2: Add Weav as a Group member (no admin access needed) Use this method if you’re a Group owner but **not** a Workspace admin. You’ll add your Weav inbox address as an external member of the Group, so Google delivers a copy of every group email to Weav. #### In Google Groups 1. Go to **Google Groups** at [groups.google.com](https://groups.google.com) and open your group (e.g. `support@yourcompany.com`). 2. In the left menu, click **Members**. 3. Click **Add members**. 4. In **Group members**, paste your **Weav inbox address** (the `workspace@weav-mail.com` address you copied in Step 1). 5. Set **Subscription** to **Each email** (so every message is delivered, not digested). 6. Click **Add members**. If you see an error like “**External members aren’t allowed**” or “**This domain doesn’t allow external members**,” your Workspace administrator has external members disabled. Either ask them to allow external members for this group, or use **Method 1** instead. #### Check your group settings (still in Google) A few group settings can quietly block emails from reaching Weav. Confirm these: 1. In your Group, go to **Group settings → Posting policies**: * **Who can post**: set to **Anyone on the web** (or at minimum, allow posts from outside your organization). If only members can post, customer emails will be rejected. * **Message moderation**: set to **No moderation**. If messages are held for moderation, the verification email will sit in a queue and the test will fail. 2. In **Group settings → Email options**: * Make sure **Subject prefix** is empty (or be aware Weav will see it on every subject line). If your Workspace admin requires moderation for external posts, ask them to **allow** `hello@weav.com` so the Weav verification test isn’t held in moderation. #### In Weav 1. Return to **Settings → Inbox Settings**. 2. Click **Test Forwarding** (or the **Verify** button) for your group address. 3. Weav sends a test email from `Weav ` to your group. If your group settings are correct, the test will be delivered to Weav and the address will be marked verified within a couple of minutes. *** ## Step 3: Send outgoing emails from your group address If you also want to **send** replies from `support@yourcompany.com` (instead of from the default `workspace@weav-mail.com`), you’ll need to authenticate your domain. Follow [Add DNS records at your domain provider](/inbox/dns-settings) to add the **DKIM** and **Return-Path** records Weav shows you. Once your domain is verified, replies from Weav will go out as your group address. You don’t need to do this just to **receive** group emails. It’s only required if you want outbound messages from Weav to appear as coming from your group address. *** ## Common issues and fixes ### The verification test never succeeds The test email is sent from `Weav ` and has to reach Weav within **5 minutes**. Most failures fall into one of these buckets: * **Method 1 (Default Routing):** The rule may still be propagating. Wait a few minutes and try again. * **Method 2 (External member):** Your group is holding the test message for moderation. Approve the moderated message, or set **Message moderation** to **No moderation** and rerun the test. * **Either method:** Your group rejects external senders. Allow posts from outside your organization, or whitelist `hello@weav.com`. ### Customer emails come into Weav, but the customer is wrong (it shows as your group address) This happens when Google Groups **rewrites the sender** to be the group address. To fix it: 1. In your Google Group, go to **Group settings → Posting policies**. 2. Look for any setting like **Post replies to → the group** or **Set sender as group**. Change it so replies and posts go to the **original author**, not to the group. 3. If you can’t change this, switch to **Method 1 (Default Routing)** — Default Routing preserves the original sender automatically. ### Customer emails are being marked as spam in Weav Forwarding through a group can break SPF, which raises the spam score on relayed messages. Fix this by adding the customer’s domain (or a partner domain) to your **Trusted Senders** list: 1. In Weav, go to **Settings → Email → Preferences.** 2. Find **Trusted Domains** and add the domain (e.g. `customerdomain.com`). 3. Emails from that domain will skip spam filtering. ### Replies from my team aren’t threading correctly Make sure your Google Group isn’t configured to rewrite the **Message-ID** header. The default Google Group settings preserve it. If you’ve enabled **conversation history** rewriting or moderation that modifies headers, switch to **Method 1 (Default Routing)** instead. ### My team still wants to see group emails in Gmail Both methods support this: * **Method 1 (Default Routing)** uses **Also deliver to**, so your team keeps receiving group mail in Gmail and Weav gets a copy. * **Method 2 (External member)** keeps the group itself working — you’ve just added Weav as an additional member. *** ## Status reference | Status | Meaning | What to do | | :--------- | :-------------------------------------------------- | :------------------------------------------------- | | Verified | Your group is connected and forwarding to Weav | No action needed | | Pending | Waiting for the verification test to arrive at Weav | Wait a few minutes, then click **Test Forwarding** | | Not tested | You haven’t run the forwarding test yet | Click **Test Forwarding** | | Failed | The test didn’t reach Weav within 5 minutes | Check group settings (above), then retry | *** ## FAQ ### Do I need admin access to Google Workspace? Only for **Method 1 (Default Routing)**. **Method 2** works with just Group owner access. If you’re unsure which you have, try Method 2 first — if Google blocks you from adding an external member, you’ll know you need admin help (or Method 1). ### Will my team still get group emails in their personal inbox? Yes, with either method. Method 1 sends Weav a copy via routing; Method 2 just adds Weav as another group member. ### Can I connect more than one group to Weav? Yes. Repeat these steps for each group address you want to connect. ### Can I connect a group from a different domain? Yes. The setup is the same — you add the group’s address in Weav and configure forwarding (or membership) on the Google side. # Explore Source: https://docs.weav.com/index Welcome to [Weav](https://weav.com)! We're thrilled to help you transform how you connect with your customers. Weav is a comprehensive customer support platform built for modern businesses. By combining highly capable AI Agents with a unified multi-channel inbox, Weav empowers your team to deliver world-class, 24/7 customer service without overwhelming your human support staff. Whether a customer reaches out via your website chat widget or email, Weav ensures they receive an instant, accurate response—and seamlessly escalates to your human team when necessary. Below are a few key terms you'll encounter in the Weav platform: **Workspace & Users**: Invite your team members, assign roles, and manage your custom routing settings. **Agents**: Your AI-powered assistants. You can customize their appearance, tone, and quick-reply prompts to perfectly match your brand's voice. **Knowledge Sources**: The materials (URLs, PDFs, text, FAQs, and videos) you use to train your Agents. The better the training data, the smarter your AI becomes. **Conversations**: A unified thread of messages between a customer and your business. Conversations track priority, status, and assignment (whether handled by AI, a human assignee, or both). **Customers & Companies**: Rich profiles automatically built as users interact with your support channels, allowing you to track lifetime interactions, contact identifiers, and context. Your Quick Start Journey Ready to get started? Follow these steps to get Weav up and running in minutes: Set up your Organization, invite team members, and define roles. Customize your Agent's behavior and appearance. Upload FAQs, links and your website Set up your custom emails and embed your chatbot widget. # Custom actions Source: https://docs.weav.com/integrations/custom-actions A guide explaining how to connect AI agents to 3rd party API's AI agent custom actions

A guide explaining how to connect AI agents to 3rd party API's Custom actions turn your AI agents from “answering questions” into actually resolving them by leveraging 3rd party API's. With custom actions, your Weav agents don’t just respond, they **reach into your systems, take action, and complete the job**. That’s the difference between deflection and resolution. Use them to connect your agents to your backend, internal tools, or third-party APIs so they can do things like look up orders, update subscriptions, or trigger workflows in real time. *** ## What are custom actions? Custom actions let your Weav agents call your own HTTPS APIs during a conversation. Instead of stopping at “Here’s what I found,” your agent can: * Fetch live data from your systems * Perform approved actions on behalf of the customer * Return structured results and use them to generate a complete answer *** ## When to use custom actions Use a custom action when the agent needs to call an external API during a conversation. **Strong use cases:** * Looking up order status from your ecommerce system * Checking subscription, invoice, or billing information * Creating a support ticket in an internal tool * Updating a booking or appointment * Fetching account details from your backend * Starting a return, exchange, or cancellation flow **Rule of thumb:**
If the answer lives outside Weav, use a custom action. Custom actions work best when your API: * Has a clear, single purpose * Returns structured JSON * Requires defined inputs (like order ID or email) *** ## Before you start You’ll need: * An HTTPS API endpoint * A JSON response from that endpoint * Any required request headers (like authorization) * A clear idea of when the agent should use the action * The inputs the agent must collect before calling it Custom action URLs must start with `https://`. The API response must be valid JSON. *** ## Create a custom action **Path:** Settings → Integrations → Custom Action 1. Open **Settings** 2. Go to **Integrations** 3. Select **Custom Action** 4. Click **Create custom action** *** ## General settings ### Name A short, internal name that clearly describes the action. **Good examples:** * `Look up order status` * `Create return request` * `Check subscription` * `Update appointment` **Best practices:** * Use action-oriented language * Be specific about what the action does * Avoid vague names like `API call` *** ### When to use This is the most important field. It tells the agent: * **When** to call the action * **What** to collect first * **How** to use the response **Good example:** > Use this action when a customer asks about the status of an order, shipment, or delivery. Before calling the action, collect the customer's order ID and email address. Use the response to explain the current order status, estimated delivery date, and tracking link if available. **Bad example:** > Use this to get order info. *** ## API request Screenshot 2026 04 26 At 10 37 35 AM

### Method Choose the HTTP method your API expects: * `GET` → read data * `POST`, `PUT`, `PATCH`, `DELETE` → change data or trigger workflows *** ### HTTPS URL Enter the endpoint Weav should call. ```text theme={null} https://api.example.com/orders/{{order_id}} ``` Use variables with double curly braces: ```text theme={null} {{order_id}} ``` Weav replaces these with values collected by the agent. *** ### Request parameters Screenshot 2026 04 26 At 10 39 08 AM

Optional query or request parameters. Use request parameters when your API expects values in the query string or parameter list. *** ### Request headers Screenshot 2026 04 26 At 10 40 42 AM

Optional HTTP headers. Use headers for authentication, content type, or other API requirements. Do not expose private API keys or secrets to customers. Only add credentials that should be used server-side by the custom action. *** ### Request body For `POST`, `PUT`, or `PATCH`: ```json theme={null} { "order_id": "{{order_id}}", "customer_email": "{{customer_email}}", "reason": "{{return_reason}}" } ``` *Must be valid JSON.* *** ## Input variables Input variables are values the agent can or should collect and pass into the API request. If a variable is required, the agent will try to collect the information from the customer. | Name | Type | Description | Required | | ----------------- | ------- | ------------------------ | -------- | | order\_id | Text | The customer's order ID | Yes | | customer\_email | Text | Email used for the order | Yes | | include\_tracking | Boolean | Include tracking details | No | *** ## User verification Enable Requires user verification when the action should only run after the customer verifies their identity. Use verification for actions that expose or change sensitive information, such as: * Billing details * Subscription changes * Account updates * Personal customer data * Order changes or cancellations **Important**: If verification is off, the action can run without asking the customer to verify first. *** ## Data access Data access controls how much of the API response the agent can use. ### **Full** The agent can use the full JSON response. Use this when: * The response is small * The response does not include sensitive fields * All returned data is safe and useful for the agent ### **Limited** The agent can only use selected response paths. Use this when: * The API returns sensitive data * The response is large * The agent only needs a few fields * You want more control over what can be used in replies Example allowed response paths: * data.status * data.tracking\_url * data.estimated\_delivery If the API returns more fields, Weav will restrict the agent to only the paths you allow. Limited data access is recommended for most production actions. It keeps the agent focused on the fields it needs. *** ## Action status Action status controls whether agents can use the custom action. * Active actions can be used by assigned agents * Inactive actions cannot be used by agents Use inactive status when you are still configuring an action, updating an API, or temporarily disabling access. *** ## Assign the action to agents Screenshot 2026 04 26 At 10 43 15 AM

After creating the custom action, choose which agents can use it. 1. Open Settings → Integrations. 2. Select Custom Action. 3. Find the action. 4. Click Manage access. 5. Select the agents that should be allowed to use it. 6. Save your changes. *** ## **Troubleshooting** ### The action is not being used Check that: * The action is active * The action is assigned to the correct agent * The “When to use” instructions are specific enough * The agent has enough required inputs to call the action *** ### The API request fails Check that: * The URL starts with `https://` * The endpoint is reachable from the internet * Required headers are configured * Required input variables are present * The request body is valid JSON * The API returns a JSON response *** ### The response is too large Custom action responses should be small and focused. If your API returns too much data: * Use Limited data access * Return fewer fields from your API * Create a dedicated endpoint for the agent * Avoid returning large arrays or full customer records # Customer verification for agent actions Source: https://docs.weav.com/integrations/customer-verification Learn how Weav verifies customers before AI agents use sensitive custom actions and integration tools. Customer verification helps protect customers when an agent needs to use a sensitive action or integration tool. Some custom actions and integration tools can access private information or make changes in another system. For example, an agent might look up billing data in Stripe, create a billing portal link, update account details, or call one of your own internal APIs through a custom action. Verification adds a customer identity check before the action runs. This article explains how verification works for customer-facing chat and email conversations. It also explains what changes when the action is a custom action compared with a connected integration tool. *** ## What verification does When verification is required, Weav pauses the action before it runs. The customer verifies by email using a one-time 6-digit code. After the code is accepted, Weav resumes the saved action and gives the result back to the agent so it can continue helping the customer. Verification is conversation-specific. After a customer verifies in a conversation, Weav opens a short verification session for that same conversation so follow-up actions do not immediately ask the customer to verify again. Verification confirms access to the email address the customer provides. It does not replace your team's policies for refunds, cancellations, account ownership, or billing changes. *** ## When verification is required For [custom actions](/integrations/custom-actions), verification is controlled by the custom action setting. When you create or edit a custom action, enable Requires customer verification if the action should only run after the customer verifies their email. For integrations like [Stripe](/integrations/stripe), verification is controlled by the integration tool. Some tools are read-only, some tools update data, and some tools expose sensitive records. Weav can require verification for specific integration tools based on the risk of the action. For example, Stripe tools require verification because the agent can access billing, invoice, customer, and subscription data. *** ## How chat verification works AI Agent Verification

In chat conversations, verification happens inside the chat experience. When an agent tries to use a verified custom action or integration tool, Weav pauses the action and shows the customer a verification card. The card asks for an email address first. After the customer submits the email, Weav sends a 6-digit code to that address and the card changes to ask for the code. AI Agent Verification Code

After the customer enters the correct code, Weav marks verification as successful and resumes the action that was waiting. The agent then receives the action result and can continue the conversation naturally. If the customer enters the wrong code, they can try again. If they need a new code, they can resend it. If they do not want to continue, they can cancel verification and the action will not run. *** ## How email verification works Email conversations use a different flow because there is no interactive verification card inside an email thread. When an agent needs to use a verified custom action or integration tool in an email conversation, Weav pauses the action and tells the agent to ask which email address the customer wants to verify. Weav does not automatically assume the customer's From address is the right email to verify. This matters because forwarded messages, shared inboxes, aliases, and support delegates can all make the sender address unreliable. After the customer replies with an email address, the agent submits that email for verification. Weav then prepares the 6-digit code. The code is sent only after the agent's acknowledgement reply goes out, so the customer is told what is happening before the verification email arrives. The customer then replies with the 6-digit code. The agent submits the code, Weav verifies it, and the saved action resumes. Once the action finishes, the agent can answer the original question using the result. In practice, the email flow usually looks like this: ```txt theme={null} Customer: Can you check my invoice? Agent: I can help with that. For security, which email address would you like to verify? Customer: alex@example.com Agent: Thanks. I am sending a 6-digit verification code to alex@example.com. Please reply with that code. Customer: 123456 Agent: Thanks, you are verified. I found your latest invoice... ``` *** ## Troubleshooting ### The customer is asked to verify This means the agent tried to use a custom action or integration tool that requires verification. The action has not run yet. Once the customer completes verification, Weav resumes the saved action. ### The customer did not receive a code Ask the customer to check the email address they entered and look in spam or junk folders. In chat, they can resend the code from the verification card. In email, the agent can ask the customer to confirm the email address and continue the verification flow. ### The code does not work Codes are 6 digits and expire after a limited time. If the code is expired or entered incorrectly too many times, the customer may need to start verification again. ### The action still does not run after verification Check that the action or integration tool is still available to the agent, the connected integration is active, and the required customer information is present. Verification allows the action to continue, but the action can still fail if the external system rejects the request or the required IDs are missing. ### The agent keeps asking for verification Verification sessions are temporary and scoped to one conversation. If the customer starts a new conversation, comes back after the session expires, or asks for another sensitive action later, Weav may ask them to verify again. # Framer Source: https://docs.weav.com/integrations/framer Learn how to install Weav on your Framer site, customize the chat launcher, and open chat from canvas layers. The Weav Framer plugin lets you add your Weav AI agent to a Framer site without manually copying scripts. Use it to: * Install the Weav chat widget * Choose which Weav agent appears on your site * Match the launcher to your brand * Turn buttons, links, and other canvas layers into chat triggers * Send an optional message when a visitor opens chat When your AI agent needs help from a person, the conversation can move into your Weav inbox with its history attached. *** ## Before you start You will need: * A Weav account * A Weav workspace with at least one active agent * A Framer project with Custom Code enabled * Permission to manage Custom Code and Code Overrides in the project * A paid Framer Site plan that supports Custom Code If you do not have a Weav account, you can create one from the plugin or at [weav.com](https://weav.com). Framer workspace or account upgrades are separate from your site's plan. The individual site must have a plan that supports Custom Code. *** ## Install the Weav plugin 1. Go to the [Framer chatbot plugin](https://www.framer.com/community/marketplace/plugins/weav/). 2. Click **Open Plugin**. 3. Open the plugin in the Framer project where you want to install Weav. The plugin opens on the Framer canvas. *** Connect

## Connect your Weav workspace 1. Open the Weav plugin in Framer. 2. Click **Connect your Weav workspace**. 3. Complete the authorization process in the browser tab that opens. 4. When you see **You're Authenticated**, close the tab and return to Framer. The plugin will detect the completed connection automatically. If you belong to more than one Weav workspace, select the workspace you want to connect and click **Next**. The connection process must be completed within two minutes. If it times out, return to Framer and start the connection again. ***

## Choose an agent Select the Weav agent you want to add to your Framer site, then click **Next**. If your workspace has only one active agent, the plugin selects it automatically. If no agents are available: 1. Click **Create an agent in Weav**. 2. Create and activate your agent. 3. Return to Framer. 4. Click **Refresh**. Only active customer-facing agents are shown in the plugin. *** Screenshot 2026 07 23 At 10 09 11 AM

## Install the chat widget After choosing an agent: 1. Find the **Chat widget** section. 2. Click **Install widget**. 3. Confirm by clicking **Install widget** again. 4. Publish your Framer site. The plugin adds the Weav widget to your project's Custom Code. Existing custom code is preserved. Installing the widget updates the Framer project, but it does not update the live website until you publish the site. After publishing, the Weav launcher will appear on your live site. *** Screenshot 2026 07 23 At 10 09 23 AM

## Customize the launcher Use the **Launcher appearance** section to match the chat launcher to your site. You can change: * **Alignment** — Display the launcher on the left or right * **Theme** — Use the light or dark theme * **Primary color** — Choose a color or enter its hex value Click **Save appearance** when you are finished. The settings are saved to the selected agent in Weav and will apply anywhere that agent's launcher is used. Choose a primary color with enough contrast against your site background so the launcher remains easy to find. *** Screenshot 2026 07 23 At 10 09 35 AM

## Open chat from a canvas layer Open Chat triggers let visitors open Weav by clicking a button, link, card, or other Framer canvas layer. You can also attach a message to the trigger. This is useful for actions such as: * Ask about pricing * Book a demo * Get help with an order * Learn more about a feature The regular floating launcher remains visible when you use Open Chat triggers. ### Create a trigger 1. Install the Weav widget first. 2. Select exactly one layer on the Framer canvas. 3. Find the **Open Chat triggers** section in the plugin. 4. Enter an **Optional message**, or leave it blank to only open chat. 5. Click **Assign as chat trigger**. The plugin creates a Code Override for the selected layer. ### Apply the Code Override Assigning the trigger creates the override, but you must also apply it to the layer: 1. Keep the layer selected. 2. Open **Code Overrides** in Framer's right panel. 3. Select **WeavOpenChatTriggers.tsx**. 4. Select the override created for the layer. When a visitor clicks the layer, it will open Weav. If you added a message, the message will also be sent to the agent. Trigger messages can contain up to 500 characters. ### Remove a trigger Find the trigger in the plugin and click **Remove**. The plugin keeps a safe, inactive version of the override so existing Framer layers do not break. You can also remove the Code Override from the layer in Framer if it is no longer needed. *** ## Switch agents If your workspace has multiple agents: 1. Click **Switch agent**. 2. Choose another agent. 3. Click **Reinstall widget**. 4. Publish your site. Reinstalling updates the widget so the newly selected agent appears on the live site. Selecting another agent does not update the published widget by itself. Reinstall the widget and publish the site to complete the change. *** ## Remove Weav from your site 1. Open the Weav plugin. 2. Find the **Chat widget** section. 3. Click **Remove**. 4. Confirm by clicking **Remove widget**. 5. Publish your Framer site again. The widget will remain on the live site until the updated project is published. *** ## Sign out Click **Sign out** at the bottom of the plugin to disconnect your Weav account from the current Framer session. Signing out does not remove an already installed widget from the site. Use **Remove widget** and publish the site if you want to remove Weav. *** ## Troubleshooting ### The widget does not appear on my live site Check that: * You clicked **Install widget** * Custom Code is enabled for the site * Your Framer Site plan supports Custom Code * You published the site after installing the widget ### Framer says Custom Code is read-only Open the plugin from the Framer canvas rather than Preview. Also check that: * The site has a paid plan that supports Custom Code * Custom Code is enabled in Site Settings * Your Framer role has permission to change the project ### The plugin cannot create chat triggers Check that: * The widget is installed * Exactly one canvas layer is selected * You have permission to create or update Code Override files ### Clicking a trigger does nothing Creating a trigger in the plugin does not automatically apply it to the layer. Select the layer and apply its override from: **Code Overrides → WeavOpenChatTriggers.tsx** Then publish the site. ### The wrong agent appears on the site Choose the correct agent, click **Reinstall widget**, and publish the site again. ### The sign-in process timed out Return to the plugin and click **Connect your Weav workspace** again. Complete the authorization process within two minutes. ### My workspace has no available agents Create and activate an agent in Weav, then return to the plugin and click **Refresh**. ### I cannot save another chat trigger Remove unused triggers or shorten their optional messages, then try again. # Google Drive Source: https://docs.weav.com/integrations/google-drive Learn how to connect Google Drive with your Weav AI Agents Import Google Drive into Weav agents

The Google Drive integration lets you import files from Google Drive directly into your agents training data. Use it when your documentation content already lives in Google Drive. Search and train your agents on knowledge bases, FAQ spreadsheets, policy PDFs, onboarding docs, internal product guides. Google Drive imports happen one file at a time and are not synced. If you change a document in Google Drive, re-import it in Weav to refresh it. *** ## Before you start You will need: * A Google account (personal or Google Workspace) with access to the files you want to import * The files you want to import already in Google Drive, in a supported format Best practices before importing: * Decide which agents should have access to the imported content * Make sure the source documents are clean, current, and customer-safe * Remove or redact any sensitive information you don't want the agent to use *** ## Import files from Google Drive Path: Training -> + Add content -> Google Drive 1. Open [Training](https://app.weav.com/training). 2. (Optional) Open a Training folder if you want the imports to land there. 3. Click + Add content. 4. Select Google Drive. 5. Sign in with your Google account if prompted. 6. Click Choose files from Google Drive. 7. Select up to 20 files. 8. Click Select. Weav queues your files for import and a confirmation appears. The new items show up in the Training table while they are processed in the background. You don't need an admin to enable this integration. Anyone who can add training content can import from Google Drive. *** ## Supported file types With Google Drive, the following formats are supported. Files that don't have this file type are automatically filtered out. | File type | Notes | | ---------------- | -------------------------------- | | Google Docs | Converted to PDF for processing. | | Google Sheets | Converted to CSV for processing. | | PDF | Imported as-is. | | Microsoft Word | Both `.doc` and `.docx`. | | Plain text | `.txt` | | Markdown | `.md` | | CSV | Imported as-is. | | Rich Text Format | `.rtf` | Selecting an entire folder is not supported. Pick the individual files you want to import. *** ## Manage which agents use imported files When a file is imported, it is attached to all of your agents by default — the same as any other training content. To change which agents can use a specific file: 1. Go to your [Training](https://app.weav.com/training). 2. Find the imported file in the Training table. 3. Open the agent access menu for that file. 4. Select the agents that should use this content. 5. Save your changes. For example, if you have multiple agents for different topics such as a billing agent and a product agent, limit each imported file to the agents that should use it. This keeps each agent focused. *** ## Best practices ### Import only customer-safe content Imported content can be used by your agents to answer customers. Don't import internal-only documents, drafts, or anything you wouldn't want quoted back in a customer conversation. ### Keep imports focused A small set of well-maintained documents will train your agent better than a large pile of mixed content. Start with your best documents and add more as you go. ### Re-import when content changes Google Drive imports are not synced. When a source document changes in Drive, re-import it in Weav so the agent uses the latest version. ### Use folders to organize imports If you keep your training content organized in Training folders in Weav, open the folder before clicking + Add content. Imports will land in that folder automatically. ### Limit access by agent Not every agent needs every document. Use the agent access menu on each Training item to scope content to the right agents. # Shopify Source: https://docs.weav.com/integrations/shopify Learn how to connect Shopify with your AI Agents

The Shopify integration connects your Weav workspace to a Shopify store so your AI agents can help shoppers with product questions, order status, and common order changes. After Shopify is connected, agents can search your live catalog, check inventory, look up orders, cancel orders, update shipping addresses, or edit line items. Product catalog data can sync into Training, and the Weav chat widget can be added to your storefront through the Shopify app. Order tools require customer email verification before they run in shopper conversations. This helps protect order and account data. *** ## When to use the Shopify integration Use Shopify when your agents need to help customers with store-specific questions or order workflows. Good use cases include: * Recommending products from your catalog * Checking whether a variant is in stock * Looking up order status or tracking * Helping a customer cancel an order * Updating a shipping address before fulfillment * Swapping a size or color, or changing quantity on an existing order line * Answering questions using synced product training data and store policies Shopify works best for agents that handle pre-purchase shopping, post-purchase support, or both on your storefront chat widget. *** ## Connect Shopify You can connect from the Shopify App Store or directly in Weav. ### Option A: Install from the Shopify App Store 1. Install [**Weav — AI customer service**](https://apps.shopify.com/weav-ai-customer-service) from the Shopify App Store. 2. Open the app in Shopify admin. 3. Choose **Sign up for Weav** (new account) or **Connect your Weav account** (existing workspace). 4. Sign in or create your Weav account. 5. Complete the Shopify authorization flow in Weav. 6. Return to the Shopify app — the connection should show as **Connected**. After connecting, use the embedded app to pick your storefront agent, add training, and activate the chat widget on your theme. ### Option B: [Connect from Weav](https://app.weav.com/settings/integrations) Path: **Settings → Integrations → Shopify** 1. Open **Settings**. 2. Go to **Integrations**. 3. Select **Shopify**. 4. Enter your store domain (for example `your-store.myshopify.com`). 5. Click **Connect**. 6. Complete the Shopify authorization flow. 7. Return to Weav. After Shopify is connected, the integration shows as **Connected**. Product sync and storefront policy discovery start automatically in the background. If you installed the Shopify app first, Weav can pre-fill your store domain when you open **Settings → Integrations** from the embedded app. *** ## Configure Shopify settings Path: **Settings → Integrations → Shopify → Settings** ### Sync products to training data When enabled, product catalog updates flow into the **Shopify** folder in **Training**. This keeps agent knowledge aligned with your catalog. * Turned on by default after connect * Updated when products change in Shopify (via webhooks) and on a daily sync * Turn off if you want to pause automatic product updates ### Custom shopping guidance Optional instructions appended to the agent system prompt when Shopify tools are available. Use this for store-specific rules such as: * Free-shipping thresholds * Seasonal promotions * What agents should never promise (for example exact delivery dates) * How to handle out-of-stock items Shopify Integration Settings

*** ## Activate the storefront chat widget The Weav chat widget is added to your Shopify theme through a **Theme App Extension**, not a manual script tag. From the Shopify app (after your store is connected): 1. Open the **Weav** app in Shopify admin. 2. If you have multiple agents, select **Agent shoppers see** and click **Save agent**. 3. Click **Activate on storefront** to open the theme editor. 4. Enable the **Weav Chat Widget** app embed. 5. Click **Save** in the theme editor. You only need to activate the app embed once per theme. To turn the widget off, disable the **Weav Chat Widget** app embed in your theme editor. *** ## Give agents access Shopify Ai Agent Access

Shopify tools are not automatically available to every agent. You choose which agents can use them. 1. Open **Settings → Integrations**. 2. Select **Shopify**. 3. Click **Manage access**. 4. Choose the agents that should use Shopify. 5. Grant access to all Shopify tools or select specific tools. 6. Click **Save changes**. On first connect, entitled tools are granted to active agents based on your workspace's **AI actions** limit. You can refine access afterward. ### Allow all tools Use **Allow all tools** when an agent should have access to every current and future Shopify tool. This is useful for a dedicated shopping and support agent on your storefront. ### Select specific tools Use specific tool access when an agent should only handle certain workflows. Examples: * A pre-purchase agent can search products and check inventory only. * A post-purchase agent can look up orders and get order details. * A fulfillment agent can update shipping addresses and edit orders. For most teams, start with specific tool access. Add update tools once you are confident the agent follows your support policies. *** ## Supported Shopify tools The Shopify integration currently supports the following agent tools. | Tool | What it does | Verification | Best for | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------- | | Search products | Searches your live Shopify catalog by keywords (titles, variants, handles). Only returns products with at least one purchasable variant. | None | Product recommendations, browsing, and discovery | | Check inventory | Returns live availability and quantity for a specific product variant. | None | "Is this in stock?" and variant-level availability | | Look up customer orders | Lists the shopper's recent orders (newest first, up to 20). | Required | "Where is my order?" and order history | | Get order details | Fetches one order — line items, status, totals, fulfillment, tracking, and sibling variants for swaps. | Required | Order status, tracking, and preparing order edits | | Cancel order | Cancels an eligible order with configurable reason, restock, customer notification, and refund options. | Required | Confirmed cancellation requests | | Update shipping address | Updates the shipping address on an order before fulfillment locks it in. | Required | Address changes before shipment | | Edit order | Swaps a line item's variant (size, color, etc.) and/or changes quantity on existing lines. Cannot add or remove line items. Blocks edits that raise the order total. | Required | Size/color swaps and quantity changes | ### Product cards in chat When an agent searches products in a **chat** conversation, Weav can show interactive product cards in the widget so shoppers can browse results visually. *Product cards are not shown in email conversations.* Shopify Products 1

*** ## How agents use Shopify tools Agents decide when to use Shopify based on the customer's request, the tools they have access to, and the guidance you provide in the agent's settings. ### Catalog and inventory (no verification) For product questions, the agent can: 1. Identify that the shopper is asking about products or availability. 2. Call **Search products** or **Check inventory**. 3. Use the result to answer or recommend items from your store. Product search only surfaces items that are available for sale. Agents will recommend products from your catalog or training data, not competitors or external sites. ### Order workflows (verification required) For order questions, the agent can: 1. Identify that the shopper is asking about their order. 2. Call the relevant order tool. 3. Weav prompts the shopper to verify their email before the tool runs. 4. After verification, the agent continues with the order request. For example, if a customer asks "Where is my order?", the agent calls **Look up customer orders**, the shopper verifies their email in chat, and the agent explains order status and tracking. For order changes, the agent typically calls **Get order details** first, confirms the change with the shopper, then calls **Cancel order**, **Update shipping address**, or **Edit order**. *** ## Customer verification Order tools require verification in shopper conversations: * Look up customer orders * Get order details * Cancel order * Update shipping address * Edit order **Search products** and **Check inventory** do not require verification. ### Chat widget Verify

When an order tool is needed in chat, Weav shows an in-chat verification card. The shopper enters their email, receives a one-time code, and verifies. After verification succeeds, the agent can continue with the order request. Once verified, the shopper can use additional order tools in the same conversation for about 30 minutes without verifying again. The verified email must match an email on file for the order. If an order has no email on file, the agent should escalate to your team. ### Email In email conversations, verification works differently. The agent asks the customer for their email, sends a verification code, and waits for the customer to reply with the code before the order tool runs. Verification protects customer data, but it does not replace your internal support policies. Add clear instructions to your agent about what it should and should not do. *** ## Read-only vs update tools Shopify tools fall into two practical groups. ### Read-only tools Read-only tools look up information without changing Shopify data. Read-only tools include: * Search products * Check inventory * Look up customer orders * Get order details Use these first when setting up a new Shopify-enabled agent. ### Update tools Update tools can change Shopify data. Update tools include: * Cancel order * Update shipping address * Edit order For update tools, the agent should summarize what will change and ask the customer to confirm before continuing. **Edit order** limitations: * Can only modify existing line items (variant swap and/or quantity change) * Cannot add or remove products from an order * Cannot change the shipping address (use **Update shipping address** instead) * Cannot apply discounts * Blocks edits that would increase the order total Only give update tools to agents that have clear support instructions and are allowed to make order changes. *** ## Training data and catalog sync Connecting Shopify can populate your agent's knowledge in two ways. ### Product catalog When **Sync products to training data** is enabled: * Products are stored in the **Shopify** folder in **Training** * Updates flow in when products are created, updated, or deleted in Shopify * A daily sync also keeps the catalog current Agents use this training data alongside live catalog search. ### Store policies and pages After connect, Weav can discover your storefront's `/policies/*` and `/pages/*` URLs and ingest them as website training data. This helps agents answer questions about shipping, returns, and store policies. If you already added your store URL during onboarding, Weav skips duplicate policy ingestion for the same domain. ### What is not synced Orders and customer records are **not** stored in training data. Order tools query Shopify live at conversation time. *** ## Shopify context in the inbox When Shopify is connected, human agents see a **Shopify** section in the conversation sidebar.

This section helps your team: * See whether a conversation's customer matches a Shopify customer * Search for and link a Shopify customer profile * View recent orders and open the customer in Shopify admin Searching Shopify customers in the inbox may require **Protected Customer Data** approval from Shopify. Without approval, customer search can be restricted. *** ## Example: Recommend a product A customer asks: > Do you have wireless earbuds under \$100? The agent can: 1. Call **Search products** with keywords like "wireless earbuds". 2. Filter results to in-stock, purchasable variants. 3. Recommend matching products from your store. 4. Show product cards in the chat widget (if on chat). *** ## Example: Check order status A customer asks: > Where is my order? The agent can: 1. Call **Look up customer orders**. 2. Prompt the shopper to verify their email. 3. List recent orders for that email. 4. Call **Get order details** if more information is needed. 5. Explain fulfillment status and tracking. Good response: > Your order #1042 shipped yesterday. Tracking number: 1Z999AA10123456784. It should arrive by Friday. *** ## Example: Swap a size on an order A customer asks: > Can I change the snowboard on order #1003 from size 150 to size 160? The agent can: 1. Call **Get order details** for order #1003. 2. Find the line item and matching variant in `sibling_variants`. 3. Confirm the change with the shopper. 4. After verification, call **Edit order** to swap the variant. If the swap would raise the order total, the edit is blocked and the agent should explain the limitation. *** ## Best practices ### Start with lookup tools Begin with **Search products**, **Check inventory**, **Look up customer orders**, and **Get order details**. Add update tools later once your team is confident in the agent's behavior. ### Use custom guidance for store rules Add promos, shipping thresholds, and escalation rules in **Settings → Integrations → Shopify → Settings → Shopping guidance**. Keep broader support policies in the agent's **Context**. ### Keep support policies in Context Tell the agent what it can do, what it should escalate, and when it must ask for confirmation. Include rules for: * Refund requests * Returns and exchanges * Cancellations after fulfillment * Address changes after shipment * Out-of-stock alternatives * When to hand off to a human ### Limit access by agent role Not every agent needs every Shopify tool. Give each agent the minimum access it needs. * Storefront shopping agent: product search and inventory * Post-purchase agent: order lookup and details * Fulfillment agent: address updates and order edits ### Review sensitive workflows Be extra careful with **Cancel order**, **Update shipping address**, and **Edit order**. ### Sync products for better answers Keep **Sync products to training data** enabled so agents have stable product knowledge even when live search is not needed. *** ## Disconnect and reinstall **Disconnect in Weav** or from the Shopify embedded app turns off the storefront widget configuration in Weav. The Shopify app remains installed so you can reconnect later. **Uninstalling the app in Shopify** fully disconnects the store in Weav. *** ## Troubleshooting ### Shopify is not available to an agent Check that: * Shopify is connected * The agent is active * The agent has access to Shopify tools * The specific tool is enabled for that agent * Your workspace has available **AI actions** entitlement for integration tools ### The agent cannot complete an order request Check that: * The customer completed email verification * The agent has the required Shopify tool * The verified email matches an email on the order * The order exists in Shopify * The order is eligible for the requested action (for example not already fulfilled for address changes) ### The agent cannot find a product option for an order edit Order variant swaps use **Get order details**, not product search. The agent should match the shopper's request (for example "size 160") against `sibling_variants` on the order line — not search the catalog by option value. ### An order edit was rejected Common reasons: * The change would increase the order total * The line item is not merchant-editable in Shopify * The order is no longer editable * Shopify rejected the address or mutation Have the agent explain the outcome in plain language and escalate if needed. ### Product sync is not updating Check that: * **Sync products to training data** is enabled in Shopify settings * The Shopify connection is active * Your queue worker is running (sync jobs run in the background) ### The storefront chat widget is not showing Check that: * Shopify is connected in Weav * An agent is selected in the Shopify app * The **Weav Chat Widget** app embed is enabled in your theme editor * You saved the theme after enabling the embed ### Customer search is restricted in the inbox Your Shopify app may need **Protected Customer Data** access approved by Shopify. Until approved, inbox customer search can return restricted errors. ### The agent is using the wrong Shopify tool Update the agent **Context**. Add clear instructions for when to use each tool. For example, tell the agent to use product search for shopping questions and order tools only for post-purchase requests. ### The agent should not make order changes Remove access to update tools: * Cancel order * Update shipping address * Edit order Keep read-only tools enabled so the agent can still answer product and order status questions. # Stripe Source: https://docs.weav.com/integrations/stripe Learn how to connect Stripe with your Weav AI Agents Stripe integration for AI agents

The Stripe integration lets your Weav agents use approved Stripe tools during customer conversations. Use it when customers ask about billing, subscriptions, invoices, payment settings, or account details stored in Stripe. After Stripe is connected, you can choose which agents can use Stripe and which tools each agent can access. Stripe tools require customer verification before they run in customer conversations. This helps protect billing and account data. *** ## When to use the Stripe integration Use Stripe when your agents need to help customers with billing questions or subscription workflows. Good use cases include: * Looking up a customer in Stripe * Checking subscription status * Finding recent invoices * Sharing a secure billing portal link * Helping a customer update billing details * Canceling or updating a subscription after confirmation Stripe works best for agents that handle billing, subscriptions, account management, or customer support. *** ## Before you start You will need: * Admin access in Weav * Permission to connect your Stripe account * A clear policy for what agents are allowed to do with billing data Best practices before connecting: * Decide which agents should have Stripe access * Start with read-only tools before enabling update or cancellation tools * Add billing rules to your agent Context *** ## Connect Stripe Path: Settings -> Integrations -> Stripe 1. Open Settings. 2. Go to Integrations. 3. Select Stripe. 4. Click Connect. 5. Complete the Stripe authorization flow. 6. Return to Weav. After Stripe is connected, the integration will show as Connected. *** ## Give agents access Stripe integration for AI agent tools

Stripe tools are not automatically available to every agent. You choose which agents can use them. 1. Open Settings -> Integrations. 2. Select Stripe. 3. Click Manage access. 4. Choose the agents that should use Stripe. 5. Grant access to all Stripe tools or select specific tools. 6. Click Save changes. ### Allow all tools Use Allow all tools when an agent should have access to every current and future Stripe tool. This is useful for a dedicated billing agent. ### Select specific tools Use specific tool access when an agent should only handle certain workflows. Examples: * A general support agent can search customers and retrieve invoices. * A billing agent can retrieve and update subscriptions. * A retention agent can create billing portal sessions and cancel subscriptions. For most teams, start with specific tool access. Add more tools once you are confident the agent is following your billing policies. *** ## Supported Stripe tools The Stripe integration currently supports the following agent tools. | Tool | What it does | Best for | | ----------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Search Stripe customers | Searches Stripe customers using Stripe search query syntax. | Finding the right customer record by email, name, metadata, or creation date. | | Retrieve customer | Retrieves details for a specific Stripe customer ID. | Confirming customer details before answering account or billing questions. | | Update Customer | Updates an existing Stripe customer. | Updating email, name, phone, address, tax status, metadata, invoice settings, or payment method references. | | List subscriptions | Lists subscriptions with optional filters like customer, status, price, date range, or collection method. | Finding a customer's active, canceled, or past subscriptions. | | Retrieve subscription | Retrieves one subscription by subscription ID. | Checking plan, status, renewal dates, billing method, or subscription details. | | Update Subscription | Updates an existing non-canceled subscription. | Changing subscription items, quantity, price, payment behavior, proration behavior, metadata, or cancellation-at-period-end. | | Cancel subscription | Cancels an active subscription at the end of the current billing period. | Handling confirmed cancellation requests. | | List Invoices | Lists invoices with optional filters like customer, subscription, status, date range, or collection method. | Finding recent invoices or checking whether invoices are open, paid, void, or uncollectible. | | Retrieve Invoice | Retrieves one invoice by invoice ID. | Answering detailed invoice questions. | | Create Billing Portal Session | Creates a secure Stripe billing portal URL. | Sending customers to Stripe to manage subscriptions, invoices, or payment methods themselves. | *** ## How agents use Stripe tools Agents decide when to use Stripe based on the customer's request, the tools they have access to, and the guidance you provide in the agent's settings. At generation time, the agent can: 1. Identify that the customer is asking about billing or subscriptions. 2. Ask for any required information, such as an email address, customer ID, subscription ID, or invoice ID. 3. Trigger customer verification when required. 4. Call the appropriate Stripe tool. 5. Use the result to answer the customer. For example, if a customer asks, "Can you check whether my last invoice was paid?", the agent will request the customer to verify their email and then it search for the customer, list invoices for that customer, then explain the invoice status. *** ## Customer verification All supported Stripe tools require verification in customer conversations. When a Stripe tool is needed, Weav asks the customer to verify by email before the action runs. After verification succeeds, the agent can continue with the Stripe request. Use verification for Stripe because the tools can access sensitive billing data, including: * Customer records * Invoices * Subscription details * Payment-related settings * Account and billing updates Verification protects customer data, but it does not replace your internal billing policies. Add clear instructions to your agent about what it should and should not do. *** ## Read-only vs update tools Stripe tools fall into two practical groups. ### Read-only tools Read-only tools look up information without changing Stripe data. Read-only tools include: * Search Stripe customers * Retrieve customer * List subscriptions * Retrieve subscription * List Invoices * Retrieve Invoice * Create Billing Portal Session Use these first when setting up a new Stripe-enabled agent. ### Update tools Update tools can change Stripe data or start a billing workflow. Update tools include: * Update Customer * Update Subscription * Cancel subscription For update tools, the agent should summarize what will change and ask the customer to confirm before continuing. Only give update tools to agents that have clear billing instructions and are allowed to make account changes. *** ## Example: Send a billing portal link A customer asks: > Can I update my payment method? The agent can: 1. Search for the Stripe customer. 2. Verify the customer. 3. Create a Billing Portal Session. 4. Send the secure Stripe portal URL to the customer. This is often safer than updating billing details directly because the customer completes the change inside Stripe themselves. *** ## Example: Check subscription status A customer asks: > Is my subscription still active? The agent can: 1. Search for the Stripe customer by email. 2. List subscriptions for that customer. 3. Retrieve the relevant subscription if more detail is needed. 4. Explain the subscription status and renewal date. Good response: > Your subscription is active and renews on May 15. Your current plan is Pro Monthly. *** ## Best practices ### Start with lookup tools Begin with tools that search, retrieve, and list Stripe records. Add update tools later once your team is confident in the agent's behavior. ### Prefer the billing portal for customer-managed changes For payment methods, invoice downloads, and some subscription changes, the billing portal is often the safest option. ### Keep billing policies in Context Tell the agent what it can do, what it should escalate, and when it must ask for confirmation. Include rules for: * Refund requests * Subscription changes * Cancellation offers * Plan upgrades or downgrades * Account ownership questions * Failed payments or disputes ### Limit access by agent role Not every agent needs every Stripe tool. Give each agent the minimum access it needs for its job. ### Review sensitive workflows Be extra careful with tools that update customers, update subscriptions, or cancel subscriptions. *** ## Troubleshooting ### Stripe is not available to an agent Check that: * Stripe is connected * The agent is active * The agent has access to Stripe tools * The specific tool is enabled for that agent ### The agent cannot complete a Stripe request Check that: * The customer completed verification * The agent has the required Stripe tool * The customer provided enough information * The Stripe customer, subscription, or invoice ID exists * Your Stripe account allows the requested action ### The agent is using the wrong Stripe tool Update the agent Context. Add clear instructions for when to use each tool. For example, tell the agent to use the billing portal for payment method updates, and to use invoice tools only for invoice questions. ### The agent should not make billing changes Remove access to update tools: * Update Customer * Update Subscription * Cancel subscription Keep read-only tools enabled so the agent can still answer billing questions without changing Stripe data. # WhatsApp Source: https://docs.weav.com/integrations/whatsapp Whats App

Connect a WhatsApp Business phone number to Weav so your AI agent can answer customer questions on WhatsApp automatically, with conversations appearing in your unified inbox alongside chat and email. Use it to: * Let customers start a conversation with your business on WhatsApp * Have your AI agent answer WhatsApp messages using your training data * Escalate WhatsApp conversations to a teammate when a customer asks for a person * Keep a full WhatsApp conversation history next to your chat and email conversations * Add internal notes on WhatsApp conversations so your team can collaborate behind the scenes WhatsApp is available on all Weav plans. *** ## Before you start You will need: * Admin access in Weav * At least one active AI agent in your workspace * A Meta Business Manager account * A WhatsApp Business phone number, or a phone number that isn't currently active in the regular WhatsApp Business app * Access to that phone number to receive a verification code by SMS or voice call Connecting WhatsApp uses Meta's Embedded Signup flow, so parts of the setup (such as verifying your business with Meta) happen inside a Meta popup rather than inside Weav. Depending on your Meta Business Manager account, Meta may ask you to complete business verification before your number can send messages. If your phone number is currently active in the regular WhatsApp Business app on a phone, you'll need to migrate it to the WhatsApp Business Platform (Cloud API) as part of the Meta setup flow, or use a different number. Meta only allows a number to be connected to one WhatsApp product at a time. *** ## Connect WhatsApp Whatsapp Connection

Path: Settings -> Integrations -> WhatsApp 1. Open Settings. 2. Go to Integrations. 3. Select WhatsApp. 4. Click **Connect WhatsApp**. 5. Complete Meta's Embedded Signup flow in the popup window: sign in to your Meta Business Manager account, and either select an existing WhatsApp Business Account and phone number or create new ones. 6. Once the popup closes, return to Weav. Weav validates the connection with Meta, subscribes to your WhatsApp Business Account so messages can flow into your inbox, and sets the connection status to **Active**. Weav handles the Meta webhook configuration for you. You will never need to paste a webhook URL, API key, or access token into Weav. *** ## Register your phone number Some phone numbers need to be registered with Meta's Cloud API before Weav can send outbound WhatsApp messages. If this step is needed, Weav will show a **Phone registration** prompt on the WhatsApp integration page after you connect. 1. Open Settings -> Integrations -> WhatsApp. 2. Find the **Phone registration** section. 3. If this number already has two-step verification enabled in WhatsApp Manager, enter its existing 6-digit PIN. Otherwise, leave the PIN field blank. 4. Click **Register phone number**. Inbound WhatsApp messages still arrive in your inbox while registration is pending. Outbound replies (including AI-generated ones) are blocked until the number is registered. *** ## Assign an agent to WhatsApp WhatsApp is a workspace-level channel, and one AI agent is assigned to handle it at a time. 1. Open the agent you want to handle WhatsApp conversations. 2. Go to its **WhatsApp** tab. 3. Click **Assign to WhatsApp**. If another agent is already assigned to WhatsApp, assigning a new agent will take over all future WhatsApp conversations. The previously assigned agent will no longer respond on WhatsApp. If no agent is assigned yet, WhatsApp conversations will still appear in your inbox, but they will need a teammate to reply manually until an agent is assigned. *** ## Configure agent behavior Whatsapp Options

On the agent's **WhatsApp** tab, you can set: * **Welcome message** — the first message this agent sends when it starts a new WhatsApp conversation. * **Escalation assignee** — the teammate WhatsApp conversations are assigned to when a customer asks to speak with a person. *** ## How WhatsApp conversations work * WhatsApp conversations appear in your unified inbox alongside chat and email, with their own channel indicator. * Your assigned AI agent answers using your training data, the same way it does on chat and email. * Meta only allows outbound WhatsApp messages within a **24-hour customer service window**, starting from the customer's most recent message. Once that window closes, you and your AI agent can no longer send a reply until the customer messages again, but you can still add **internal notes** to keep track of the conversation internally. * Customers can ask to speak with a person at any time, which hands the conversation to the escalation assignee configured on the agent's WhatsApp tab. If you regularly need to reach customers outside the 24-hour window, plan to follow up the next time they message you, or reach them through another channel such as email. *** ## Manage the connection Path: Settings -> Integrations -> WhatsApp * **Check health** — verifies the connection is still valid with Meta and refreshes its status. * **Pause** — temporarily stops sending and receiving WhatsApp messages without disconnecting your number. Use this if you need to pause support without losing your setup. * **Resume** — turns a paused connection back on. * **Disconnect** — removes the WhatsApp connection from Weav entirely. You'll need to complete Embedded Signup again to reconnect. *** ## Good to know * Only one AI agent can be assigned to WhatsApp per workspace at a time. * Weav does not currently support Meta message templates, so all outbound messages are regular freeform replies sent within the 24-hour window. * WhatsApp is available on all Weav plans at no extra cost. *** ## Troubleshooting ### I can't finish connecting WhatsApp Check that: * You're signed in to Weav with admin access. * You completed the Meta popup fully, closing it early cancels the connection. * Your Meta Business Manager account has permission to manage the WhatsApp Business Account and phone number you selected. * Your phone number isn't already active in the regular WhatsApp Business app. If it is, migrate it to the WhatsApp Business Platform in Meta's flow, or choose a different number. ### The connection shows "Setup incomplete" or "Error" Click **Check health** on the WhatsApp integration page to refresh the connection status and see the latest detail message. If the issue persists, try disconnecting and reconnecting through Embedded Signup. ### Outbound messages aren't sending Check that: * Your phone number is registered with Meta (see **Register your phone number** above). * The conversation's 24-hour reply window hasn't expired. If it has, you can still add an internal note, but you'll need to wait for the customer to message again before replying. * The WhatsApp connection status is **Active**, not **Paused**. ### The wrong agent is responding on WhatsApp Go to the agent that should handle WhatsApp and click **Assign to WhatsApp** on its WhatsApp tab. Assigning a new agent immediately takes over future WhatsApp conversations. ### I registered my phone number but it still won't send messages Double-check the PIN you entered matches the existing two-step verification PIN configured in Meta's WhatsApp Manager. If this number has never had two-step verification enabled, leave the PIN field blank and try again. ### Customers say messages aren't reaching my inbox Check that: * The WhatsApp connection status is **Active**, not **Paused** or **Disconnected**. * You didn't recently disconnect and forget to reconnect Weav in Meta Business Manager. Run **Check health** to confirm Weav can still reach Meta's API for your number. # Build your first AI agent Source: https://docs.weav.com/quick-start/build-your-first-ai-agent Create, train, and deploy your first Weav AI Agent in minutes. Follow this step-by-step guide to get your intelligent assistant ready to help your customers. In just a few steps, you'll have a fully functional AI Agent capable of instantly answering customer questions, resolving routine issues, and seamlessly handing off complex problems to your human team. Let's get started! Overview Here is what we'll accomplish in this guide: Set up a new AI Agent, define its role, and customize its tone of voice. Upload your existing knowledge base—like FAQs, website links, or PDFs—so your Agent knows your business inside and out. Use the Agent Playground to test responses and refine your Agent's behavior before going live. Activate your Agent on your website widget or email channels. ### Step 1: Create & Customize Your Agent Your Agent is the frontline of your customer support. Let's give it an identity. Navigate to the Agents Dashboard After signing into your Weav workspace, navigate to Agents in the main sidebar. Click the "Create Agent" button. **Configure Basic Settings** Give your Agent a personality that matches your brand: * Name: Give your Agent a friendly name (e.g., "Support Assistant"). * Role & Instructions: Provide clear, high-level instructions on how the Agent should behave. (e.g., "You are a helpful and polite support assistant for ACME Corp. Keep your answers concise and always offer to connect the user with a human if they are frustrated.") * Tone: Decide if you want the Agent to sound professional, casual, enthusiastic, or empathetic. * Quick Prompts: Set up 2-3 common questions that users can click immediately when they open the chat widget (e.g., "What are your shipping times?" or "How do I reset my password?"). ### Step 2: Train with Your Data Your AI Agent needs high-quality information to provide accurate answers. Weav allows you to train your Agent using multiple Knowledge Sources. Navigate to your Agent's Knowledge or Training tab to start adding sources. **Crawl your website or help center** Simply paste the URL of your website, blog, or public Help Center. Weav will automatically scrape the content and convert it into training data. Best for: General company information, existing documentation sites, and blog posts. **Upload your internal PDFs and manuals** Upload files directly from your computer. Weav supports PDFs, text files, and more. Best for: Detailed product manuals, internal policy documents, or offline training guides. **Direct text input** Have a quick rule or a temporary promotion? Paste text directly into a snippet. Best for: Rapidly changing information, temporary sales, or specific rules that aren't documented elsewhere. **Add direct Question & Answer pairs** If there are specific questions your customers ask constantly, define the exact Answer you want the AI to give. Best for: Ensuring 100% accuracy on high-volume, critical questions like refund policies. Training happens automatically! Once you add a source, Weav processes it in the background. You can continue setting up your Agent while it learns. ### Step 3: Test in the Playground Before letting your Agent talk to real customers, you should verify its knowledge. Navigate to the Playground tab within your Agent's settings. **Evaluate Response Quality** The Playground is a safe, internal testing environment. Try asking your Agent a few questions based on the data you just uploaded. As you test, look for: * Accuracy: Are the facts correct based on your training data? * Tone: Does it sound like your brand? * Formatting: Is the response easy to read? If the Agent gives an incorrect answer or says "I don't know," you likely need to add more training data to cover that specific topic, or tweak your Agent's base instructions to be more explicit. Step ### 4: Deploy to Your Channels Once you are satisfied with your Agent's performance in the Playground, it's time to put it to work! Unlike standalone chatbots, Weav Agents live directly inside your Unified Inbox and can respond across different channels. Go to your Agent's Settings and ensure its status is set to Active. Decide where this Agent should operate. * Chatbot: The Agent will instantly reply to customers chatting on your website. * Email: The Agent can draft auto-replies for inbound support emails. Weav's superpower is the seamless transition to a human. Set your escalation rules. For example, instruct the Agent to assign the conversation to your Support Team inbox if the user explicitly asks for a "human" or if the AI cannot resolve the issue after a few attempts. 🎉 Congratulations! You've successfully created, trained, and deployed your first Weav AI Agent! Your customers will now enjoy instant, accurate answers 24/7, and your human team can focus on the complex, high-value conversations that matter most. What's Next? # Configure workspace Source: https://docs.weav.com/quick-start/configure-workspace Set up your workspace basics so your team can start supporting customers quickly. ## Overview This quick start guide walks you through the core workspace setup steps every new account should complete: 1. Set your workspace name 2. Upload your workspace icon 3. Choose locale and timezone 4. Invite teammates 5. Add payment details Use your real company details from day one. It helps keep branding, reporting, and teammate collaboration consistent. *** ## 1) Set your workspace name Your workspace name appears across your account and helps your team identify the correct environment. ### Why this matters * Keeps your internal account organized * Improves clarity for teammates * Aligns your support workspace with your brand ### Recommended format Use your company name (for example, `Acme`, `Northstar Labs`, `River & Pine`). *** ## 2) Add your workspace icon Your workspace icon is the visual identity for your team inside the app. ### Why this matters * Makes your workspace easy to spot * Improves navigation for teams in multiple workspaces * Creates a polished, branded setup *** ## 3) Configure locale and timezone Set your default language/region and timezone preferences. **Organization vs user locale/timezone:** Your **workspace locale and timezone** are the default settings used across shared experiences like reporting context, workspace-level defaults, and team-wide consistency. Each **user** can still have their own locale/timezone preferences (how dates/times are displayed to them). In practice, organization settings provide a common baseline, while user settings personalize the experience per teammate. ### What to configure * **Locale**: language and regional format (dates, numbers) * **Timezone**: your primary business timezone Choose the timezone where most of your support team operates.\ If your team is distributed, pick the timezone used for reporting and operational decisions. *** ## 4) Invite teammates Bring your team into the workspace so they can start handling conversations. ### What to do * Invite each teammate by email * Assign appropriate access/roles * Confirm invited users can access the workspace after acceptance *** ## 5) Add payment details Add your payment method early so your workspace setup stays smooth and you can use paid features without interruptions. This matters because it helps prevent delays later, keeps your billing account in good standing, and ensures plan-based capabilities are available when you need them. In billing settings, add your preferred payment method and confirm your billing contact details are accurate. If payment details are missing or outdated, access to some features may be limited. # Connect channels Source: https://docs.weav.com/quick-start/connect-channels Connect chat and email so your AI agent can start handling real customer conversations. After your workspace and agent are configured, the final Quick Start step is connecting your channels. In Weav, that means connecting **Chat** (website widget) and **Email** (agent assignment for inbound email handling). Once both are connected, your agent is ready for live customer interactions. ## Connect chat to your website To enable chat, open your agent and go to **Settings → Chat → Deploy**. In the **Installation** row, Weav gives you a ready-to-use embed script. Screenshot2026 02 28at8 00 14AM

This script loads the Weav widget and initializes it with your agent’s unique slug, so conversations route to the correct agent configuration. In **Deploy → Installation**, copy the full embed snippet using the copy button. Add the snippet near the end of your site’s `` tag. Deploy your site so the widget script is live for visitors. Open your site, start a test chat, and confirm responses come from the expected agent. The script is agent-specific. If you switch to a different agent, copy that agent’s script from its own Chat Deploy section. ## Configure which agent handles email To enable email handling, open your agent and go to **Settings → Email → Deploy**, then use **Assignment**. Screenshot2026 02 28at8 02 23AM

When you click **Assign to email**, that agent becomes the active email agent for the workspace. Only one agent can be assigned to email at a time. Assigning a new agent automatically replaces the previously assigned email agent. ### What assignment changes in practice For new inbound email conversations, Weav links the conversation to the active email agent so email drafting and response automation can run. If the conversation is unassigned, Weav can also assign it to that agent automatically (based on eligibility checks). This is what powers the “agent handles email” workflow. If a conversation already has an agent attached, assignment is not forcibly overwritten on that existing thread. Reassignment mainly affects new or eligible conversations moving forward. ## Pair assignment with your email behavior settings Right below Assignment, configure the behavior that determines how aggressively the agent responds: * **Auto-send threshold** controls whether the agent auto-sends high-confidence replies or creates drafts for human review. * **Escalation assignee** sets who receives conversations when escalation is needed. * **Escalation rules** let you define conditions for escalating to a teammate. ## Recommended go-live checklist Before going live, validate both channels end-to-end: 1. Chat widget appears on your website and sends/receives messages correctly. 2. A new inbound email conversation is linked to the assigned email agent. 3. Draft/auto-send behavior matches your selected threshold. 4. Escalation routes to the correct teammate. If email isn’t connected at the workspace level yet, complete [setting up custom email](https://docs.weav.com/inbox/forward-emails-to-weav) first, then return to agent assignment. ## You’re ready for live interactions When chat is embedded and an email agent is assigned, your workspace is fully connected for live customer conversations across both channels. # Train you agents Source: https://docs.weav.com/quick-start/train-you-agent # Train your AI agents Source: https://docs.weav.com/quick-start/train-your-agents Add knowledge to your AI agents using text, websites, files, videos, and Q&A. Your agents are only as strong as the content you give them. The **Training** workspace is where you add, organize, and maintain the information your agents and **Ask Weav** use to answer customers. This guide explains each training type in detail, when to use it, and how to avoid common mistakes so your agents respond with more accuracy and confidence. Screenshot2026 02 28at7 54 23AM

Training content can be enabled for specific AI agents and for Ask Weav. If access is turned on, that source can be used to generate answers. ## Before you start Great training data is clear, current, and specific. If your content is outdated, repetitive, or too broad, your agent may return weaker answers even if it has a lot of data. A good approach is to start with your highest-impact sources first (website, help center, onboarding docs, top support questions), then add edge cases over time. ## How Training works in Weav Screenshot2026 02 28at7 55 35AM

Open **Training** and choose **Add content**. You can add: * Text * Website * File * Video * Q\&A After adding content, Weav processes it in the background. You may see statuses like **Queued**, **Processing**, **Completed**, or **Failed** while indexing runs. If a source fails, you can usually fix the source (for example: inaccessible page, unsupported file, invalid video link) and try again. ## Training type: Text Use **Text** when you want to type or copy and paste knowledge directly into Weav, like policy snippets, product explanations, internal playbooks, or approved response guidance. Text is best for fast updates and short, high-value knowledge that changes often. **Keep each text entry focused on one topic so retrieval stays precise**. ### Best use cases Use text for content that does not live in a single stable URL or file, or when you need to publish a support update immediately. ### Practical guidance Write in plain, scannable language with clear headings and short paragraphs. Include exact terms your customers use in real conversations so matching improves. Text entries can be meaningful content length and support large bodies of content, so you can store both concise snippets and long-form reference material. ## Training type: Website Use **Website** to sync content from a website or help center. This is usually the fastest way to train an agent on a large knowledge base. Screenshot2026 02 28at7 57 22AM

In Weav, website sync is a two-step flow. First, you enter a top-level URL. Then Weav discovers pages, and you choose which pages to include before syncing. Add the top-level URL (for example, your home page). Weav will discover linked sub-pages. Select only the pages that should train your agents. Focus on clean, customer-ready documentation. Weav processes selected pages and creates training chunks in the background. ### Best use cases Website sync is ideal for marketing sites, docs portals, help centers, changelog pages, and support knowledge bases that are already organized. ### Practical guidance Avoid syncing pages with thin content, duplicated content, or temporary announcements. You can enable **automatic re-sync every 30 days** for website sources, and you can also manually trigger a re-sync when you publish important updates. If a domain is already synced, Weav prevents duplicate website sync for that domain to avoid overlapping sources. ## Training type: File Use **File** when you have documentation saved to digital files. Weav extracts the file text and trains from that content. Supported formats include common support-document formats like PDF, DOCX/DOC, TXT/MD, RTF, and CSV. ### Practical guidance Prefer clean, text-readable files with clear section structure. Remove noisy exports, scanned image-only docs, and duplicated versions where possible. File uploads are size-limited per file. If a document is very large, split it into logical parts (for example: billing-policy-part-1, part-2) for easier maintenance. ## Training type: Video Use **Video** to train from YouTube content. Weav extracts transcript text and uses it as training data. This works well for webinar content, onboarding walkthroughs, and recorded product training where the spoken explanation is valuable. ### Practical guidance Choose videos with clear narration and accurate captions. If possible, pair important videos with a short text summary in a separate Text source so key points are easier to retrieve. Weav supports standard YouTube video URLs. YouTube Shorts are not supported. ## Training type: Q\&A Use **Q\&A** for high-priority, repeat questions where you want precise answer behavior. Q\&A is excellent for FAQ-style intents like pricing rules, account limits, refund policy, SLA details, and compatibility questions. A focused Q\&A entry can significantly improve consistency for common asks. ### Practical guidance Write questions in customer language, not internal jargon. Keep answers direct and policy-safe. If questions are similar but meaningfully different, create separate Q\&A entries rather than one broad answer. ## Assigning training data to the right agents Each training source can be enabled for one or more AI agents and for Ask Weav. This lets you keep knowledge scoped to the agent that needs it. For example, your billing agent can use billing sources, while your onboarding agent uses setup sources. This reduces irrelevant retrieval and improves answer quality. ## Recommended training strategy Start with your most trusted, customer-facing documentation first. Then add Q\&A for top recurring tickets. Add files and videos where your best knowledge is not yet documented elsewhere. Review your sources regularly. Remove outdated entries, re-sync changed websites, and keep naming/titles consistent so your team can manage content quickly. A smaller, curated knowledge base almost always performs better than a large, unmaintained one. ## Troubleshooting quick guide If answers feel off, first check source quality and source coverage for that topic. Then verify that the source is enabled for the correct agent. For websites, confirm the right pages were selected and re-sync if content changed recently. If processing fails, check the specific source format or URL quality and retry. Partial website success is still useful: successful pages can still train the agent even if some pages fail. # Overview Source: https://docs.weav.com/settings/overview A high-level guide to the settings available in Weav and what you can control from each page. ## Introduction Weav settings are where you manage your **personal profile**, your **workspace**, and **developer** tools like API keys and webhooks. Opening **Settings** from the app menu takes you to a dedicated settings area with a sidebar. The sidebar is grouped into **Personal**, **Workspace**, and **Developers**. What you see can depend on your role—for example, some workspace options are only available to workspace admins. *** ## Personal Settings that apply only to you: profile, email, and notifications. ### Details **Path:** Settings → Personal → **Details** * **Name** – Your display name in Weav. * **Email** – Sign-in and account email; change is done through a verification flow. * **Signature** – Optional email signature used when you reply to conversations. * **Timezone** – Your timezone for dates and times in the app. * **Locale** – Your preferred language/locale. * **Appearance** – Theme (e.g. light/dark) if your workspace supports it. ### Notifications **Path:** Settings → Personal → **Notifications** * **Per-event toggles** – For each event type (e.g. new conversation, assignment, mention), you can turn on or off: * **Email** – Receive an email when the event happens. * **Push** – Receive a browser push notification (if supported and allowed). * **Push setup** – Enable or disable browser push and manage permission. *** ## Workspace Settings that affect the whole organization. **General and Billing** is admin-only; the rest are available based on your permissions. ### General **Path:** Settings → Workspace → **General**
**Required role:** Admin * **Workspace name** – Organization/workspace name. * **Locale** – Default language/locale for the workspace. * **Timezone** – Default timezone for the workspace. * **Workspace icon** – Logo or icon for the organization. * **Delete workspace** – Option to permanently delete the workspace and its data. ### Email **Path:** Settings → Workspace → **Email** * **Addresses** – Add, edit, and remove **email addresses** used for support. For each address you can: * Configure **inbound** (receiving) and **outbound** (sending). * Attach **domains** and see verification status (e.g. DKIM, return path). * Run **forwarding tests** to confirm inbound setup. * **Preferences** (tab) – Defaults and behavior for email in the inbox: * **Inbox address** – Your Weav inbound address (e.g. for forwarding); copy to use in your mail provider. * **Default status** – Open vs resolved after sending a reply. * **Default assignee**, **Default from name** – Optional defaults for new conversations or sent emails. * **Auto BCC** – Comma-separated addresses that receive a copy of every outbound email. * **Trusted domains** – Domains whose messages skip spam checks. * **Ignored addresses** – Addresses that are not used to create or update conversations. ### Teammates **Path:** Settings → Workspace → **Teammates** * **List of members** – See everyone in the workspace, with role and status. * **Invite** – Send invites by email; manage pending invites (resend, revoke). * **Roles** – Change a member’s role (e.g. admin, member). * **Remove** – Remove a member from the workspace. ### Views **Path:** Settings → Workspace → **Views** * **Custom inbox views** – Saved filter/sort configurations for the inbox. * **Private vs shared** – Views can be private (only you) or shared with the workspace. * **Pin** – Pin views so they appear in the inbox sidebar. * **Edit / duplicate / delete** – Change filters, copy a view, or remove it. Creating or editing a view can take you to the inbox with the view builder. ### Tags **Path:** Settings → Workspace → **Tags** * **Create tags** – Add tags (name and optional icon) for conversations. * **Edit / delete** – Change name or icon, or remove a tag. * **Usage** – See how many conversations use each tag; optionally open the inbox filtered by that tag. ### Segments **Path:** Settings → Workspace → **Segments** * **Customer segments** – Saved filter/sort configurations for the **Customers** (people) list. * **Private vs shared** – Segments can be private or shared. * **Pin** – Pin segments for quick access in the customers area. * **Edit / duplicate / delete** – Change filters, copy, or remove. Creating a segment can take you to the customers page with the segment builder. Use this to manage saved customer lists (e.g. “High value”, “Needs follow-up”). ### Billing **Path:** Settings → Workspace → **Billing**
**Required role:** Admin Billing is split into tabs: * **Current period** – Usage and summary for the current billing period. * **Subscription** – Plan, add-ons, and subscription status. * **Limits** – Configure and limit your AI resolutions. * **Invoices** – View and download past invoices. * **Payment details** – Update payment method (e.g. card) used for billing. Use this to monitor usage, change plan, and manage payments. ### Import **Path:** Settings → Workspace → **Import** * **Integrations** – List of supported import sources. * **Start import** – For an available integration, open the flow to import data (e.g. chatbots, customers, messages, training data). Use this when migrating from another tool into Weav. *** ## Developers Settings for integrating Weav with other systems. ### API keys **Path:** Settings → Developers → **API** (shown in UI as “API keys”) * **Create API key** – Generate a new token with a name and optional expiry. * **View / copy** – See and copy the secret when first created (it’s not shown again). * **Revoke** – Delete a token so it can no longer be used. Use these keys to authenticate API requests (e.g. from scripts, integrations, or your own app). Learn more about the available API's in the [Weav developer center](https://docs.weav.com/api-reference/introduction) ### Webhooks **Path:** Settings → Developers → **Webhooks** * **Configuration** – Add webhook endpoints (URL, optional secret), choose which **events** to send (e.g. conversation created, message received), and enable/disable each endpoint. * **Delivery logs** – List of recent deliveries per webhook: status, payload, and errors for debugging. Use this to push real-time events from Weav to your servers or third-party services. Learn more about the [Weav webhooks](https://docs.weav.com/api-reference/webhooks/webhook-delivery) ### MCP connections **Path:** Settings → Developers → **MCP connections** **Required role:** Admin or owner * **Connected clients** – See AI tools that have been granted access to this workspace through the Weav MCP server. * **Disconnect** – Revoke a client so it can no longer read or change workspace data. Use this after connecting an MCP client. Learn more in the [MCP guide](/api-reference/mcp). # Customer support workflows Source: https://docs.weav.com/settings/workflows Automate common support steps so customers get faster responses and conversations reach the right place.

Use workflows when the same thing should happen every time a conversation starts or a customer sends a message. A workflow can reply to the customer, add internal notes, route the conversation, apply tags, change status, mark spam, or delete conversations that should not stay in your inbox. Workflows are built on a visual canvas. You choose when the workflow should run, add conditions for the situations it should care about, and connect actions in the order you want them to happen. *** ## When to use workflows Workflows are best for predictable support situations. They are not meant to replace your agents or teammates. They are meant to handle the repetitive parts around the conversation so agents and teammates can focus on the work that needs judgment. For example, you can use a workflow to send an instant reply when a customer writes in, route billing questions to a billing agent, tag conversations from VIP customers, add a private note for teammates, or close conversations that match a known spam pattern. Workflows are especially useful when your team already has a rule like "if this happens, do that." If the rule is clear enough to write down, it is usually a good candidate for a workflow. *** ## How workflows work Every workflow has a trigger, optional conditions, and one or more steps. The trigger decides when Weav should consider running the workflow. A workflow can run when a new conversation is created or when a new message is received. Trigger conditions narrow that down further by channel, customer, assignee, company, status, subject, message text, tags, or date created. After the trigger matches, Weav follows the workflow canvas from top to bottom. It runs each connected step in order. If the workflow reaches an If / Else branch, Weav checks the branch paths from top to bottom and follows the first path that matches. If no path matches, the Else path runs. *** ## Create a workflow Path: Settings -> Workflows Open Settings, go to Workflows, and create a new workflow. Give it a clear name that describes the situation it handles, such as "Route billing questions" or "Tag VIP conversations." When the builder opens, start with the trigger. Choose whether the workflow should run for a new conversation or a new message. Then add trigger conditions to make sure the workflow only runs in the right situations. After the trigger is configured, add actions or branches to the canvas. Save your changes as you work. When the workflow is ready, publish it to make it active. Publishing makes the workflow active. Moving it back to draft deactivates it, and it will no longer run until you publish it again. *** ## Triggers Workflow triggers

The trigger is the starting point of a workflow. Use New conversation when the automation should happen once at the beginning of a conversation. This is a good fit for welcome replies, initial routing, tagging, or spam handling. Use New message when the automation should happen when a customer sends a message. This is useful for routing based on message content, detecting keywords, or applying rules after the conversation is already open. Trigger conditions let you decide which conversations qualify. You can choose All, Email, or Chat, then add filters such as customer email, assignee, company, status, subject, message, tags, or date created. For example, a workflow for billing emails might use a New message trigger, limit the channel to Email, and add a message condition that contains "invoice" or "billing." *** ## Conditions Conditions keep workflows focused. Without conditions, a workflow can run broadly for every matching trigger. That may be right for a general welcome workflow, but most workflows should be narrower. Conditions let you say "only run this for chat conversations," "only run this when the message contains refund," or "only run this when the conversation has a specific tag." Conditions are checked together. If you add multiple filters, the workflow only runs when the conversation matches them. This helps prevent a workflow from taking action on the wrong conversation. Use conditions when the workflow is meant for a specific support situation, customer segment, channel, or topic. *** ## If / Else branches Branches let one workflow handle more than one path. An If / Else branch checks the rules you configure and routes the conversation down the first matching path. The Else path handles everything that did not match. You can also set the Else path to Do nothing, which stops the workflow when no condition matches. Branches are useful when the workflow starts the same way but should behave differently depending on the conversation. For example, you could create one workflow for new messages. If the message contains "billing," assign it to the billing agent. If it contains "bug," add a bug tag and forward it to your engineering triage address. Otherwise, do nothing and let the normal support flow continue. *** ## Actions

Actions are the steps a workflow performs after the trigger and conditions match. ### Reply to the customer Use Reply to the customer when you want to send an automatic response. This can acknowledge a request, set expectations, or point customers to the right next step. Replies are best for simple, predictable messages. Avoid using a workflow reply for anything that needs personalized account details or careful judgment. ### Forward Use Forward when a conversation should be sent to another email address. This is useful for billing teams, external vendors, escalation inboxes, or specialized support queues. ### Add a note Use Add a note to leave private context for your team. Notes are internal and are not shown to the customer. This is useful when a workflow identifies something teammates should know, such as "This customer mentioned cancellation" or "This message matched the refund workflow." ### Change status Use Change status to open or resolve a conversation. This is helpful for cleaning up conversations that do not need a teammate response, or reopening conversations that should be reviewed. ### Mark as spam Use Mark as spam when a conversation matches a pattern your team does not want in the inbox. Be careful with spam workflows. Start with narrow conditions so legitimate customers are not accidentally marked as spam. ### Set assignee Use Set assignee to assign a conversation to a teammate, an AI agent, or leave it unassigned. This is one of the most useful workflow actions because it helps conversations reach the right owner quickly. For example, you can assign billing questions to a billing agent, route VIP customer messages to a senior teammate, or unassign conversations that should return to the shared queue. ### Add tags and remove tags Use Add tags to label conversations automatically. Tags make it easier to filter the inbox, report on support themes, and build follow-up workflows. Use Remove tags when a tag is no longer relevant after a condition is met. ### Delete Use Delete only for conversations you are confident should be removed. Delete is a destructive action and should be used carefully. Do not use Delete as a general cleanup step. Use it only for clear cases like known test messages or spam patterns your team is comfortable removing automatically. *** ## Example: route billing questions A common workflow is routing billing questions to the right owner. Start with a New message trigger. Set the channel to All, or choose Email if billing questions usually come through email. Add a condition where Message contains "billing," "invoice," or "subscription." Then add a Set assignee action and choose your billing agent or billing teammate. You can also add a tag such as Billing so the conversation is easy to report on later. This workflow helps customers reach the right support path quickly. It also keeps general support teammates from manually triaging the same billing questions every day. *** ## Troubleshooting ### The workflow did not run Check that the workflow is active, not draft. Then review the trigger type, channel, and conditions. If the workflow uses a New message trigger, it will not run just because the conversation already exists; it needs a matching message event. ### The workflow ran on the wrong conversation Add more specific trigger conditions. For example, limit by channel, message text, tags, assignee, or company. If the workflow uses a branch, check that the branch paths are ordered correctly because the first matching path runs. ### An action was skipped Some actions can be skipped if required information is missing or stale. For example, an assignee might no longer exist, a tag might have been deleted, or a reply might be empty. Review the action configuration and update any missing references. ### A reply did not send Make sure the reply body is not empty. Also check whether the conversation is assigned to an AI agent. **Workflow replies are skipped when the conversation is assigned to an agent**, so the agent can continue managing the customer response. ### The workflow is no longer needed Move it back to draft to stop it from running. If you are sure the workflow is no longer useful, delete it from the workflows list.