# Check replies before sending Source: https://docs.trypopcorn.ai/agents/ai-manager Score every reply before it is sent, retry replies below your target score, and hand over when the agent cannot do better (formerly AI Manager). **Check replies before sending** ("Scores each reply and tries again when it falls below your target.") is a second check on each reply. Before a reply reaches the customer, a reviewer scores it against the agent's instructions (Popcorn's rules with its Voice, or your custom instructions), your knowledge and the tools the agent has; a reply below your target score is discarded and the agent tries again with the reviewer's notes. Use it on agents where a wrong answer is costly, such as one that quotes policies or takes orders, and accept that each retry makes the reply slower. Earlier versions of Popcorn called this switch **AI Manager**. ## Before you start * Click **Agent** in the sidebar and open the agent; the switch is on the **Instructions** tab, under **How it replies**. * Switch on **Hand over to your team** on the **Handoff** tab if you want the agent to hand over after failed retries. ## Switch it on **1. Enable the check** On the **Instructions** tab, under **How it replies**, switch on **Check replies before sending**. **2. Set the target** Fill in **Minimum reply score (0 to 1)**. The hint reads "Higher scores ask for better replies but retry more. We recommend 0.5 to 0.7." The default is 0.6. A value outside 0 to 1 shows **Enter a number from 0 to 1, like 0.6.** **3. Set the retry limit** Fill in **Maximum retries**, the number of times a reply is regenerated when it scores below the target. The default is 3, and it must be a whole number of 1 or more. The hint warns that more retries can slow replies down. **4. Decide what happens after the last retry** Tick **Hand over to your team after the last retry** ("A person takes over when every retry scores below your target.") to hand the conversation over instead of sending a reply that still scored below target. If **Hand over to your team** is off, the tick box is disabled and reads **Turn on hand over to your team under Handoff to use this.** **5. Save and publish** Click **Save and review**, then **Publish changes**. ## How a reply is scored The reviewer sees the same instructions and tool list as the agent, the conversation up to the customer's last message, and the reply the agent just drafted. It gives a score between 0 and 1 from three criteria: | Criterion | Weight | What it checks | | - | - | - | | Instruction adherence | 40% | Follows the agent's instructions, stays in its role, does not invent facts that are not in the knowledge base, states policies and limits accurately. | | Task completion | 30% | Answers the actual request, uses the information it has, asks a clarifying question or states a limit when the case is unusual, completes the task rather than half of it. | | Communication quality | 30% | Right tone for its role, clear and concise, follows the communication rules in the agent's instructions, matches the customer's style, uses tools correctly. | Each criterion is rated 1.0 (perfect), 0.7 (minor issues), 0.5 (acceptable), 0.3 (poor) or 0.0 (failure), and the weighted total is compared with your target. A target of 0.6 therefore lets through replies with minor issues and blocks replies with a significant problem in any one area. Only replies in conversations assigned to the AI are scored. Replies your team writes are never scored. ## What happens when a reply scores below target 1. The reply is not sent. It is kept internally as a rejected attempt together with its score and the reviewer's note. 2. The agent is told "The manager reviewed your last response and said it needs improvements" with the note, and writes a new reply. 3. The new reply is scored again. This repeats until a reply reaches the target or **Maximum retries** is used up. 4. After the last retry: * With **Hand over to your team after the last retry** off, the last reply is sent as it is. * With it on, the agent is instructed to hand the conversation over instead of answering. The conversation appears in **Unassigned** and in the **Needs you** folder, the customer gets the usual handover confirmation, and your handover alerts are sent. The reason is recorded in the conversation's activity history. Replies that pass are sent normally; their score and note are stored with the message. This check does not use extra credits: a customer message the agent answers costs one credit whether the reply was accepted first time or retried. ## Choosing the settings * **Minimum reply score**: start at the default 0.6. Raise it toward 0.7 only after checking the Inbox for replies that still got through with problems; every increase means more retries on borderline replies. * **Maximum retries**: each retry is a full new reply, so a customer can wait several times the normal response time when replies keep failing. Two or three is usually enough; a reply that fails three times rarely passes on the fourth. * **Hand over to your team after the last retry**: turn it on for agents whose wrong answers you would rather not send at all. Without it, the check can only improve replies, not stop them. ## Check replies and Spotlight This check works on each reply before it is sent. [Spotlight](/agents/spotlight) scores whole conversations after the fact on six dimensions and lists conversations to review. Use Spotlight to see whether the agent's replies are good enough in general, and **Check replies before sending** to enforce a minimum on every reply for a specific agent. ## Related * [Capabilities](/agents/capabilities): **Hand over to your team** and the other **How it replies** settings. * [Popcorn's rules and Voice](/agents/popcorns-rules) and [Writing custom instructions](/agents/writing-instructions): what the reviewer scores against. * [Troubleshooting AI agents](/agents/troubleshooting): slow responses and handovers that happen too often. # Agent capabilities Source: https://docs.trypopcorn.ai/agents/capabilities What each agent switch does: handover and handover topics, spam blocking, opt-outs, product recommendations, orders, follow-ups and more. Capabilities are the switches on the agent page that give the agent tools and behaviours beyond answering from its knowledge. They live on three tabs: **Instructions** (**How it replies**), **Actions** (**Selling and orders**, **Follow-ups**, **Safety**) and **Handoff** (with **Handover topics**). Like every other agent setting, a change is saved as a draft and reaches customers' conversations when you [publish](/agents/test-and-publish). > [!NOTE] > > The two follow-up switches, **Close resolved chats** and **Follow up when customers go quiet**, are the exception: Popcorn's background checks read the settings you last saved, so changes to those two switches and their timings apply as soon as you click **Save and review**, without waiting for **Publish changes**. **Check replies before sending** has its own page: [Check replies before sending](/agents/ai-manager). Alerts are covered in [Connect knowledge, tools, channels and notifications](/agents/connect-knowledge-tools-channels). ## Handoff tab ### Hand over to your team "Passes the chat to a person when the customer asks or your rule applies." With it on, the agent has a tool to stop answering and pass the conversation to your team. It uses the tool when the customer asks for a person, when the knowledge base tells it to forward something, when one of your handover topics or rules applies, or when a custom agent's instructions say so. An agent on [Popcorn's rules](/agents/popcorns-rules) also offers your team when Knowledge does not cover a question. * With the switch on, the tab also shows **Team hours** (your workspace's working hours from **Settings → General**; **Change** opens them there) and **Handover topics** (below). * Tick **Add your own handover rules** to write free-text triggers under **When to hand over**, for example "when a customer asks for a refund". The text is attached to the handover tool itself. Once the agent has handover topics, the tick box reads **Add other rules** and the field **Other rules** ("For anything the topics don't cover."), up to 2,000 characters. * If you use conversation tags (**Settings → Conversation tags**), the agent picks the tag that best describes the reason and applies it to the conversation, or the tag a matching topic names. * Once a chat is handed over, the agent stops replying there until someone hands it back. What happens on handover: 1. The conversation leaves the AI and appears in **Unassigned**, which also counts in the **Needs you** folder of the Inbox, with a line in the conversation saying why it came to your team (see [How the Inbox names the reason](/inbox/overview#how-the-inbox-names-the-reason)). 2. The customer gets a short message in their language confirming the handover, with your words when a topic's **What the agent says** applies. It is sent even if the customer writes again while the agent is handing over. If the message cannot be written, Popcorn sends "One moment — let me get a team member to help you with this." or its Arabic equivalent, in the customer's language (both when it cannot tell). 3. Slack and email alerts are sent if you switched them on under **Alerts**, and your team gets an in-app notification titled **Conversation Handover** with the reason and a link to the conversation. > [!NOTE] > > **Hand over to your team after the last retry**, under **Check replies before sending**, depends on this switch. Turning **Hand over to your team** off while it is on shows **Handing over after the last retry is off too** and switches that option off. ### Handover topics "Chats about these always go to your team. The agent tells the customer what you wrote and tags the chat." Use topics for the kinds of chats your team always takes, such as bulk orders or complaints. They work on both agent types, while **Hand over to your team** is on. **1. Add a topic** On the **Handoff** tab, click **Add topic**. The **New topic** dialog opens: "The agent hands these chats to your team instead of answering them." **2. Describe the chats** Fill in the fields in the table below, then click **Add topic**. The topic joins the list; use the buttons on its row to edit or remove it. **3. Save and publish** Topics are saved with the agent: click **Save and review**, then **Publish changes**. | Field | What to enter | | - | - | | **Topic** | A name, such as "Corporate and bulk orders". Required, up to 80 characters, and different from your other topics' names. | | **When it applies** | "Describe these chats in plain words.", for example "The customer wants 20 or more pieces, or asks for a company invoice". Required, up to 400 characters. | | **What the agent says** | Optional, up to 400 characters, for example "Our sales team will send you a quote shortly." "Without it, the agent says someone from your team will reply." | | **Conversation tag** | Optional: one of your conversation tags, or **No tag**. "Tags the chat so the right people pick it up." | An agent can have up to 20 topics. A topic marked **From your instructions** was moved there from the agent's old instructions by the Knowledge check; one marked **Suggested** was added from a suggestion. **Suggested topics.** When the Knowledge check finds chats your team took over that fit a topic the agent does not have, the **Handoff** tab lists it under **Suggested topics**, with what the agent would say, the tag and how many chats it was seen in. **Add** adds the topic and publishes the agent right away (**Topic added and published**). It waits while the page has changes you have not saved (**Save or discard your changes to add a suggested topic.**) or a saved draft you have not published (**Publish your saved changes to add a suggested topic.**). The same suggestions come up in the review on **Knowledge** as **Should your team take these chats?**, where **Yes, hand them over** adds the topic the same way (see [Review what your agent learned](/knowledge/knowledge-check)). ## Actions tab ### Safety **Block spam and off-topic chats** — "Stops the agent replying to spam, fraud and attempts to pull it off topic." The agent flags messages that try to change its behaviour, hijack its instructions, or are spam, fraud, or off-topic, and refuses to answer them instead of replying. * Flags are counted per conversation. On the third flagged message, the conversation is handed over to your team exactly like a handover: it moves to **Unassigned** and **Needs you**, notifications go out, and the count resets. * It has no settings of its own. If legitimate customers are being refused, review the conversations it handed over in **Needs you** before deciding whether to keep it on. **Let customers opt out** — "Customers who ask to stop get no more campaign messages." When a customer tells the agent they no longer want messages, the agent marks them as unsubscribed. Campaigns leave unsubscribed customers out unless you choose to send to them (see [Customers](/customers/overview#subscribed-and-unsubscribed)), and how opt-outs count against a campaign is on [Delivery and reachability](/campaigns/delivery-and-reachability#unsubscribes). The agent does not stop replying to the customer's own messages. New agents start with it on, including the one onboarding creates. Agents that existed before were switched on once by Popcorn while their store had an active plan: an agent with nothing unpublished got a new published version, which open chats also moved to, with the note "Unsubscribe turned on: customers who ask to stop getting campaigns are unsubscribed."; an agent with a saved draft got it added to that draft, which you publish. If you turn it off, it stays off. ### Selling and orders These switches need a connected store (Shopify, Salla or Zid; see [Integrations](/integrations/overview)). Without one, the tools are created for Shopify by default and fail when the agent calls them. **Recommend products** — "Suggests products from your catalog." Gives the agent a catalog search and a way to send product cards. The agent searches by keywords or by a product link the customer shares, then sends the matching products as cards instead of describing them in text. Customers can also send a photo of a product; the agent searches by image and asks the customer to confirm the match. * With the cards, the agent writes a short text in short lines: the answer to the customer's question, why these products fit, and a closing question on its own line, such as which one they want. When it sends a single product from your WhatsApp catalog, the text goes inside the product card. * For a product with options, such as colours or sizes, search results tell the agent which options are for sale now and which are not, so it does not offer one your description names but you no longer sell. * A product that is not active, or out of stock while **Product quantities** is on in **Settings → General**, is never sent as a card. The agent can still answer about it and offers something available instead. Shopify products are never treated as out of stock. * A product counts as on sale only when its sale price is below its price; otherwise the agent and the card show the one price checkout charges. When this switch is on, a **Manage rules** button appears beside it. Rules decide which products to show first or exclusively for a given request; product weights (Boost, Normal, Hide) shape the results too. See [Recommendation rules](/products/recommendation-rules) and [Product catalog](/products/catalog). **Take orders in chat** — "Lets the agent place orders for customers." The agent can take an order inside the conversation: 1. Build a cart from the products it recommended, and add the product's custom options if it has any (required options must be chosen before ordering). 2. Collect the delivery address through a form (on WhatsApp, a form the customer fills in; Saudi customers can give their national address short code and the agent resolves it to a full address). 3. Prepare the order with the shipping and payment methods you set under **Settings → Shipping** and **Settings → Payment**, then send the customer a confirmation button. The order is only created in your store after the customer taps that button; a typed "yes" is not enough. When a customer shows interest in a product (names or picks one, asks its price, delivery or payment, or says yes after seeing it), the agent offers to prepare the order; when they agree, it starts the cart and asks only for what is still missing. It keeps the sale in the chat rather than sending the customer to your website or a branch. If your store has no payment method turned on, the agent does not create the order: it tells the customer your team will confirm how they can pay, and hands the conversation over. If a customer asks to pay with a method you have turned off, the order is refused. Orders created this way appear under **Orders** and link back to the conversation. See [Orders](/orders/overview) and [Shipping and payment](/settings/shipping-and-payment). **Track orders** — "Answers where an order is." Lets the agent look up the status of the customer's orders. The customer's phone number is used automatically, so a customer can simply ask "where is my order?"; if they give an order number, it is checked against the phone number. On Shopify, the agent asks for the email used at checkout only if the phone number does not match. **Send images in chat** — "Lets the agent send images, like product photos." Onboarding switches this on for your first agent. ### Follow-ups **Close resolved chats** — "Closes a chat the agent has resolved once the customer goes quiet." Popcorn closes conversations the agent has finished with, so the Inbox only shows what is still open. * **Close after (hours)**: how long a conversation must be quiet before it is closed, counted from the last message in the chat. Enter at least 1; new agents start at 24. * A conversation on one of the agent's WhatsApp numbers is closed when it is assigned to the AI, the last message came from the agent or your team (never when the customer wrote last, since a chat never closes while the customer is waiting on a reply), it is not snoozed, and no handover is pending. The check runs every 30 minutes. * The close is recorded in the conversation's activity history in the Inbox. If the customer writes again, a new conversation starts. * It cannot be switched off while **Follow up when customers go quiet** is on: the switch is locked and reads **Turn off follow-ups first.** Onboarding switches this on with a 24-hour window. **Follow up when customers go quiet** — "Sends a message when a customer stops replying before the chat is resolved." When a customer goes quiet with something still open, the agent sends one short follow-up that picks up where the chat stopped: the question it asked them, or the step they were about to take. It does not greet them again, repeat what it already said or start a new topic. | Field | Meaning | | - | - | | **Add your own follow-up instructions** | Tick it to add your own guidance under **Follow-up instructions**, for example "remind them about the items in their cart". | | **Number of follow-ups** | 1 to 5 follow-ups per conversation. | | **Follow-up 1 (hours)**, **Follow-up 2 (hours)**, … | For each follow-up, how many hours (1 to 23) to wait before sending it. The first value is the wait after the last reply to the customer, from the agent or your team; each later value is the wait after the previous follow-up. | How it runs: * Popcorn checks every 15 minutes, on WhatsApp only, for open conversations assigned to the AI on the agent's numbers where the customer wrote in the last 24 hours and the agent or your team replied after. Once the customer's last message is more than 24 hours old, no more follow-ups are sent, so the waits add up to less than a day in practice. * Before sending, Popcorn reads the conversation and follows up only when something is open: a question the customer has not answered, products they were sent but have not chosen from, an order, booking or details they stopped partway through, or a greeting they never followed with what they want. When it is unsure, it sends nothing. * It skips the follow-up when the conversation had ended (the question was answered, the customer ordered or said thanks or goodbye), the customer said no or asked not to be contacted, the sender is not a customer (a sales pitch, a job application, a supplier, an automatic reply, spam or a wrong number), or the chat was handed to your team or sent to another channel. The conversation then shows a line such as **Follow-up skipped: the customer said no** (see [See what the agent did](/inbox/working-conversations#see-what-the-agent-did)), and Popcorn does not check it again until the conversation moves on. * No follow-up is sent if the last reply was a template or failed to deliver, or if you replied to the customer from the WhatsApp Business app in the last 24 hours. * It requires **Close resolved chats**: while that is off the switch is locked and reads **Turn on closing resolved chats first.** The **Close after (hours)** value must also be longer than your longest follow-up wait, or the page shows **Enter more than N hours, so your last follow-up can send first.** Onboarding switches this on with one follow-up after 1 hour. ## Instructions tab: How it replies **Share customer details with the agent** — "Gives the agent details like the customer's phone number." The agent is told the customer's phone number, so it can quote it back or use it in tools. The customer's name and last delivery address are given to the agent regardless of this switch. Onboarding switches this on. **Split long replies** — "Sends a long reply as a few shorter messages, at no extra cost." A reply is sent as one message per paragraph (text separated by a blank line), so a list or an answer laid out over several lines stays in one message. It has no effect on a reply written as a single paragraph. **Delay replies** — "Waits a few seconds before replying, like a person typing." Before each reply, the agent waits a random number of seconds within the range you set with **Reply delay, in seconds** (1 to 60; new agents start at 14 to 34). On WhatsApp the customer's message shows as read and "typing…" appears through the wait, so the pause looks like someone writing. Leave it off if response time matters more than the human feel. **Check replies before sending** — "Scores each reply and tries again when it falls below your target." See [Check replies before sending](/agents/ai-manager). ## Quick reference | Switch | Tab | Needs | Default on a new agent | Default on the onboarding agent | | - | - | - | - | - | | **Hand over to your team** | **Handoff** | Nothing | Off | On | | **Block spam and off-topic chats** | **Actions** | Nothing | Off | Off | | **Let customers opt out** | **Actions** | Nothing | On | On | | **Recommend products** | **Actions** | Connected store | Off | Off, or On when you connected a store in setup | | **Take orders in chat** | **Actions** | Connected store, shipping and payment settings | Off | Off, or On when you connected a store in setup | | **Track orders** | **Actions** | Connected store | Off | Off, or On when you connected a store in setup | | **Send images in chat** | **Actions** | Nothing | Off | On | | **Share customer details with the agent** | **Instructions** | Nothing | Off | On | | **Split long replies** | **Instructions** | Nothing | Off | Off | | **Close resolved chats** | **Actions** | WhatsApp number | Off | On, 24 hours | | **Follow up when customers go quiet** | **Actions** | **Close resolved chats**, WhatsApp number | Off | On, 1 follow-up after 1 hour | | **Delay replies** | **Instructions** | Nothing | Off | Off | | **Check replies before sending** | **Instructions** | **Hand over to your team** for its handover option | Off | Off | On the **Create agent** page the **How it replies** switches, including **Send images in chat**, are on the **Actions** tab. ## Related * [Check replies before sending](/agents/ai-manager) * [Connect knowledge, tools, channels and notifications](/agents/connect-knowledge-tools-channels) * [Inbox overview](/inbox/overview): what the **Needs you** folder and closed conversations look like. * [Troubleshooting AI agents](/agents/troubleshooting): hands over too often or never, changes not taking effect. # Connect knowledge, tools, channels and notifications Source: https://docs.trypopcorn.ai/agents/connect-knowledge-tools-channels Give an agent knowledge bases and custom tools, attach WhatsApp numbers and the Website chat widget, and set where handover alerts go. An agent only answers from the knowledge bases it can read, only calls the tools connected to it, and only picks up conversations on the channels attached to it. All of this is set on the agent's own page, on the **Knowledge**, **Actions** (**Tools**), **Channels** and **Handoff** (**Alerts**) tabs. Like every other agent setting, these connections are saved as a draft and reach customers when you [publish](/agents/test-and-publish). ## Before you start * Click **Agent** in the sidebar and open the agent. You need a role that can edit agents. * Knowledge lives in knowledge bases. Create them and publish their articles under **Knowledge** in the sidebar first (see [Knowledge overview](/knowledge/overview)). * Custom tools are created under **Tools** first (see [Create a custom tool](/tools/create-a-tool)). A tool does not need to be public to be connected. * WhatsApp numbers are connected to the workspace under **Integrations → WhatsApp** before they can be attached to an agent (see [WhatsApp](/channels/whatsapp)). * Slack alerts need the agent to exist already: the **Create agent** page cannot connect Slack. ## Give the agent access to knowledge bases **1. Open the Knowledge tab** On the agent's page, open **Knowledge**. Every knowledge base in your workspace is listed with its name and description, and the tab shows how many are switched on. Above them, once the nightly Knowledge check has looked at this agent, **What it knows** says whether it has questions for you, with **Review** or **Open Knowledge** (see [Review what your agent learned](/knowledge/knowledge-check)). **2. Turn knowledge bases on or off** Switch on each one the agent should be able to read. Access is granted knowledge base by knowledge base, and the description helps the agent pick the right one for a question. **3. Create a knowledge base if you need one** **New knowledge base** (shown when you have none) and **Manage knowledge** (shown once you have some) take you to **Knowledge**. Come back and switch the new knowledge base on once it has articles. **4. Save and publish** Click **Save and review**, then **Publish changes**. Knowledge access is part of the published version, so customers only see the change after publishing. To check that articles are actually used and to test answers, see [Connect knowledge to agents](/knowledge/connect-to-agents). ## Connect custom tools Custom tools let the agent call your own systems during a conversation (see [Custom tools](/tools/overview)). **1. Find Tools on the Actions tab** On the **Actions** tab, scroll to **Tools** ("Actions you set up yourself or add from the marketplace."). Your workspace's custom tools are listed with a switch each. If you have none yet, it shows **No tools yet** with **Add tool**, which opens the tool builder, and **Open marketplace**, which opens the Tools Showcase. Once you have tools, **Add tool**, **Open marketplace** and **Manage tools** are at the bottom of the panel. **2. Switch a tool on** Turn on the tools this agent should be able to call. Turning a tool off removes it from the agent. **3. Save and publish** Click **Save and review**, then **Publish changes**. > [!NOTE] > > Connecting copies the tool into the agent, header values included, so a tool cannot be deleted while an agent still uses it: turn it off on each agent's **Actions** tab and save first. Editing the tool under **Tools** later updates the agent's copy. If a tool could not be enabled when you save, you see *Couldn't turn on … Your other changes were saved.* with the tool names; everything else is saved, so switch the tool on again and click **Save and review**. ## Attach channels ### WhatsApp numbers **1. Open the Channels tab** On the **Channels** tab, the **WhatsApp** panel ("The numbers this agent answers on.") lists every number connected to your workspace, each with a switch. **2. Switch numbers on or off** Switch on each number the agent should answer. **Add number** takes you to **Integrations → WhatsApp** to connect a new number. If you have no numbers yet, the panel reads **No WhatsApp numbers yet**. **3. Save and publish** Number changes are staged in the draft and take effect when you click **Publish changes**. What to expect: * A number can be attached to one agent at a time. Publishing fails with **One or more WhatsApp channels are connected to another agent** until you disconnect the number from the other agent. * A number that is attached to no agent is answered by the workspace's default agent. * An agent must have a published version before a number can be routed to it. * Switching a number off moves that number's open conversations to your default agent immediately when you publish, whatever you choose for open chats in the publish dialog. The dialog lists the numbers it applies to. **Manage sandbox numbers** on the same panel opens **Test on WhatsApp**, a shared test number for trying an agent on WhatsApp before connecting your own number. See [Test and publish](/agents/test-and-publish). ### Website chat widget The **Website chat widget** panel ("Paste this code into your website's HTML, just before the closing body tag.") shows an embed code that opens this agent in Website chat. Click **Copy code** (you see **Copied to clipboard**) and paste the snippet into your site. The name, avatar and welcome message Website chat shows are set under **Integrations → Website chat**; see [Website chat](/channels/website-chat). ## Get notified when the agent hands over The **Alerts** panel on the **Handoff** tab ("How your team hears about a handover.") controls where your team is alerted when a conversation leaves the AI. An alert is sent when the agent hands over through **Hand over to your team**, when **Block spam and off-topic chats** hands over after repeated flagged messages, and when Popcorn hands over on its own because the workspace has no credits, its plan through Zid has ended, no agent is available, or a reply could not be generated. A conversation handed over this way appears in **Unassigned** and in the **Needs you** folder in the Inbox. ### Slack **1. Turn on Slack alerts for handovers** Switch on **Slack alerts for handovers** ("Posts in Slack each time a chat is handed to your team."). **2. Connect Slack** The panel reads **Slack isn't connected, so these alerts won't arrive yet.** Click **Connect Slack**. Slack opens in a new window and asks you to authorize Popcorn and choose the channel that should receive the alerts. When the window closes you see **Slack is connected**; the panel then shows a **Connected** badge and the button becomes **Reconnect Slack**. If the window does not open, you see **Allow pop-ups for this site, then connect Slack again.** **3. Save again, then publish** Connecting Slack updates the agent directly. If you had already saved a draft, click **Save and review** again before publishing, otherwise publishing stops with **Draft is out of date with the live agent configuration**. Each Slack alert is titled **Human Handover** and includes the customer's name and phone number, their email if known, the tag applied by the handover if any, and a link to the conversation. ### Email **1. Turn on Email alerts for handovers** Switch on **Email alerts for handovers** ("Emails your team each time a chat is handed over."). **2. Add recipients** Type an address under **Add a recipient** and press Enter or click **Add**. Recipients appear under **Recipients**; remove one with the **X** on its chip. An address that is already listed cannot be added twice (**This address is already on the list.**), and you need at least one (**Add at least one email address.**) before the agent can be saved. **3. Save and publish** Click **Save and review**, then **Publish changes**. Every recipient receives an email with the subject **Human Handover - Popcorn AI**, the customer's name, phone number and email if known, and a **View Conversation** button. ## Related * [Test and publish an agent](/agents/test-and-publish): drafts, the publish dialog, version history and rollback. * [Capabilities](/agents/capabilities): the handover and safety settings that decide when a handover happens. * [Working conversations](/inbox/working-conversations): what your team does with a handed-over conversation. * [Troubleshooting AI agents](/agents/troubleshooting). # Create an agent Source: https://docs.trypopcorn.ai/agents/create-an-agent Create a new AI agent with New agent: choose its type, name it, switch on what it can do, then publish it for customers. Onboarding already created your first agent and set it as the default. Create another agent when a WhatsApp number or website needs different behaviour, for example a support agent that only answers from your policies and a sales agent that recommends products and takes orders. Every agent has its own type (Popcorn's rules with a **Voice**, or custom instructions), capabilities, knowledge, tools and channels. ## Before you start * Decide the agent's type, which cannot be changed later. An agent on **Popcorn's rules** (recommended) needs no instructions: Popcorn decides how it sells, answers and hands over, and you set its **Voice**. An agent on **Custom instructions** runs on instructions you write, which are then required; **Draft with agent** can write them from a short description. See [Popcorn's rules and Voice](/agents/popcorns-rules). * If the agent should answer from your own information, create the knowledge bases and publish their articles first under **Knowledge** in the sidebar (see [Knowledge overview](/knowledge/overview)). * **Recommend products**, **Take orders in chat** and **Track orders** work through your connected store (see [Integrations](/integrations/overview)). * Plan to publish right after creating the agent. A new agent has no published version, so a WhatsApp number you switch on for it starts answering only after you publish. ## Create the agent **1. Open New agent** Click **Agent** in the sidebar, then **New agent**. The **Create agent** page opens. It has the same five tabs as an existing agent: **Instructions**, **Knowledge**, **Actions**, **Handoff** and **Channels**. **2. Choose the agent type** On the **Instructions** tab, under **Agent type**, keep **Popcorn's rules** (**Recommended**) or choose **Custom instructions**. "You can't change the type after the agent is created." **3. Name the agent** Under **Profile**, fill in **Agent name**. Creating the agent without one shows **Give the agent a name**. **4. Write the instructions (custom instructions only)** For a custom agent, describe in **Instructions** your store, how the agent should talk to customers and what it should never do, or click **Draft with agent** to have it write a first draft. Creating a custom agent without instructions shows **Add instructions so the agent knows how to reply**. See [Writing custom instructions](/agents/writing-instructions). An agent on Popcorn's rules has no instructions field. **5. Choose knowledge** On the **Knowledge** tab, switch on each knowledge base the agent may answer from. **New knowledge base** takes you to **Knowledge** if you still need to create one. **6. Switch on what it can do** On the **Actions** tab, **Selling and orders** has **Recommend products**, **Take orders in chat** and **Track orders**; **How it replies** has **Send images in chat**, **Share customer details with the agent**, **Split long replies**, **Delay replies** and **Check replies before sending**; **Follow-ups** has **Close resolved chats** and **Follow up when customers go quiet**; **Safety** has **Block spam and off-topic chats** and **Let customers opt out**. Under **Tools**, switch on any custom tools the agent may call (**Add tool** and **Open marketplace** are there if you have none yet). Each setting is described in [Capabilities](/agents/capabilities). **7. Set up handing over** On the **Handoff** tab, switch on **Hand over to your team** if the agent should pass chats to a person, and choose how your team hears about it under **Alerts**. See [Connect knowledge, tools, channels and notifications](/agents/connect-knowledge-tools-channels). **8. Create it** Click **Create agent**. You see **Agent created** and land on the new agent's page. If something did not save you see **Agent created, but some settings didn't save**, or **Agent created, but these tools weren't added** with the tool names: the agent exists with everything else you chose, so check those settings on its page and click **Save and review**. If a field needs fixing when you click **Create agent**, the tab that holds it shows a count of the fields to fix, and the page opens the first tab that has one. Some settings are not on the **Create agent** page and wait until the agent exists: * Connecting a WhatsApp number: the **Channels** tab reads **You can connect WhatsApp numbers after you create the agent.** Switch numbers on from the agent's page (see [Connect knowledge, tools, channels and notifications](/agents/connect-knowledge-tools-channels)). * Slack alerts: under **Handoff**, switching on **Slack alerts for handovers** reads **Create the agent first, then connect Slack on its page.** * The **Voice** of an agent on Popcorn's rules: it starts with the default Voice, which you change on the agent's **Instructions** tab (see [Popcorn's rules and Voice](/agents/popcorns-rules)). * **Handover topics**, on the agent's **Handoff** tab (see [Capabilities](/agents/capabilities)). ## Default values on the form Every switch starts off except **Let customers opt out**, which starts on. Fields that appear when you switch something on start with these values: | Field | Starts at | | - | - | | **Reply delay, in seconds** (under **Delay replies**) | 14 to 34 seconds | | **Close after (hours)** (under **Close resolved chats**) | 24 | | **Number of follow-ups** (under **Follow up when customers go quiet**) | 3, with **Follow-up 1 (hours)**, **Follow-up 2 (hours)** and **Follow-up 3 (hours)** set to 1, 2 and 5 | | **Minimum reply score (0 to 1)** (under **Check replies before sending**) | 0.6 | | **Maximum retries** (under **Check replies before sending**) | 3 | ## Publish the new agent A new agent has no published version yet. Its header shows **Not published yet** and reads "Set up your agent, then save and publish it." Until you publish, a WhatsApp number you switch on under **Channels** does not route to the agent, and the agent cannot be chosen with **Set as default** (the menu item reads **Publish to set as default**). **1. Make the first save from the agent page** Change anything on the agent page, for example switch on a WhatsApp number under **Channels**, and click **Save and review**. The first save records the agent as it was when created as a published version with the note **Initial published version**, and your edits become a draft. **2. Publish** In the **Publish changes?** dialog, which says "Nothing is published yet, so this will be the first version.", click **Publish changes**. See [Test and publish](/agents/test-and-publish). **3. Route conversations to it** Switch on a WhatsApp number under **Channels** and publish again, paste the **Website chat widget** embed code on your site, or choose **Set as default** from the agent's row menu on the **Agents** page. > [!TIP] > > Use the test chat on the agent page to try the agent before connecting a live number: from 1280 pixels wide it sits beside the settings, and below that the **Test agent** button in the header opens it. Once the agent has a published version, the chat uses it. Test conversations appear in your Inbox and each AI reply uses one credit, like a real conversation. ## The agent onboarding created The agent created during onboarding is named after your business (for example **Noor Perfumes Assistant**), already has a published version, and starts with a different setup than a blank **New agent**: * It runs on **Popcorn's rules** with the default **Voice**. Open the agent to change the Voice on its **Instructions** tab (see [Popcorn's rules and Voice](/agents/popcorns-rules)). * The knowledge base built from your website pages already connected. * **Hand over to your team** and **Let customers opt out** switched on. * **Send images in chat** and **Share customer details with the agent** switched on. * **Close resolved chats** switched on with a 24-hour window, and **Follow up when customers go quiet** switched on with one follow-up after 1 hour. * **Delay replies** and **Check replies before sending** switched off. * **Recommend products**, **Take orders in chat** and **Track orders** off at first. If you connected a store during setup, the second step switches all three on and publishes the change, with the version note "Store connected: the agent can now share products, take orders and track them." Without a store they stay off. Open it from the **Agents** page to review these settings before you connect a live number. ## Related > **[Popcorn's rules and Voice](/agents/popcorns-rules)** > > The two agent types, and how to set an agent's **Voice**. > **[Capabilities](/agents/capabilities)** > > What each switch on the **Actions** and **Handoff** tabs does. > **[Connect knowledge, tools and channels](/agents/connect-knowledge-tools-channels)** > > Attach knowledge, WhatsApp numbers, Website chat and handover alerts. > **[Test and publish](/agents/test-and-publish)** > > Drafts, the publish dialog and version history. # AI agents overview Source: https://docs.trypopcorn.ai/agents/overview What an AI agent is in Popcorn, how to read the Agents page, what the default agent does, and how an agent picks up conversations. An AI agent is what answers your customers on WhatsApp and Website chat: [Popcorn's rules](/agents/popcorns-rules) in the Voice you choose (or, for a custom agent, instructions you write), plus the knowledge, capabilities and channels you give it. Most workspaces run one agent, created during onboarding and set as the default. Create more when different numbers or sites need different behaviour, for example a sales agent on one WhatsApp number and a support agent on another. Click **Agent** in the sidebar, under **Your agent**, to open the **Agents** page with every agent in your workspace. ## The Agents page | Column | What it shows | | - | - | | **Name** | The agent's name, with a **Default** badge on the workspace's default agent. Under the name: the WhatsApp number it answers on (with "and N more" when it has several), or **No WhatsApp number**. | | **Status** | **Live on WhatsApp**, **Not on WhatsApp yet** (published, but no number connected), **Not published yet**, **Stopped, out of credits**, or **Stopped, plan ended** (your plan through Zid has ended; renew it to turn the agent back on, see [When a Zid plan ends](/billing/plans-and-credits#when-a-zid-plan-ends)). | | **Conversations** | The number of WhatsApp conversations on the numbers this agent handles. | | **Last interaction** | When a conversation handled by this agent was last updated, as relative time. **Never** means it has not handled a conversation yet. | | **Updated** | The date the agent was last saved. | Use **Search agents** to filter by name. The page shows 10 agents at a time. On a narrow screen the **Status** and **Conversations** columns move under the agent's name. Click a row to open the agent. The **⋯** menu on each row (**More actions**) has: * **Edit**: opens the agent. * **Set as default**: makes this agent the workspace default. It reads **Publish to set as default** and stays disabled until the agent has a published version. You need a role that can manage agents to see this option. * **Delete**: removes the agent after you confirm **Delete agent** in the dialog. This cannot be undone. The option is disabled for the default agent and reads **Set another default to delete**. ## The default agent Every workspace has one default agent. It handles: * Every WhatsApp number that is not connected to a specific agent. * Website chat conversations whose embed code does not name an agent. * Conversations on a number whose agent is disconnected. When you publish a change that disconnects a number, its open conversations move to the default agent immediately. Onboarding creates your first agent and sets it as the default. To change the default later, publish the agent you want to use, then choose **Set as default** from its row menu. You cannot delete the default agent; set another agent as default first. ## How an agent picks up a conversation 1. A customer writes to one of your WhatsApp numbers or through Website chat. 2. Popcorn routes the conversation to the agent connected to that number, or to the default agent if the number has no agent of its own. Website chat conversations go to the agent named in the embed code you installed. 3. The conversation starts on the agent's published version and stays on it until you publish a change and choose to apply it to open chats. Unpublished drafts never reach customers. 4. Each customer message the agent answers uses one credit, on WhatsApp, Website chat, the **Test agent** chat on the agent page and the WhatsApp sandbox alike. Campaign messages are charged separately, through the campaign. The one exception is the chat on **Home** during setup, which is free (see [Test and publish an agent](/agents/test-and-publish)). 5. On WhatsApp, the customer's message is marked as read and shows "typing…" while the agent works on its reply. The indicator disappears when the reply arrives, or after at most 25 seconds if no reply is coming. If the workspace runs out of credits, its plan through Zid has ended, or no valid agent is configured, Popcorn hands the conversation over to your team rather than leaving the customer without an answer. The conversation appears in **Unassigned** and in the **Needs you** folder in the Inbox, and the agent's handover alerts are sent if you enabled them. See [Inbox overview](/inbox/overview). Customers can also send voice notes: Popcorn transcribes each one and the agent answers what was said. When a voice note has no speech in it, or cannot be transcribed, the agent asks the customer to send it again or type their message. ## What is on an agent's page The header shows the agent's name, a status badge and, when the agent is live, the version new chats use ("New chats use v3, published Sep 12, 2026."). Its buttons are **Version history**, **Test agent** and **Save and review** (or **Publish changes** once a draft is saved). From 1280 pixels wide, the test chat sits beside the settings and the **Test agent** button is not shown. The settings are on five tabs: | Tab | What you set there | | - | - | | **Instructions** | **Name**, then **Voice** for an agent on Popcorn's rules, or **Instructions** (with **Draft with agent**) for a custom agent; then **How it replies**: **Split long replies**, **Delay replies**, **Check replies before sending**, **Share customer details with the agent**. See [Popcorn's rules and Voice](/agents/popcorns-rules), [Writing custom instructions](/agents/writing-instructions) and [Capabilities](/agents/capabilities). | | **Knowledge** | **What it knows**, once the nightly Knowledge check has looked at this agent (whether it has questions for you, with **Review** or **Open Knowledge**), then which knowledge bases the agent answers from, with **Manage knowledge**. See [Connect knowledge, tools and channels](/agents/connect-knowledge-tools-channels). | | **Actions** | **Selling and orders** (**Recommend products**, **Take orders in chat**, **Track orders**, **Send images in chat**), **Follow-ups** (**Close resolved chats**, **Follow up when customers go quiet**), **Safety** (**Block spam and off-topic chats**, **Let customers opt out**) and **Tools**. See [Capabilities](/agents/capabilities) and [Custom tools](/tools/overview). | | **Handoff** | **Hand over to your team** with **Team hours**, **Handover topics**, your own rules and **Suggested topics**, and **Alerts** by Slack or email. See [Capabilities](/agents/capabilities). | | **Channels** | The agent's **WhatsApp** numbers, **Manage sandbox numbers**, and the **Website chat widget** embed code. | Edits are saved as a draft. Customers keep talking to the published version until you click **Publish changes**. The two follow-up schedules are the exception and apply on save; see [Capabilities](/agents/capabilities). ## Related > **[Create an agent](/agents/create-an-agent)** > > Set up a new agent from **New agent** and publish it. > **[Popcorn's rules and Voice](/agents/popcorns-rules)** > > How the agent behaves, and how to set how it sounds. > **[Test and publish](/agents/test-and-publish)** > > Try changes, publish them and roll back. > **[Capabilities](/agents/capabilities)** > > What each switch does and when to turn it on. > **[Spotlight](/agents/spotlight)** > > Performance scores and conversations to review. > **[Troubleshooting](/agents/troubleshooting)** > > Agent not replying, wrong answers, changes not taking effect. # Popcorn's rules and Voice Source: https://docs.trypopcorn.ai/agents/popcorns-rules How an agent on Popcorn's rules behaves, how to set its Voice and reply language, and where your own rules go instead. Most agents run on **Popcorn's rules**: Popcorn writes and tests how the agent sells, answers and hands over, and you choose how it sounds with its **Voice**. What it knows comes from your Knowledge, which you keep true with the help of the Knowledge check: every night it learns from your team's replies in chats and asks you before it adds anything (see [Review what your agent learned](/knowledge/knowledge-check)). What the agent can do comes from the capabilities you switch on. This page explains what the rules make the agent do, how to set the Voice, and where to put the rules you used to write as instructions. ## The two agent types Every agent has a type, chosen under **Agent type** on the **Create agent** page: | Type | What it means | | - | - | | **Popcorn's rules** (marked **Recommended**, and selected by default) | "Popcorn writes and tests how the agent sells, answers and hands over. You keep its Knowledge up to date." The agent has no instructions box: its **Instructions** tab shows **Voice** instead. | | **Custom instructions** | "You write how the agent behaves. For special cases: Popcorn's support for custom agents is limited." The agent runs on the instructions you write; see [Writing custom instructions](/agents/writing-instructions). | "You can't change the type after the agent is created." To use the other type, create a new agent and move your WhatsApp numbers to it. To see an agent's type, open its **Instructions** tab. An agent on Popcorn's rules reads "Runs on Popcorn's rules: Popcorn writes and tests how it sells, answers and hands over. You keep its Knowledge up to date." A custom agent shows its **Instructions** box with **Draft with agent**. ## What Popcorn's rules make the agent do The rules are the same for every store, filled in with your business name and the agent's Voice. When Popcorn improves them, every agent on Popcorn's rules gets the change without you publishing anything. A store that sells products gets a sales agent; a business without products gets a support agent. The agent: * Replies to greetings naturally, and searches your Knowledge before answering any question about your products, services or policies, even one that looks off-topic. * Answers from Knowledge directly when it covers the question, even in part. * Never guesses about your business. When neither Knowledge nor a tool covers a point, it says it can't confirm that point and offers to bring in your team, and hands over when the customer accepts or the request needs a person. * Says, for a question outside your business, that it has no details and offers help with what you do. * Says it is passing the customer to your team only in a reply where it actually hands over, and uses the handover when your Knowledge says to forward something to the team. * Says it is an AI assistant, not an employee. It does not make appointments, bookings or commitments for your business, and does not promise outcomes or give instructions your Knowledge does not contain. * Recommends only what can be bought now. It can answer about a product that is out of stock or not for sale (that it exists, its price, that it is not available now), but offers an available alternative instead of recommending it. Shopify products are never treated as out of stock, so this applies to them only when they are not active (see [Products the agent can't sell](/products/catalog#products-the-agent-cant-sell)). * Asks one question at a time. Its replies are written for a phone: the answer in the first line, which is often all the notification shows; one idea per line with a blank line before its question; WhatsApp's own formatting used sparingly (bold for a product name, price or date, and "- " lines for several options); a phone number, order number, code or link on a line of its own; and caveats only when they help the customer decide, never an account of how its search went. > [!TIP] > > Keep **Hand over to your team** switched on (**Handoff** tab). Popcorn's rules offer your team whenever Knowledge does not cover a question, and the agent can only hand over with that switch on. What the agent can do (recommend products, take orders, track orders, hand over) still depends on the switches on its **Actions** and **Handoff** tabs; see [Capabilities](/agents/capabilities). ## Set the Voice **1. Open the Voice** Click **Agent** in the sidebar and open the agent. On the **Instructions** tab, **Voice** ("How the agent sounds to your customers.") is below **Profile**. **2. Choose the settings** Pick each setting from the table below. An agent whose Voice you never changed runs with the defaults. **3. Preview the replies** Click **Preview replies** to hear the Voice before you save (see below). **4. Save and publish** Click **Save and review**, then **Publish changes**. The Voice is part of the agent's version, so customers and the test chat get it only once you publish. In the publish dialog the change counts under **Messaging and notification settings**, and **Show before and after** lists it as **Voice**. | Setting | Options | Default | | - | - | - | | **Arabic style** | **Saudi dialect**, **Gulf dialect** or **Formal Arabic**: how the agent writes when it replies in Arabic. | **Saudi dialect** | | **Reply language** | **Same as the customer**, **Always Arabic** or **Always English** (see below). | **Same as the customer** | | **Tone** | **Friendly**, **Professional** or **Playful**. | **Friendly** | | **Reply length** | **Short** keeps replies under about 50 words where it can; **Normal** under about 100, answering fully. | **Short** | | **Name it introduces itself by** | Optional, up to 60 characters. Leave it empty to use the agent's name. | Empty | | **Use emoji** | "A few, where they suit the message." Off, the agent uses none. | On | ### Preview the Voice The test chat answers with the published version, so it cannot show a Voice you have not published. **Preview replies** answers three sample customer messages in the Voice on the page: a greeting in Arabic asking about men's perfumes and their prices, a question in Arabic about delivery to Riyadh, and a question in English about returns. "The samples don't use your Knowledge or store data", so the replies stay general and say the agent will check the details for the customer. Previews use no credits. After you change a setting, the preview shows **You changed the voice since this preview.**; click **Preview again**. If the preview fails you see **Couldn't preview the voice**, or **No sample replies came back. Try again.** ## Reply language With **Same as the customer**, Popcorn works out the language of each reply from the customer's own words and tells the agent before it writes: * The customer's latest message that says something decides. A greeting, a "thanks", a link, a code or a product name on its own does not switch the language; the agent keeps the language of their earlier messages. * A customer who asks for a language by name ("English please") gets it. * A customer who writes in another language, such as French or Urdu, gets replies in that language. * The words of a voice note and the caption under a photo count; a photo, sticker or tapped button does not. * The agent translates what it uses from your Knowledge and tool results, and keeps product names as your store writes them. With **Always Arabic** or **Always English**, every reply is in that language, whatever the customer writes. **Arabic style** has no effect with **Always English**. An agent on custom instructions does not get this: the language of its replies follows its instructions. ## Where your rules go An agent on Popcorn's rules never reads instructions, so each rule you would have written has its own place: | You want the agent to | Set it here | | - | - | | Know a fact about your store: delivery, payment, returns, fees, opening hours | An article in [Knowledge](/knowledge/overview) | | Pass certain chats to your team, say something specific and tag them | **Handover topics** on the **Handoff** tab (see [Capabilities](/agents/capabilities)) | | Sound a certain way, reply in one language or use a name | **Voice** | | Show certain products first, or only certain products, for a request | [Recommendation rules](/products/recommendation-rules) | | Follow up in a certain way | **Add your own follow-up instructions** on the **Actions** tab | | Offer only the payment and delivery options you support | **Settings → Payment** and **Settings → Shipping** (see [Shipping and payment](/settings/shipping-and-payment)) | ## Agents that had their own instructions When Popcorn's rules became the default, agents that already existed were switched to them, apart from a few that kept custom instructions. If an agent was answering customers with its own instructions, Popcorn first saved those instructions word for word as a published Knowledge article named "Previous instructions of" followed by the agent's name, in the agent's Knowledge. The agent no longer reads its instructions, but finds every fact they held when it searches Knowledge. On the **Knowledge** page, the Knowledge check asks whether to keep each fact from it (**Keep this?**) and, once each has a home of its own, offers to remove it (**Remove the old instructions?**). You can also edit or delete it yourself, but deleting it before its facts have moved takes them away from the agent. See [The old instructions article](/knowledge/knowledge-check#the-old-instructions-article). ## Related * [Create an agent](/agents/create-an-agent): choose the type when you create an agent. * [Capabilities](/agents/capabilities): what the agent can do, including handover topics. * [Test and publish](/agents/test-and-publish): publish a Voice change and test the result. * [Writing custom instructions](/agents/writing-instructions): for agents of type **Custom instructions**. # Spotlight Source: https://docs.trypopcorn.ai/agents/spotlight Read your agent's Performance score, the six quality areas, resolution and sentiment breakdowns, and the conversations to review. Spotlight scores your closed conversations the way a QA manager would and rolls the results up into one **Performance score**, six quality areas, and a list of the conversations most worth reading. Use it to find out where an agent, or a teammate, loses customers, and to check whether a change you published made things better. > [!NOTE] > > Spotlight is free during beta: the page shows a **Free during beta** badge, and scoring does not use credits. ## Before you start * Spotlight needs at least 10 evaluated conversations in the view you are looking at. Until then the page shows **Getting started** with a progress count ("N of 10 evaluated"). If your filters leave fewer than 10 it reads **Not enough conversations match these filters**, shows how many match, and offers **Clear filters**. * A conversation is evaluated after it is closed, if the customer sent at least two messages. Popcorn looks for newly closed conversations every 15 minutes, so scores appear shortly after a conversation is closed. Conversations older than 120 days are not evaluated. * Every participant is scored separately: the AI agent and each teammate who replied. A conversation with both counts once in the conversation totals. ## Open Spotlight and filter **1. Go to Spotlight** Click **Spotlight** in the sidebar, under **Your agent**. The last 7 days are shown; switch to **14 days**, **30 days** or **Custom** (pick **From** and **To**, then **Apply**) at the top. **2. Narrow the view** Use **Everyone** to pick one agent or teammate (each entry shows its number of evaluations), **All types** for **Sales**, **Support** or **General**, and **All sentiments** for **Positive**, **Neutral**, **Negative** or **Frustrated**. **3. Choose who handled the conversations** **All**, **Agent**, **Agent and team** and **Team** filter by who replied: everyone, only the AI, both, or only your team. Comparisons such as "vs previous period" always use the period of the same length immediately before your date range. Conversations are placed in a range by the date they started. ## Performance score The **Performance score** is the average of all evaluations in the range, **out of 5**, with the change against the previous period next to it and the number of conversations it covers. **Score over time** plots the daily score across the range (hourly when the range is a single day) and appears once there are at least two points; until then it reads "Not enough data to draw a trend yet." Each evaluation's score is a weighted average of the six areas below. ## Score by area | Area | What it measures | Weight | | - | - | - | | **Understanding** | Understood what the customer wanted | 20% | | **Resolution** | Solved what the customer needed | 25% | | **Accuracy** | Gave correct information | 20% | | **Communication** | Clear and in your brand's tone | 15% | | **Instructions** | Followed your instructions | 10% | | **Helpfulness** | Offered help before being asked | 10% | Each area is scored from 1 to 5, and each card shows the average with its change and a small trend line. The scale is deliberately strict: * 3 means the job was done adequately. A correct answer with no problems is a 3, not higher. * 4 needs clear evidence of doing more than expected; 5 is exceptional and rare. * 2 means something went meaningfully wrong; 1 means the customer experience was harmed. * Short exchanges (a greeting, a single question and answer) cannot score above 3 on Understanding, Resolution, Communication or Helpfulness. * **Instructions** compares the AI's replies with the agent's instructions: Popcorn's rules with its Voice, or your custom instructions. Teammates are not judged on instructions and always get a 3 there. * A handover is not automatically a failure: handing over something the agent could have answered from its knowledge or tools scores low, handing over something it genuinely could not resolve scores as adequate. ## Key figures | Figure | Meaning | | - | - | | **Resolution rate** | Share of evaluations whose resolution was **Confirmed** or **Assumed**, with the change against the previous period | | **Conversations** | Evaluated conversations in the range, with the percentage change against the previous period | | **Resolved** | Number of confirmed or assumed resolutions, "of" the evaluation total | | **Escalated** | Evaluations that ended in a handover, as a share of the total | ## Breakdowns **How conversations ended** * **Confirmed**: the customer explicitly said the issue was solved. * **Assumed**: a concrete answer was given and the customer kept engaging, without confirming. * **Escalated**: the conversation was handed over to someone else. * **Abandoned**: the customer stopped replying, or nothing was resolved. **Customer sentiment** counts **Positive**, **Neutral**, **Negative** and **Frustrated** customers, judged from the customer's messages during that participant's part of the conversation. **Conversation types** splits conversations into **Sales** (browsing or buying), **Support** (a problem or an existing order) and **General** (greetings, mixed or unclear intent). Both show a stacked chart over time once the range has at least two points (two days, or two hours when the range is a single day). ## Conversations to review The table ("The lowest-scoring conversations, which may need a look") lists up to ten conversations with the lowest score in the range, one row per conversation. Each row shows the **Score**, the **Main issue** (the evaluator's note on the lowest-scoring area), the **Sentiment**, the **Type** and the **Date**. Click **Review** to open the conversation in the Inbox, or **View inbox** to go to the Inbox itself. When nothing scored low, the section reads **All conversations look good**. In the Inbox, a closed conversation that scored below 3.5 shows a **Quality score** card in the conversation details with the main issue; **Details** expands the score of every area and **Hide** collapses it. ## Acting on what you see | If this is low | Look at | | - | - | | **Instructions** | The agent's Voice on [Popcorn's rules](/agents/popcorns-rules), or its [custom instructions](/agents/writing-instructions): the evaluator found replies that contradict or skip them. | | **Accuracy** | The [knowledge bases](/knowledge/overview) the agent can read and your product data; wrong prices, policies or product details come from what the agent was given. | | **Resolution** with many **Escalated** | Handover settings and missing tools or knowledge, see [Capabilities](/agents/capabilities) and [Connect knowledge, tools, channels](/agents/connect-knowledge-tools-channels). | | **Helpfulness** | Whether the instructions ask the agent to suggest products or next steps; a bare answer scores 3. | Filter by **Everyone** to compare agents, or to see how teammates score after a handover. After publishing a change, compare the score of the following period with the one before it. Per-version outcome figures are also listed in the agent's **Version history**; see [Test and publish](/agents/test-and-publish). ## Related * [Check replies before sending](/agents/ai-manager): the real-time check that retries weak replies before they are sent. Spotlight scores whole conversations after they close. * [Reports](/analytics/reports): volumes, response times and handover rates. # Test and publish an agent Source: https://docs.trypopcorn.ai/agents/test-and-publish Try an agent in the test chat or on WhatsApp, publish a draft to new or open chats, and use version history to roll back. Customers always talk to the published version of an agent. Everything you change on the agent page, from instructions to connected numbers, is saved as a draft first, so you can review the exact differences and decide which conversations get the update. Every publish and rollback is kept in the version history. ## How drafts and versions work * Editing anything shows a banner such as **2 unpublished changes. Live conversations use the published version.** with **Discard**, and the header button becomes **Save and review**. **Discard** returns the page to the last saved state. On a phone, **Save and review** and **Discard** are pinned across the top of the page. * **Save and review** checks your fields (a field to fix opens its tab), saves your changes to the agent, creates a draft and opens the **Publish changes?** dialog. There is one draft per agent; saving again updates it. If you close the dialog without publishing, the header button becomes **Publish changes**. * The first time you save an agent that has no versions yet, Popcorn also records the agent as it was before your edits as a published version with the note **Initial published version**, so you always have something to roll back to. * Until you publish, the published version keeps answering customers. The page tells you where you are: **This agent isn't published yet. Publish it to start answering customers.**, the unpublished-changes banner above, or, once nothing is waiting, "New chats use v4, published Sep 12, 2026." * Publishing needs a role that can edit agents. ## Try the agent in the test chat **1. Open the test chat** On the agent page, from 1280 pixels wide, the **Test your agent** panel sits beside the settings. On a narrower screen, click **Test agent** in the header (**Test** on a phone) to open it in a dialog titled **Test** followed by the agent's name. **2. Chat as a customer** Type a message and send it. Under each reply, a line shows what the agent did: **Searched the knowledge base** or **Used** followed by the tool's name. A reply that has just arrived shows that line once the conversation is opened again. When the agent hands over, the chat shows **Handed to your team**. **3. Start over when needed** **Start a new conversation** asks **Start a new conversation?**; click **Start over** to begin a fresh one. **Open in new tab** opens the same chat in a tab. > [!NOTE] > > The test chat talks to the **published** version, exactly like your customers. Edits you have saved but not published are not reflected. To try a change, publish it, then start a new conversation so the next message starts on the new version. To hear a **Voice** before you publish it, use **Preview replies** on the **Instructions** tab instead (see [Popcorn's rules and Voice](/agents/popcorns-rules)). (A brand-new agent has no published version until its first save on the agent page; until then the test chat uses the settings it was created with.) Test conversations are real conversations: they appear in your Inbox and each AI reply uses one credit like any other. If the workspace is out of credits, the chat shows **Your agent stopped replying to customers** with **Top up credits** (or **Choose a plan** on the free plan). ### The free test chat on Home While your workspace has no WhatsApp number connected and no customer conversations yet, **Home** shows your agent's setup with a **Try your agent** panel ("Ask what a customer would. Nothing is sent to WhatsApp."). The same chat appears during onboarding as **Try it as a customer**. Chats there are free: they use no credit, they are kept in **Test conversations** (under **More folders** in the Inbox) so reports and lead counts leave them out, and a handover in them alerts nobody. Chats started from the agent page, the **Test agent** dialog or the sandbox are not free tests. ## Try the agent on WhatsApp with the sandbox The sandbox is a shared Popcorn test number, useful before you connect your own WhatsApp number. It is answered by your workspace's **default** agent. **1. Open the sandbox** On the agent's **Channels** tab, click **Manage sandbox numbers**. The **Test on WhatsApp** dialog ("Chat with your agent from your own phone before customers do.") opens. **2. Register your phone** Under **1. Add the phone you'll test from**, enter your WhatsApp number with the country code under **Your phone number** and click **Add number**. You see **Number added** (with **Undo**), and the number is listed as **No messages yet** until it sends its first message, then **Active**. If it fails, check the number: a phone can test with only one Popcorn AI account. **3. Message the test number** Under **2. Message the test number**, scan the QR code with your phone or click **Open WhatsApp**, and send the pre-filled message. The default agent replies on WhatsApp; the conversation appears in your Inbox and uses credits like a live conversation. Remove a number with the button next to it (**Remove** followed by the number). If your number is not registered, the sandbox replies that it is not linked to any organization. If the workspace has no default agent, it replies that your organization does not have a default agent set up yet; choose one from the **Agents** page with **Set as default**. ### Start over on WhatsApp When you test from your phone, on the sandbox or on one of your own numbers, you can reset the chat by sending a command on its own, exactly as written: | Send | What happens | | - | - | | `/reset` (or `/start`) | Your next message starts a new conversation. The agent still remembers your earlier conversations with that number, as it does for any returning customer. | | `/reset-all` | Your next message starts a new conversation, and the agent forgets everything from that number before the reset: earlier messages and their summary, past orders, and the address given before. Use it when a test should start clean. | Popcorn answers the command itself, without the agent, so it uses no credit: "Conversation reset successfully. Please send a message to start a new conversation." (or "Conversation and history reset successfully. …" for `/reset-all`). Everything stays in your Inbox. The commands work for anyone who messages your numbers, customers included. ## Publish changes **1. Save and open the review** Click **Save and review** (or **Publish changes** in the header when a draft already exists). The **Publish changes?** dialog opens ("Customers get these changes once you publish."). **2. Check what changed** **What changed** lists the areas that differ from the published version, with a count: **Name and instructions**, **Messaging and notification settings**, **Capabilities, tools and knowledge**, and **Connected WhatsApp numbers**. Click **Show before and after** to compare **Before** and **After** field by field. For an agent with nothing published, the dialog says "Nothing is published yet, so this will be the first version." **3. Choose who gets the update** Under **Who gets this update**, the default is **New chats only**. Choose **New chats and chats in progress** to include chats that are already running (see the table below). **4. Add a note and publish** Optionally write a **Note about this version (optional)**; it appears in the version history so your team knows what changed. Click **Publish changes**. You see **Changes published** together with how many open chats were updated. ### What the publish options mean | Option | What happens | | - | - | | **New chats only** (default) | Only conversations that start after publishing use the new version. Chats already in progress keep the version they started with. | | **New chats and chats in progress** | Open conversations the AI is handling on this agent's channels switch to the new version from their next AI reply. The dialog shows an estimate ("About N open chats switch to this version right away.") and suggests this for urgent fixes, like a wrong price or policy. | | **Also include chats a teammate is handling** | Extends the update to open conversations a teammate has taken over; when the agent takes these chats back, it uses this version. Available only with the option above. | Two more things happen at publish time: * Numbers you switched off move their open conversations to the default agent immediately, whatever you chose above. The dialog warns you: "The agent stops answering on these N numbers, and their open chats move to your default agent right away", and lists them. * Any other draft of this agent is archived, so only the version you just published can be rolled back to. ## Version history Click **Version history** in the agent header to open **Versions** ("Every saved and published version of this agent, and how each one did."). Each entry shows the version number, a status of **Published**, **Draft** or **Archived**, the publish or save date and time, the note you wrote (or **No note**), and five figures: | Figure | Meaning | | - | - | | **Chats** | Conversations that ran on this version | | **Handed to team** | Share of those conversations handed to a human | | **Closed** | Share of those conversations that were closed | | **Ordered** | Orders placed in those conversations, as a share of conversations | | **Tool errors** | Share of tool calls that failed | The live version is marked **Customers are on this version**; archived versions have a **Roll back** button. ## Roll back to an earlier version **1. Pick the version** In **Versions**, click **Roll back** next to the version you want. The **Roll back to vN?** dialog opens: "vN becomes the published version again. Your current version stays in the history." **2. Review what it changes** **What changes back** compares the current version with **After rollback** for every area that differs. If you had unsaved changes on the page, the dialog warns that they will be discarded. **3. Choose who gets it** Under **Who gets this version**, the default is **New chats only**. Choose **New chats and chats in progress** to switch open AI conversations from their next reply, and **Also include chats a teammate is handling** to extend that to conversations a teammate has taken over. **4. Give a reason** **Why are you rolling back?** is required (**Add a reason to roll back.**). Your team sees it in the version history. **5. Confirm** Click **Roll back to vN**. You see **Rolled back to vN**. A rollback does not reuse the old version number: Popcorn creates a new published version with the old version's contents and your reason as its note, archives the version that was live, and discards any unpublished draft. ## When publishing or rolling back fails | Message | What to do | | - | - | | **Draft is out of date with the live agent configuration. Save your changes again before publishing.** | Something changed on the agent after the draft was saved, for example a teammate saved edits or you connected Slack. Click **Save and review** again. | | **One or more WhatsApp channels in this version no longer exist. Save your changes again before publishing.** | A number in the draft was removed from the workspace. Save again. | | **One or more WhatsApp channels are connected to another agent** | Switch the number off on the other agent (and publish there) first. | | **Cannot apply this version: secret header(s) … can no longer be restored from the live agent.** | The version uses a tool whose credentials are no longer on the agent. Reconnect the tool's credentials, then try again. | | **Couldn't prepare your changes for publishing** | The edits were saved to the agent but no draft was created. Click **Save and review** again before publishing. | | **Nothing to publish yet. Save your changes first.** | There is no draft. Make a change and click **Save and review**. | ## Related * [Connect knowledge, tools, channels and notifications](/agents/connect-knowledge-tools-channels) * [Spotlight](/agents/spotlight): quality scores for the conversations each version handled. * [Troubleshooting AI agents](/agents/troubleshooting) # Troubleshooting AI agents Source: https://docs.trypopcorn.ai/agents/troubleshooting Fix an agent that does not reply, gives wrong answers, hands over too often or never, replies slowly, or ignores changes you made. Most agent problems come down to one of three things: the conversation is no longer assigned to the AI, the change you made has not been published, or the agent was never given the knowledge, tool or channel it needs. Start with the symptom below. ## The agent does not reply | Likely cause | What to do | | - | - | | The conversation is not assigned to the AI. After a handover, or after a teammate takes over, the AI stays silent in that conversation. It shows in the **Needs you** folder. | Reply as a teammate, or assign the conversation back to the AI from the Inbox. See [Working conversations](/inbox/working-conversations). | | The workspace has no credits. The agent's status reads **Stopped, out of credits**. Popcorn does not generate a reply; it hands the conversation over to your team, a team member gets an in-app notification titled **Conversation Handover - Credits Exhausted**, and the agent's Slack and email handover alerts are sent if enabled. | Top up under **Plan and billing**. See [Plans and credits](/billing/plans-and-credits). | | The agent's status reads **Stopped, plan ended**: your plan through Zid has ended. The agent does not reply whatever credits remain, and conversations are handed over to your team. | Renew the plan. See [When a Zid plan ends](/billing/plans-and-credits#when-a-zid-plan-ends). | | No agent can answer the number: it is attached to no agent and the workspace has no default agent. Popcorn hands the conversation over. | Switch the number on for an agent under its **Channels** tab, or choose a default agent from the **Agents** page with **Set as default**. | | The reply could not be generated (for example a tool call failed). Popcorn hands the conversation over rather than leaving the customer waiting. | Open the conversation in **Needs you**, reply, and check the tool that failed. | | The agent's status reads **Not published yet** or **Not on WhatsApp yet**. | A new agent answers customers only once it is published and has a WhatsApp number switched on. See [Create an agent](/agents/create-an-agent). | | In the test chat the reply did not arrive. | You see **The reply didn't come through. Send your message again.** Send the message again. | ## Replies contain wrong or outdated information * **The change is not published.** Customers, the test chat and the sandbox all use the published version. Open the agent: if a banner says it has unpublished changes, click **Save and review** and then **Publish changes**. See [Test and publish](/agents/test-and-publish). * **The agent cannot read the right knowledge base.** On the agent's **Knowledge** tab, switch on the knowledge base that holds the article, then publish. Only published articles are used; see [Connect knowledge to agents](/knowledge/connect-to-agents). * **Product details are stale.** Prices and stock come from the connected store; use **Resync products** under **Integrations** if the catalog is behind. See [Product catalog](/products/catalog). * **The conversation is old.** An open conversation keeps the version it started with unless you published with **New chats and chats in progress**. New conversations already use the new version. * **A fact is only in the old instructions.** An agent that was switched to Popcorn's rules no longer reads its instructions; their facts are in a Knowledge article named "Previous instructions of" followed by the agent's name. Keep that article published until its facts have moved. See [Popcorn's rules and Voice](/agents/popcorns-rules#agents-that-had-their-own-instructions). * **It offers an option or product you no longer sell.** The agent only sends products that are active and, with **Product quantities** on in **Settings → General**, in stock (Shopify products are never treated as out of stock). Mark the product or variant inactive in your store or under **Products**, and resync if needed. **Spotlight** tells you how often this happens: a low **Accuracy** score with the evaluator's note per conversation. See [Spotlight](/agents/spotlight). ## The agent replies in the wrong language * **On Popcorn's rules**, check **Reply language** in the agent's **Voice**: **Always Arabic** or **Always English** override the customer's language. With **Same as the customer**, a greeting, "thanks", link or product name on its own does not switch the language; a customer can ask for another language by name. See [Reply language](/agents/popcorns-rules#reply-language). * **For Arabic in the wrong style**, change **Arabic style** (**Saudi dialect**, **Gulf dialect** or **Formal Arabic**). * **On custom instructions**, the language follows the instructions: state "Reply in the customer's language" and the dialect you want. See [Writing custom instructions](/agents/writing-instructions). * The Voice applies only after you publish. Use **Preview replies** to hear it first. ## The agent hands over too often | Cause | What to do | | - | - | | Handover topics or rules are broad. Under **Hand over to your team**, each topic's **When it applies** and the text under **When to hand over** (or **Other rules**) decide when the agent passes a chat on. | Narrow them to the cases a person really must handle, or remove a topic. See [Capabilities](/agents/capabilities). | | The agent runs on Popcorn's rules and your Knowledge does not cover what customers ask. The rules offer your team rather than guess. | Add the missing facts to Knowledge; the Knowledge check suggests them from your team's answers. See [Review what your agent learned](/knowledge/knowledge-check). | | **Block spam and off-topic chats** is on and the customer keeps sending flagged messages. Flagged messages get no reply, and the third one in the same conversation triggers a handover. | Expected for spam or manipulation attempts. Turn it off only if it flags genuine customers. | | **Check replies before sending** is on with **Hand over to your team after the last retry**. Replies that miss the target score are retried, and after the last retry the conversation is handed over. | Lower **Minimum reply score (0 to 1)**, raise **Maximum retries**, or untick the handover option. See [Check replies before sending](/agents/ai-manager). | | Credits ran out. Every new customer message is handed over until you top up. | Top up under **Plan and billing**. | ## The agent never hands over * **Hand over to your team** is off. The agent can only hand over when it is switched on on the **Handoff** tab; turn it on, then publish. * No handover topic or rule describes the situation. Add a topic with **Add topic**, or the case under **When to hand over**, for example "when a customer asks for a refund". * **Hand over to your team after the last retry** under **Check replies before sending** needs **Hand over to your team** to be on as well; the tick box is disabled and reads **Turn on hand over to your team under Handoff to use this.** otherwise. ## Replies are slow * **Delay replies** waits a random number of seconds inside the range you set (1 to 60 seconds) before every reply, to look more human. Turn it off or narrow the range **Reply delay, in seconds**. * **Check replies before sending** retries a reply that scores below the target, up to **Maximum retries** times. Each retry adds time; the hint in the app warns that more retries can slow replies down. * After publishing with **New chats and chats in progress**, open conversations switch version on their next reply; nothing is re-sent, so no delay comes from the publish itself. ## Follow-ups are not sent * **Follow up when customers go quiet** goes out on WhatsApp only, in conversations the AI is handling, and only while the customer's last message is less than 24 hours old. * Popcorn sends a follow-up only when something is still open in the chat. When it decides there is nothing to follow up, the conversation shows a line such as **Follow-up skipped: the conversation had ended**. That is expected. See [Capabilities](/agents/capabilities). * No follow-up goes out after a template, after a message that failed to deliver, or when you replied from the WhatsApp Business app in the last 24 hours. ## Changes are not taking effect | What you see | Why | What to do | | - | - | - | | A banner says **N unpublished changes. Live conversations use the published version.**, or the header shows **Publish changes** | Saving creates a draft; customers use the published version. | Click **Save and review**, then **Publish changes**. | | The test chat still answers the old way after publishing | The chat resumed its previous conversation, which stays on the version it started with. | Click **Start a new conversation**, confirm **Start over**, then send a new message. | | An open customer conversation still behaves the old way | Open conversations keep their version unless you chose **New chats and chats in progress**. | Publish again with that option, or wait for new conversations. | | **Draft is out of date with the live agent configuration** when publishing | The agent changed after the draft was saved, for example a teammate saved edits or you connected Slack. | Click **Save and review** again, then publish. | | *Couldn't turn on … Your other changes were saved.* after saving | The named tools could not be attached to the agent; every other change was saved. A tool does not need to be public to be connected. | Switch the tools on again and click **Save and review**. See [Create a custom tool](/tools/create-a-tool). | | A number stays with another agent | A number can be attached to one agent at a time. | Switch it off on the other agent and publish there first. | ## The test chat or the sandbox behaves differently from live * Both use the **published** version, so they cannot show unpublished edits (see above). * On WhatsApp the agent remembers your earlier conversations from the same phone, as it does for a returning customer. Send `/reset-all` to start a test with no history. See [Start over on WhatsApp](/agents/test-and-publish#start-over-on-whatsapp). * The test chat opens the agent you are editing. The **WhatsApp sandbox** always uses the workspace's **default** agent, which may be a different agent with different instructions and knowledge. Check the **Default** badge on the **Agents** page. * The sandbox replies that the number is not linked to any organization if your phone number is not registered under **Manage sandbox numbers**, and that your organization does not have a default agent set up yet if the workspace has no default agent. * Chats from the test chat on the agent page and from the sandbox are real: they appear in the Inbox and use credits, so what you see there is what a customer would get on the same version. Only the **Try your agent** chat on **Home** and **Try it as a customer** during onboarding are free; they are kept in **Test conversations**. ## Cannot set as default, publish or save | Message | Meaning | | - | - | | **Publish to set as default** in the agent's row menu | The agent has no published version yet. Open it, save and publish, then choose **Set as default**. | | **Set another default to delete** (the disabled **Delete** item) | The default agent cannot be deleted. Set another agent as default first. | | **Agent name is required** / **Agent instructions are required** | The name must be filled in before the agent can be saved, and so must the instructions of an agent on custom instructions. On the **Create agent** page they read **Give the agent a name** and **Add instructions so the agent knows how to reply**. | | **There's already a topic with this name.** / **Say when this topic applies.** | Each handover topic needs its own name and a **When it applies**. | | **Publish your saved changes to add a suggested topic.** | **Add** under **Suggested topics** publishes the agent, so it waits until nothing is unsaved or unpublished. | | **Turn on closing resolved chats first.** | **Follow up when customers go quiet** needs **Close resolved chats**. Turn that on first. | | **Turn off follow-ups first.** | **Close resolved chats** cannot be switched off while **Follow up when customers go quiet** is on. | | **Enter more than N hours, so your last follow-up can send first.** | **Close after (hours)** must be longer than your longest follow-up wait. | | **Cannot apply this version: secret header(s) … can no longer be restored** | You are rolling back to or publishing a version that uses a tool whose credentials are gone. Reconnect the tool's credentials first. | | **Couldn't delete** followed by a tool name | The tool is still used by an agent. Turn it off on each agent's **Actions** tab, save, then delete it. | Publishing and rolling back need a role that can edit agents; setting the default agent needs a role that can manage agents. See [Team and roles](/settings/team-and-roles). ## Handover notifications do not arrive * Notifications are only sent on a handover: the agent's **Hand over to your team**, **Block spam and off-topic chats**, or an automatic handover by Popcorn. Assigning a conversation manually does not send one. * For Slack, **Slack alerts for handovers** must be on and the panel must show **Connected**; if it says **Slack isn't connected, so these alerts won't arrive yet.**, click **Connect Slack** (or **Reconnect Slack**). If you connected Slack after saving a draft, save again before publishing. * For email, **Email alerts for handovers** must be on and at least one address must be listed under **Recipients**. * Notification settings are part of the agent's version: after changing them, **Save and review** and **Publish changes**. * A handover in a free test chat (**Test conversations**) alerts nobody. See [Connect knowledge, tools, channels and notifications](/agents/connect-knowledge-tools-channels). # Writing custom instructions Source: https://docs.trypopcorn.ai/agents/writing-instructions Write instructions for an agent of type Custom instructions: Knowledge first, real tools instead of promises, clear scope, tone and language. > [!NOTE] > > This page is only for agents of type **Custom instructions**. Most agents run on **Popcorn's rules**, which have no instructions box: you set their **Voice** instead. See [Popcorn's rules and Voice](/agents/popcorns-rules). An agent of type **Custom instructions** runs on the **Instructions** you write yourself ("Custom instructions are written by your store. Popcorn's support for custom agents is limited."). Popcorn adds the rest at reply time: your knowledge bases, the capabilities you switched on, the customer's details and the date. Instructions work best when they tell the agent how to use those things, not when they try to replace them. This page explains what the agent already knows, what to write, and how **Draft with agent** writes instructions for you. ## What the agent gets besides your instructions Every reply starts from your instructions plus context Popcorn adds automatically: | Added automatically | Details | | - | - | | Agent name, current date and time | In your workspace's timezone, so "today" and "tomorrow" are correct. | | Store currency | Only if **Show currency to the agent** is switched on under **Settings → General**. | | Customer name and last delivery address | Whenever Popcorn knows them. | | Customer phone number | Only if **Share customer details with the agent** is on (**Instructions** tab, under **How it replies**). | | Knowledge base search | A search across the knowledge bases you switched on under the agent's **Knowledge** tab. | | Capability tools | Handover, guard, unsubscribe, product search and recommendation, cart and order tools, order tracking, sending media, and your custom tools, depending on what you switched on. | | Image search note | If **Recommend products** is on, the agent is told how to handle product photos a customer sends. | Two consequences: * Do not paste product prices, stock or policies into the instructions. Put them in a knowledge base or keep them in your store; the instructions should tell the agent to look them up. * Do not describe actions the agent has no tool for. An agent with **Hand over to your team** off cannot hand over, however clearly the instructions ask it to. ## What to write **Draft with agent** uses a four-part structure. Cover these four parts, in this order: > **Role and context** > > Who the agent is, for which business, for which products or services, and in what manner. One or two sentences: "You are a customer service representative for Noor Perfumes. You help customers with orders, delivery and returns in a warm, professional way." > **Primary tasks and capabilities** > > Tell the agent to answer greetings directly, to search the knowledge base before answering any question about products, services or policies (even questions that look off-topic), to use what it finds as-is, and what to say when the knowledge base has nothing: for topics outside your business, a short "I don't have details about that" plus an offer to help with what you do sell; for topics inside your business, the tool to use (for example handing over to your team). > **Communication style** > > Tone, language, length and pacing. For comparison, Popcorn's rules ask by default for replies under 50 words, one question at a time, in the customer's own language and a Saudi dialect for Arabic. If you want Arabic replies in a specific dialect, say so here. > **Limitations and boundaries** > > What the agent must not do: invent facts, add its own requirements or promises beyond the knowledge base, claim it forwarded or processed something without using a tool, collect data you do not want collected, or make commitments on the company's behalf. ### Rules that reflect how Popcorn works These lines are worth keeping in any instruction set because the rest of the product depends on them: * **"Search the knowledge base before answering questions about products, services or policies."** The agent only searches a knowledge base when it decides to; this line makes it decide to. * **"When the knowledge base says to forward or hand over, use the handover tool. Never say you have done something unless you used a tool to do it."** Without this, an agent can tell a customer "I've passed this to the team" while nothing happened. * **"Use only the facts you found. Do not add suggestions, requirements or outcomes that are not in the knowledge base."** **Check replies before sending**, if you switch it on, scores replies partly on whether they invent facts that are not in the knowledge base (see [Check replies before sending](/agents/ai-manager)). * **"Reply in the customer's language."** Unlike an agent on Popcorn's rules, a custom agent is not told which language each reply should be in: it replies in whatever language the instructions, your Knowledge and the customer lead it to, so state the rule explicitly. ### What belongs elsewhere | You want to control | Set it here instead | | - | - | | When to hand over to a human | **Handoff** tab → **Handover topics**, or **Add your own handover rules** (see [Capabilities](/agents/capabilities)) | | What follow-up messages say | **Actions** tab → **Follow up when customers go quiet** → **Add your own follow-up instructions** | | Which products to show for a question | **Products** → recommendation rules and product weights (see [Recommendation rules](/products/recommendation-rules)) | | Payment methods and delivery coverage | **Settings → Payment** and **Settings → Shipping** | ## Draft instructions with the agent The **Draft with agent** button under **Instructions** turns a plain-language description into a full instruction set in the four-part structure above. It works the same on the **Create agent** page (once you choose **Custom instructions**) and on a custom agent's **Instructions** tab. If the field is empty, the dialog opens as **Draft instructions with the agent**. If the field already has instructions, it opens as **Improve instructions with the agent** and shows them as **Current instructions**. **1. Describe the agent** Pick a starting point under **Start from an example** (**Customer service**, **Sales** or **Technical support**) and edit it under **What should your agent do?**, or write your own: your store, what customers ask about, and when to involve your team. Two or three sentences are enough. A single word such as "assistant" is rejected and nothing is written, so add more detail and try again. Click **Draft instructions**. **2. Review the draft** The draft appears under **Draft**, with the dialog titled **Review the draft**. **Edit description** goes back to your description. **3. Refine if needed** **Say what to change** asks **What should change?** ("use a warmer tone and mention our free delivery offer"); anything you do not mention stays as it is. Under **Or add a suggestion**, click one of **Make the agent's role and store clearer**, **List the main tasks step by step**, **Set a friendly, clear tone**, **Say what the agent must not do** or **Add example replies** to add it to your note, then click **Improve instructions**. **Restructure** reorganises what you have into four sections (Role and Context, Primary Tasks, Communication Style, Limitations) and is asked to keep all your information. **4. Use the result** Click **Use these instructions**. The text replaces whatever was in **Instructions**; the button appears once the text differs from what you opened the dialog with. Read it once: the generator writes placeholders such as the company name from your description, so correct anything it guessed. If it cannot write a draft you see **Couldn't write instructions. Try again.** Nothing reaches the page until you click **Use these instructions**. The text is not saved until you save the agent, and reaches customers only after you publish. ## Example A sales agent for a perfume store with a connected Shopify store, **Recommend products**, **Take orders in chat** and **Hand over to your team** switched on, and a "Policies" knowledge base: ```text theme={null} # Role and Context You are a sales assistant for Noor Perfumes. You help customers choose fragrances, place orders and get answers about delivery and returns, in a warm and confident tone. # Primary Tasks and Capabilities 1. Greetings: reply naturally, no search needed. 2. Any question about products, prices, delivery or returns: search the knowledge base first and answer only from what you find. 3. When a customer describes what they like, search the catalog and send product recommendations; do not describe products in plain text. 4. When the customer wants to buy, build the cart, collect the address and create the order with the available payment methods. 5. Complaints, damaged items, or anything the knowledge base does not cover: hand over to the team with the handover tool. Never say you have forwarded something unless you used the tool. # Communication Style - Reply in the customer's language. In Arabic, use a Saudi dialect. - Keep replies under 50 words and ask one question at a time. # Limitations and Boundaries - Do not invent prices, discounts, delivery times or stock. - Do not promise refunds; explain the return policy from the knowledge base and hand over if the customer wants to proceed. - You are an AI assistant, not an employee. ``` Why it works: * Line 2 of the tasks makes the agent search the "Policies" knowledge base before answering, which is the only way it can quote the real return policy. * Lines 3 and 4 only work because **Recommend products** and **Take orders in chat** are on; they steer the agent to the tools rather than describing products by hand. * Line 5 pairs a rule with the handover tool. If you also want a specific trigger such as "any mention of a wrong item", add it as a handover topic on the **Handoff** tab so it is attached to the tool itself, with what the agent says and the tag it sets. * Nothing in it duplicates data that lives in the store or the knowledge base. ## Check the result Instructions apply only to the published version. After editing, click **Save and review**, publish, then use the test chat and start a new conversation before you try it. To see how a published version performs over time, open [Spotlight](/agents/spotlight). ## Related * [Popcorn's rules and Voice](/agents/popcorns-rules): the other agent type, with no instructions to write. * [Create an agent](/agents/create-an-agent) * [Capabilities](/agents/capabilities): the switches that give the agent its tools. * [Connect knowledge to agents](/knowledge/connect-to-agents): checking that articles are actually used. * [Troubleshooting AI agents](/agents/troubleshooting): wrong answers, ignored instructions, changes not taking effect. # Connect ChatGPT Source: https://docs.trypopcorn.ai/ai-assistants/connect-chatgpt Add Popcorn to ChatGPT with a server URL or from ChatGPT's directory, approve access in your browser, and try your first requests. ChatGPT connects to Popcorn as a remote server. You copy one URL from Popcorn into ChatGPT, or use the **Connect in ChatGPT** button where it is offered, approve access once in your browser, and from then on you can ask ChatGPT to work in your workspace. ## Before you start * A Popcorn role with **API keys** view access, so you can open **Settings → AI assistants**. **Owner**, **Admin** and **Manager** have it. * A ChatGPT account that can add apps. Where that option lives is ChatGPT's own interface and changes over time. The **ChatGPT** card says: "If your ChatGPT account has developer mode, add this server URL in the app settings and choose OAuth." * A Popcorn account with a phone number that has finished setup. If it has not, Popcorn takes you through that first and then returns you to the approval screen. * If you belong to more than one workspace, switch to the one you want first. The connection belongs to the workspace you approve it in. ## Connect **1. Copy the server URL** In Popcorn, go to **Settings → AI assistants**. Under **Connect an assistant**, find the **ChatGPT** card (labelled **Developer setup**) and click **Copy server URL**. The value is: ``` https://api.trypopcorn.ai/chatgpt/mcp ``` If the card shows a **ChatGPT app** label and a **Connect in ChatGPT** button instead, click it: it opens Popcorn AI in ChatGPT. Select Connect, sign in to your Popcorn AI account, review the access it asks for, and skip to the last step. **2. Add the server in ChatGPT** Click **Open ChatGPT**, or open ChatGPT yourself. In the app settings add a new server, paste the URL as its address and choose OAuth. ChatGPT discovers Popcorn's sign-in requirements from the URL; there is no token or key to enter. **3. Approve access in your browser** When ChatGPT connects, Popcorn opens "Connect *assistant* to Popcorn AI" ("This will let *assistant* do the following in *workspace*."). If you are not signed in, you are sent to sign in first and then brought back. The screen shows the **App**, the **Workspace** (with your email), when the **Request expires**, the **Connection address** and **Requested access**, with one line per area such as "Inbox: Read". Check that the workspace is the one you intend, then click **Allow access**. You are returned to ChatGPT. **4. Try a request** Ask ChatGPT something read-only first, for example "Give me an overview of my Popcorn workspace" or "Which campaigns ran this month and how did they deliver?" > [!NOTE] > > The approval request is valid for 10 minutes. For ChatGPT, a request that lapsed while you were signing in or finishing account setup is renewed when you come back, for up to 24 hours after the connection started. If the page says **Authorization request was not found.**, start the connection again from ChatGPT. ## What the approval screen means * **Requested access** lists each area ChatGPT asked for, in the form "Inbox: Read", with a short description such as "Send Inbox content to customers after you confirm the action." and the access code beside it. Anything described as "after you confirm the action" means ChatGPT must show you a preview and get your go-ahead each time before Popcorn carries it out. * ChatGPT asks for every area at once. Popcorn grants only what your role allows, and the screen lists exactly that. An Agent sees fewer lines than a Manager. If your role allows none of them, approval is refused. * **Deny** cancels the request. Nothing is connected. * **Manage connected assistants** opens **Settings → AI assistants** in a new tab. That page holds setup only; to see or end connections, ask the assistant. See [Permissions and safety](/ai-assistants/permissions-and-safety#revoking-a-connection). ## What is different in ChatGPT * ChatGPT does not offer billing. It cannot read your plan, credits or invoices, buy credits or pay an invoice; use **Plan and billing** in Popcorn for those. * When ChatGPT lists conversations, it gets only the latest customer, agent or team message of each, up to 500 characters. It opens a conversation to read the whole thread. * ChatGPT has one extra tool, **Open Popcorn workspace**. It shows a card with your workspace and shortcuts for insights, customer support, campaigns, agents, knowledge and commerce, limited to what your role can use. It sends and changes nothing. * Everything else, including how confirmations work, matches the other assistants. ## First requests to try | Ask ChatGPT | What happens | | - | - | | "Summarise my open conversations and which ones need a human." | Reads the Inbox and reports back. No changes. | | "Draft a WhatsApp template announcing free shipping this weekend." | Creates a template draft you can review in **Templates**. Nothing is submitted to Meta until you confirm. | | "Prepare a campaign to customers who ordered in the last 30 days using that template." | Builds a campaign draft and shows the audience, template, timing and credit estimate. It launches only after you confirm the exact plan. | | "Which products sold most last week?" | Reads orders and products. | | "Which conversations did my AI agent hand over this week?" | Reads the Inbox. | ## Changing what ChatGPT can do The access you approved is fixed for that connection. If your role gains permissions, or you want ChatGPT to start with a wider set, remove and re-add the server in ChatGPT so it requests access again, then approve the new list. If you want less access, ask ChatGPT to revoke its own connection and reconnect, or have an Owner or Admin adjust your role; see [Permissions and safety](/ai-assistants/permissions-and-safety#revoking-a-connection). ## Troubleshooting | Symptom | What to do | | - | - | | ChatGPT cannot reach the server | Check the URL is exactly `https://api.trypopcorn.ai/chatgpt/mcp`, with no trailing characters. The ChatGPT address differs from the one Claude Code and Codex use. | | **Authorization request was not found.** | The 10-minute window passed, or the request was already approved or denied. Reconnect from ChatGPT and approve promptly. | | **Authorization request expired.** on a request you just started | The page uses this text for several refusals: you are signed in to Popcorn as a different user than the one who started the connection, or your role allows none of the access ChatGPT asked for. Sign in as the right user or ask an Owner or Admin about your role, then reconnect from ChatGPT. | | **Unable to complete authorization.** after you click **Allow access** | Popcorn could not finish the approval, for example because it lapsed or was already used. Go back to ChatGPT and start the connection again. | | **This request has been refreshed. Review the requested access and choose again to continue.** | The approval lapsed while the page was open. Check the list and click **Allow access** again. | | ChatGPT says it lacks permission for an action | Your role does not allow it, so the approval screen did not list it. Check your role under **Settings → Roles and permissions**, ask an Owner or Admin to change it if needed, then reconnect. | | ChatGPT says too many requests | Popcorn limits how fast each assistant can call it. Wait for the time it reports and try again. | | ChatGPT stopped working after a team change | If your role was changed or you were removed from the workspace, access ends with the next request. | ## Related * [What you can do](/ai-assistants/what-you-can-do) * [Permissions and safety](/ai-assistants/permissions-and-safety) * [Connect Claude](/ai-assistants/connect-claude) and [Connect Codex](/ai-assistants/connect-codex) # Connect Claude Source: https://docs.trypopcorn.ai/ai-assistants/connect-claude Add Popcorn to Claude on the web, desktop and mobile as a custom connector, or to Claude Code with one command, then approve access and try it. Claude connects to Popcorn in two ways. **Claude** on the web, desktop and mobile uses a custom connector (or a button, where Popcorn's directory listing is available). **Claude Code** uses one command. Either way you approve access once in your browser, and from then on Claude can work in your workspace. ## Before you start * A Popcorn role with **API keys** view access, so you can open **Settings → AI assistants**. **Owner**, **Admin** and **Manager** have it. * For the connector: a Claude plan that can add custom connectors. Where that option lives is Claude's own interface; the **Claude** card says to use **Customize**, **Connectors**, **Add custom connector**. For Claude Code: Claude Code installed on your computer. * A Popcorn account with a phone number that has finished setup, for the connector. If it has not, Popcorn takes you through that first and then returns you to the approval screen. * If you belong to more than one workspace, switch to the one you want first. The connection belongs to the workspace you approve it in. ## Connect **Claude (web, desktop, mobile)** **1. Copy the connector URL** In Popcorn, go to **Settings → AI assistants**. Under **Connect an assistant**, find the **Claude** card (labelled **Custom connector**) and click **Copy connector URL**. The value is: ``` https://api.trypopcorn.ai/claude/mcp ``` If the card shows a **Claude connector** label and a **Connect in Claude** button instead, click it: it opens Popcorn AI in Claude's connectors directory. Select Connect, sign in to your Popcorn AI account, review the access it asks for, and skip to the last step. **2. Add it in Claude** Click **Open Claude** (it opens Claude's connectors page), or open Claude yourself. Under **Customize**, **Connectors**, choose **Add custom connector**, paste the URL and continue. There is no token or key to enter. **3. Approve access in your browser** Popcorn opens "Connect *assistant* to Popcorn AI" ("This will let *assistant* do the following in *workspace*."). If you are not signed in, you are sent to sign in first and then brought back. The screen shows the **App**, the **Workspace** (with your email), when the **Request expires**, the **Connection address** and **Requested access**. Check that the workspace is the one you intend, then click **Allow access**. **4. Try a request** Ask Claude something read-only first, for example "Give me an overview of my Popcorn workspace" or "List my WhatsApp templates and their approval status." **Claude Code** **1. Copy the command** In Popcorn, go to **Settings → AI assistants**. Under **Connect an assistant**, find the **Claude Code** card (labelled **Command line**) and click **Copy command**. The command is: ``` claude mcp add --transport http popcorn https://api.trypopcorn.ai/mcp ``` **2. Run it** Paste the command into your terminal and run it. This adds Popcorn to Claude Code as a server named `popcorn`. No token or key is involved. **3. Approve access on first use** Claude asks you to sign in the first time it uses Popcorn, or when you run `/mcp` in Claude Code and choose **Authenticate**. Popcorn then opens the approval screen in your browser, with the same **App**, **Workspace**, **Request expires**, **Connection address** and **Requested access** as above. Click **Allow access**, then return to Claude Code. **4. Try a request** Ask Claude something read-only first, for example "Show me conversations waiting on a human reply." > [!NOTE] > > The approval request is valid for 10 minutes. If the page says **Authorization request was not found.**, ask Claude to use Popcorn again to get a fresh approval screen. For the connector, a request that lapsed while you were signing in or finishing account setup is renewed when you come back, for up to 24 hours after the connection started. ## What the approval screen means * **Requested access** lists each area Claude asked for, in the form "Campaigns: Read", with a short description and the access code beside it. A description that says "after you confirm the action" means Claude must show you a preview and get your go-ahead each time before Popcorn carries it out. * The connector asks for every area at once, and Popcorn grants only what your role allows. If your role allows none of them, approval is refused. Claude Code chooses what it asks for. If it asks for more than your role can grant, the page shows **Authorization request expired.** instead of the approval screen. If Claude does not ask for specific areas, Popcorn grants read-only access to every area your role can view. * **Deny** cancels the request. Nothing is connected. See [Permissions and safety](/ai-assistants/permissions-and-safety) for the full model. ## What is different between the two | | Claude connector | Claude Code | | - | - | - | | Address | `https://api.trypopcorn.ai/claude/mcp` | `https://api.trypopcorn.ai/mcp` | | Billing | Not offered: no plan, credits or invoice access | Offered, with confirmation | | Role | Granted the subset your role allows | Denied if it asks for more than your role allows | ## First requests to try | Ask Claude | What happens | | - | - | | "Show me conversations waiting on a human reply and suggest who should take each." | Reads the Inbox and reports back. Assignments happen only if you ask for them. | | "Draft a template for our Ramadan sale and tell me what Meta might reject." | Creates a template draft you can review in **Templates**. Nothing is submitted until you confirm. | | "Compare my agent's draft version with the live one." | Reads both versions and shows the differences. Publishing needs your confirmation. | | "Which knowledge articles have not been updated in three months?" | Reads Knowledge. | | "Check whether my Shopify connection is healthy." | Reads integration status. | ## Built-in workflows Popcorn publishes four ready-made workflows that Claude can list and run: **Safely prepare and launch a campaign**, **Triage the Popcorn inbox**, **Review and publish an agent version**, and **Connect a commerce or messaging integration**. Each walks Claude through reading first, showing you a preview, and waiting for your confirmation. See [What you can do](/ai-assistants/what-you-can-do#built-in-workflows). ## Troubleshooting | Symptom | What to do | | - | - | | The command fails | Check it was pasted exactly as copied, including `--transport http`. | | Claude cannot reach the connector | Check the URL is exactly `https://api.trypopcorn.ai/claude/mcp`. The connector address differs from the one Claude Code uses. | | **Authorization request was not found.** | The 10-minute window passed, or the request was already approved or denied. Ask Claude to use Popcorn again and approve promptly. | | **Authorization request expired.** on a request you just started | The page uses this text for several refusals: you are signed in to Popcorn as a different user than the one who started the connection, or your role cannot grant the access Claude asked for. Sign in as the right user or ask an Owner or Admin about your role, then try again. | | **Unable to complete authorization.** after you click **Allow access** | Popcorn could not finish the approval, for example because it lapsed or was already used. Start the connection again from Claude. | | Claude says it lacks permission for an action | Your role does not allow it. Check your role under **Settings → Roles and permissions**, then reconnect so the new access is requested. | | Claude says too many requests | Popcorn limits how fast each assistant can call it. Wait for the time it reports and try again. | | Claude stopped working after a team change | If your role was changed or you were removed from the workspace, access ends with the next request. | ## Related * [What you can do](/ai-assistants/what-you-can-do) * [Permissions and safety](/ai-assistants/permissions-and-safety) * [Connect ChatGPT](/ai-assistants/connect-chatgpt) and [Connect Codex](/ai-assistants/connect-codex) # Connect Codex Source: https://docs.trypopcorn.ai/ai-assistants/connect-codex Add Popcorn to Codex CLI with two commands, sign in through your browser, and try your first requests. Codex connects to Popcorn through Codex CLI. You run two commands that Popcorn gives you: the first registers Popcorn, the second starts the sign-in that opens Popcorn's approval screen in your browser. ## Before you start * A Popcorn role with **API keys** view access, so you can open **Settings → AI assistants**. **Owner**, **Admin** and **Manager** have it. * Codex CLI installed on your computer. * If you belong to more than one workspace, switch to the one you want first. The connection belongs to the workspace you approve it in. ## Connect **1. Copy the commands** In Popcorn, go to **Settings → AI assistants**. Under **Connect an assistant**, find the **Codex** card (labelled **Codex CLI**) and click **Copy commands**. The commands are: ``` codex mcp add popcorn --url https://api.trypopcorn.ai/mcp codex mcp login popcorn ``` **2. Register Popcorn** Run the first command. It adds Popcorn to Codex as a server named `popcorn`. **3. Sign in and approve** Run the second command. Codex opens Popcorn's approval screen in your browser. If you are not signed in, you are sent to sign in first and then brought back. The screen shows the **App** asking, the **Workspace** it will reach (with your email), when the **Request expires**, the **Connection address**, and **Requested access** with one line per area, such as "Campaigns: Read". Check that the workspace is the one you intend, then click **Allow access**. Return to your terminal. **4. Try a request** Ask Codex something read-only first, for example "Give me an overview of my Popcorn workspace" or "Show my last five orders." > [!NOTE] > > The approval request is valid for 10 minutes. If the page says **Authorization request was not found.**, run `codex mcp login popcorn` again. ## What the approval screen means * **Requested access** lists each area Codex asked for, in the form "Inbox: Send", with a short description and the access code beside it. A description that says "after you confirm the action" means Codex must show you a preview and get your go-ahead each time before Popcorn carries it out. * If Codex does not ask for specific areas, Popcorn grants read-only access to every area your role can view. * Access never exceeds your own Popcorn role. If Codex asks for more than your role can grant, the page shows **Authorization request expired.** instead of the approval screen. * **Deny** cancels the request. Nothing is connected. * Codex uses the main address, so billing is available (with confirmation), unlike ChatGPT and the Claude connector. See [Permissions and safety](/ai-assistants/permissions-and-safety) for the full model. ## First requests to try | Ask Codex | What happens | | - | - | | "Which of my campaigns had the most failed deliveries this month, and why?" | Reads campaign delivery results and summarises the failure reasons. | | "Import these customers" followed by a list of names and phone numbers | Prepares an import and shows which rows would be created or updated. It runs only after you confirm. | | "Add a product called X at 120 SAR with this description." | Prepares the product and shows the preview. It is created only after you confirm. | | "Turn off the recommendation rule for the summer collection." | Updates the rule. | | "List my team and any pending invites." | Reads the team. | ## Built-in workflows Popcorn publishes four ready-made workflows that Codex can list and run: **Safely prepare and launch a campaign**, **Triage the Popcorn inbox**, **Review and publish an agent version**, and **Connect a commerce or messaging integration**. Each walks Codex through reading first, showing you a preview, and waiting for your confirmation. See [What you can do](/ai-assistants/what-you-can-do#built-in-workflows). ## Troubleshooting | Symptom | What to do | | - | - | | The first command fails | Check the URL is exactly `https://api.trypopcorn.ai/mcp`. | | **Authorization request was not found.** | The 10-minute window passed, or the request was already approved or denied. Run `codex mcp login popcorn` again and approve promptly. | | **Authorization request expired.** on a request you just started | The page uses this text for several refusals: you are signed in to Popcorn as a different user than the one who started the connection, or your role cannot grant the access Codex asked for. Sign in as the right user or ask an Owner or Admin about your role, then run the login command again. | | **Unable to complete authorization.** after you click **Allow access** | Popcorn could not finish the approval, for example because it lapsed or was already used. Run the login command again. | | Codex says it lacks permission for an action | Your role does not allow it, or the connection was approved before that area existed. Check your role under **Settings → Roles and permissions**, then run the login command again so the new access is requested. | | Codex says too many requests | Popcorn limits how fast each assistant can call it. Wait for the time it reports and try again. | | Codex stopped working after a team change | If your role was changed or you were removed from the workspace, access ends with the next request. | ## Related * [What you can do](/ai-assistants/what-you-can-do) * [Permissions and safety](/ai-assistants/permissions-and-safety) * [Connect ChatGPT](/ai-assistants/connect-chatgpt) and [Connect Claude](/ai-assistants/connect-claude) # AI assistants overview Source: https://docs.trypopcorn.ai/ai-assistants/overview Connect ChatGPT, Claude or Codex to your Popcorn workspace so it can run campaigns, work the inbox and answer questions about your store. AI assistants lets the assistant you already use, ChatGPT, Claude or Codex, work inside your Popcorn workspace with you. Once connected, you can ask it in plain language to draft a template, launch a campaign, go through open conversations, look up a customer or order, or pull last week's numbers, and it does the work through Popcorn on your behalf. Setup is one copied value, or one button, plus an approval screen. There is no API key to create, paste or keep safe. ## How it works **1. Pick an assistant** Go to **Settings → AI assistants** ("Popcorn for AI assistants") and find your assistant under **Connect an assistant**. See [Connect ChatGPT](/ai-assistants/connect-chatgpt), [Connect Claude](/ai-assistants/connect-claude) or [Connect Codex](/ai-assistants/connect-codex). **2. Sign in and approve** Popcorn opens a page titled "Connect *assistant* to Popcorn AI" in your browser. It shows the **App** asking, the **Workspace** it will reach, when the **Request expires**, the **Connection address**, and a **Requested access** list. Click **Allow access** or **Deny**. **3. Ask and take action** Ask the assistant for what you need. It reads and changes only what your own Popcorn role allows, and you confirm every send, launch and deletion. ## Ways to connect | Assistant | Card on **Connect an assistant** | What you copy | Connection address | | - | - | - | - | | ChatGPT | **ChatGPT** | **Copy server URL** | `https://api.trypopcorn.ai/chatgpt/mcp` | | Claude on the web, desktop and mobile | **Claude** | **Copy connector URL** | `https://api.trypopcorn.ai/claude/mcp` | | Claude Code | **Claude Code** | **Copy command** | `https://api.trypopcorn.ai/mcp` | | Codex | **Codex** | **Copy commands** | `https://api.trypopcorn.ai/mcp` | | Any other client with OAuth sign-in | **Other MCP clients** | **Copy URL** | `https://api.trypopcorn.ai/mcp` | The **ChatGPT** and **Claude** cards show one of two setups. Where Popcorn's listing in the assistant's directory is available, the card has a **Connect in ChatGPT** or **Connect in Claude** button instead of a URL: click it, select Connect there, sign in to Popcorn AI and review the access it asks for. Otherwise the card shows the URL to add by hand. ## What your assistant can reach | Area | What it can do | | - | - | | Campaigns and templates | Draft, clone and update WhatsApp templates; submit them for review; build audiences; launch, pause, resume, stop and delete campaigns; create automated campaigns; read delivery results | | Inbox | List and read conversations, timelines and notes; assign, close, reopen, tag and snooze; take over a conversation or hand it back to an AI agent; send messages, media and products after your confirmation | | Customers | Search and read profiles; update details; import customers; delete customers after your confirmation | | Products and orders | Read the catalog and orders; create, update and delete products; manage recommendation rules, custom options, shipping options and payment preferences; sync the catalog from your store | | Analytics | Workspace overview, reports, and performance by agent | | AI agents and tools | Create and edit agents, save draft versions, publish or roll back after your confirmation, route WhatsApp numbers, manage custom tools | | Knowledge | Create, edit, preview, publish and delete articles and folders; restore an earlier version; see which articles the agent used | | Integrations and channels | Check store, Meta and WhatsApp connection health; start a store, Meta or Slack connection that you finish in the browser; update your WhatsApp profile; sync the Meta catalog | | Team | See members and pending invites; invite, remove and change roles after your confirmation | | Billing | Read your plan, credits and invoices; buy credit packages, pay an open invoice and change billing preferences with your saved payment method, after your confirmation. Offered only through Claude Code, Codex and other clients that use the main address; ChatGPT and the Claude connector leave billing out | | Workspace settings | General settings, your profile and notification preferences, Website chat and WhatsApp button settings, the message-status webhook, sandbox test numbers | | Workspace setup | Analyze your public website, then create the first agent and knowledge base in an empty workspace after your confirmation | For example requests in each area, see [What you can do](/ai-assistants/what-you-can-do). > [!NOTE] > > The **What assistants can do** panel on **Settings → AI assistants** is a summary of six areas: **Knowledge base**, **Campaigns and templates**, **Customers and conversations**, **Performance and workspace**, **Products and orders**, and **Agents and tools**. The table above is the full set. ## What keeps this safe * **It asks before anything it cannot undo.** Sending messages, launching campaigns, publishing, importing, deleting, changing billing and similar actions come back as a preview first. The assistant must show you that preview and get your go-ahead before Popcorn carries it out. The go-ahead is valid for 10 minutes and for that exact plan only. * **Access is bound to you.** Every connection is tied to your user, the workspace you approved it in, and the assistant you approved. Popcorn re-checks your user and role on every request, so the assistant can never do more than your role allows. If your role is reduced or you are removed from the workspace, its access stops with the next request. * **You see what it gets.** The approval screen lists each area of access. ChatGPT and the Claude connector ask for everything and receive only what your role allows; Claude Code, Codex and other clients choose what they ask for, and one that asks for nothing specific receives read-only access. * **Customer content is data, not instructions.** Popcorn tells the assistant that customer messages, articles, imported rows and store content are information to work with, never commands to follow, and enforces permissions and confirmations regardless. Details are in [Permissions and safety](/ai-assistants/permissions-and-safety). ## Before you start * You need a Popcorn role with **API keys** view access to open **Settings → AI assistants**. **Owner**, **Admin** and **Manager** have it; **Agent** and **Viewer** do not. See [Team and roles](/settings/team-and-roles). * What the assistant can do afterwards depends on the rest of your role. A role without **Campaigns** full access, for example, cannot launch campaigns through an assistant either. * If you belong to more than one workspace, switch to the one you want before you approve. The connection belongs to the workspace you approve it in. * The assistant must support remote connections with sign-in. ## What it costs Connecting an assistant and asking it questions does not use Popcorn credits. Actions it carries out cost what they cost in the app: a campaign it launches uses campaign credits, and a credit package it buys on your instruction is charged to your saved payment method after you confirm. One read-style request is an exception: generating an AI summary of a conversation can use AI credits, so the assistant asks you before running it. See [Credit usage](/billing/credit-usage). ## Pick your assistant > **[ChatGPT](/ai-assistants/connect-chatgpt)** > > Add Popcorn as a server URL, or connect from ChatGPT's directory. > **[Claude](/ai-assistants/connect-claude)** > > A custom connector for the web, desktop and mobile, or one command in Claude Code. > **[Codex](/ai-assistants/connect-codex)** > > Two commands in Codex CLI. ## Related * [What you can do](/ai-assistants/what-you-can-do) * [Permissions and safety](/ai-assistants/permissions-and-safety) * [API reference](/api-reference/introduction) if you need to build your own integration rather than use an assistant # Permissions and safety Source: https://docs.trypopcorn.ai/ai-assistants/permissions-and-safety How an assistant's access to your workspace is granted, limited by your role, confirmed before risky actions, and revoked. A connected assistant acts as you, inside the limits of your Popcorn role, and only after you have approved it. This page explains what the approval screen grants, what the assistant must confirm with you, how long access lasts, and how to end it. ## What you approve When an assistant connects, Popcorn opens a page titled "Connect *assistant* to Popcorn AI" with the line "This will let *assistant* do the following in *workspace*." You must be signed in to Popcorn; if you are not, you are sent to sign in and then brought back. The screen shows: | Field | Meaning | | - | - | | **App** | The name the assistant registered with, with a **Website** link when it provides one. | | **Workspace** | The workspace the assistant will reach, with the email you are signed in as. It is the workspace you are in when you approve. | | **Request expires** | When this approval request lapses. Requests are valid for 10 minutes. | | **Connection address** | The Popcorn address the assistant is connecting to. | | **Requested access** | One line per area the assistant asked for, with a short description of what it allows. | Click **Allow access** to connect or **Deny** to cancel. The footer says "You can disconnect *assistant* at any time." and links to **Manage connected assistants**, which opens **Settings → AI assistants** in a new tab. That page holds setup only; see [Revoking a connection](#revoking-a-connection). ### Access levels Each line under **Requested access** is an area plus a level, in the form "Inbox: Send", with the short code the assistant asked for (for example `inbox:send`) shown next to it. | Level on screen | Code | What the screen says it allows | | - | - | - | | **Read** | `read` | Read that area's data allowed by your current Popcorn AI role. | | **Create and edit** | `write` | Create or update that area's data allowed by your current Popcorn AI role. | | **Delete** | `delete` | Delete that area's data after you confirm the action. | | **Publish** | `publish` | Publish that area's changes after you confirm the action. | | **Launch and control** | `launch` | Launch or control that area's delivery after you confirm the action. | | **Send** | `send` | Send that area's content to customers after you confirm the action. | | **Run** | `execute` | Run that area's operations allowed by your current Popcorn AI role. | The areas are **Workspace**, **Analytics**, **Inbox**, **Saved replies**, **Tags**, **Customers**, **Products**, **Orders**, **Templates**, **Campaigns**, **AI agents**, **Knowledge base**, **Custom tools**, **Integrations**, **Billing**, **Settings**, **API keys** and **Team**. ### Assistants that ask for nothing specific If the assistant does not request particular areas, Popcorn grants read-only access to every area your role can view. The assistant can answer questions and produce reports but cannot change anything. Reconnect if you later want it to make changes and it supports asking for that access. ## Your role is the ceiling An assistant can never do more than you can. Each area of access maps to a permission on your Popcorn role, the same ones shown under **Settings → Roles and permissions** (**Full access** includes every other action for that area): | Assistant access | Needs this permission on your role | | - | - | | Inbox read / write / send | **Inbox** → View / Edit / Create | | Customers, Products, Orders read / write / delete | That area → View / Edit / Delete | | Campaigns read / write / launch / delete | **Campaigns** → View / Edit / Full access / Delete | | Templates read / write / publish / delete | Template permissions: View / Edit / Full access / Delete. Templates are not a separate row in **Roles and permissions**; the built-in roles set them (Owner, Admin and Manager have full access, Agent can view, create and edit, Viewer can view). | | AI agents read / write / publish | **Agents** → View / Edit / Full access | | Custom tools read / write / publish | **Agents** → View / Edit / Edit | | Knowledge base read / write / publish / delete | **Knowledge base** → View / Edit / Full access / Delete | | Analytics read | **Analytics** → View | | Integrations read / write | **Integrations** → View / Full access | | Team read / write | **Team** → View / Full access | | Billing read / write | **Billing** → View / Full access | | Settings read / write | **Settings** → View / Edit | | Saved replies (macros) and Tags read / write / delete | **Macros** or **Tags** → View / Edit / Delete | | API keys read / delete | **API keys** → View / Delete | Three consequences: * **What happens when the request exceeds your role depends on the assistant.** ChatGPT and the Claude connector ask for every area and receive only what your role allows; the screen lists exactly that, and approval is refused only when your role allows none of it. Claude Code, Codex and other clients choose what they ask for. If they ask for more than your role can grant, the page shows **Authorization request expired.** instead of the approval screen. Ask an Owner or Admin to change your role, or connect as a user who has the access. * **Changes to your role apply on the next request.** Popcorn re-checks your user and role every time the assistant calls it. If your role is reduced, the assistant loses that access immediately. If you are removed from the workspace or the workspace is suspended, the connection stops working. * **Billing depends on the connection.** ChatGPT and the Claude connector never receive billing access, whatever your role. See [Differences between connections](#differences-between-connections). ## Bound to you, your workspace, and that assistant Every approval creates a connection tied to three things: your user, the workspace you approved it in, and the specific assistant that asked. It cannot be transferred to another person, another workspace, or another assistant. A connection works only at the address it was approved for: one made for the ChatGPT address is rejected at the Claude and main addresses, and the other way round. * **Workspace.** If you belong to more than one workspace, approve while you are in the one you want. The connection keeps working in that workspace as long as you are a member of it, even if you later switch your dashboard to another one, and it acts with your role there. If the workspace you are in changes while the approval page is open, Popcorn refuses the approval and the page reloads to show the new workspace, so you decide again. * **User.** If the approval link is opened while signed in as a different Popcorn user than the one who started the connection, the page shows **Authorization request expired.** and nothing is approved. ## Confirmation before anything irreversible Actions that reach a customer, publish something, delete data, move money, or change what is live are split into two steps. The assistant first asks Popcorn for a plan, which returns an exact preview: recipients, template, timing, amount, what will be created or deleted. The assistant must show you that preview and wait for your go-ahead. Only then can it ask Popcorn to carry the plan out. What Popcorn enforces on its side: * A go-ahead is valid for 10 minutes and for one execution only. * It is bound to the exact plan. If the assistant changes anything, or if the underlying data changed in between (a template was edited, a conversation received new messages, a price changed), Popcorn refuses and the assistant must prepare a new plan for you to review. * Retrying a completed action with the same details does not run it twice. Actions that always need confirmation include: sending any Inbox message, media, product, or template chat; handing a conversation to the AI agent with an immediate reply; launching, pausing, resuming, stopping, activating, deactivating, or deleting a campaign; creating an automated campaign; submitting or deleting a template; creating, updating, importing, or deleting products, and syncing your catalog; importing or deleting customers; publishing or rolling back an agent version; changing which agent handles a WhatsApp number or is the main agent; deleting an agent or one of its capabilities; publishing, replacing, or deleting a custom tool, and installing one from the Tools showcase; publishing or deleting Knowledge articles and folders; deleting macros, tags, recommendation rules, product custom options, shipping options, or sandbox test numbers; updating your WhatsApp profile, the message-status webhook, or Shopify integration settings; reading your Shopify store's checkout attributes; syncing the Meta catalog; disconnecting a WhatsApp number; setting up a workspace from a website analysis; inviting, re-inviting, or removing team members, cancelling invites, and changing roles; buying credits, paying an invoice, changing billing preferences, or opening a billing session; generating an AI conversation summary (it can use credits); and revoking an assistant connection or API key. Reads and low-impact edits (updating a customer's name, tagging or closing a conversation, saving a draft, creating a macro, adding a shipping option) do not need confirmation. ### Messages outside the 24-hour window An assistant cannot send a free-form text, media or product message when WhatsApp's 24-hour customer-service window for that conversation is closed. Popcorn refuses it with "The 24-hour customer-service window is closed; use popcorn\_plan\_start\_inbox\_template\_chat to send an approved template", and nothing is sent. The assistant can instead prepare an approved template chat, which you confirm like any other send. Sends are also refused when the WhatsApp number itself cannot send; see [Channels troubleshooting](/channels/troubleshooting). ## Things you must do in the browser Some steps never go through the assistant, because they involve your credentials or consent with another company: * Signing in to Shopify, Salla, or Zid and approving the store connection. * Meta login and consent for WhatsApp or a product catalog. The assistant gives you a link that opens the **WhatsApp** page under **Integrations** ready to connect (or **Integrations** itself for a catalog); you click **Connect WhatsApp** and complete Meta's steps yourself. * Slack authorization for an agent. * Entering or changing a payment card, changing your plan, and any payment that your bank asks you to authenticate. Where billing is offered, the assistant can start a billing session (after your confirmation) and give you the link. The assistant should hand you the link, wait, and then check the connection status. It cannot approve these steps for you, and you should never paste provider codes or passwords into a chat. ## How long access lasts * The approval request itself expires after 10 minutes. For ChatGPT and the Claude connector, a request that lapsed while you were signing in or finishing account setup is renewed when you come back, for up to 24 hours after the connection started; you then decide on the refreshed screen ("This request has been refreshed. Review the requested access and choose again to continue."). * Once approved, the assistant's session is renewed automatically while you keep using it. A connection that goes unused for 30 days expires, and the assistant asks you to approve again. * Reconnecting after a permission change is expected. Connections approved before an area existed do not include it; to add it, connect again so the assistant requests the new access. Importing customers or products, for example, needs read access to those areas as well as write access. ## Differences between connections | | ChatGPT | Claude connector | Claude Code, Codex, other clients | | - | - | - | - | | Address | `.../chatgpt/mcp` | `.../claude/mcp` | `.../mcp` | | Access granted | What your role allows, from every area | What your role allows, from every area | What the client asks for, or read-only if it asks for nothing specific | | Billing tools and access | Not offered | Not offered | Offered, with confirmation | | Existing API keys | Not accepted | Not accepted | Accepted for reading only | | Extra | **Open Popcorn workspace** card | None | None | ## Revoking a connection **Settings → AI assistants** shows setup instructions only; it does not list or revoke connections. To end an assistant's access: * **Ask the assistant.** Say "List my connected assistants" and then "Revoke the connection for X". Revoking is itself a confirmed action, so the assistant shows you which connection it is about to remove and waits for your go-ahead. This works from any connected assistant, including the one you are revoking. * **Change the role or remove the user.** An Owner or Admin can reduce your role or remove you from the workspace under **Settings → Team members**; every connection you approved stops with the next request. * **Removing Popcorn inside the assistant's own settings** stops that assistant from using the connection. Unless the assistant tells Popcorn it is disconnecting, the approval on Popcorn's side remains until it is revoked or expires after 30 days unused. ## Rate limits Popcorn limits how quickly each assistant can call it, per action type, per minute: | Action type | Per minute | | - | - | | Reads | 120 | | Edits and drafts | 30 | | Sends, launches, and publishes | 10 | | Deletions | 5 | Generating agent instructions has its own, tighter limits because it calls an AI model: 3 per minute per assistant, 5 per minute per user, 20 per minute per workspace, and a daily allowance of 25 per user and 250 per workspace (the day resets at midnight UTC). When a limit is hit, the assistant receives **Too many MCP requests** with the number of seconds to wait. Nothing is lost; it can continue after the window. Edits, sends, deletions, and instruction generation also pause if Popcorn's safety limiter is temporarily unavailable (the assistant is told to retry in 60 seconds), so that nothing runs unchecked. Reads keep working. ## API keys An existing Popcorn API key (from **Settings → API keys and webhooks**) can also be used by an assistant, but only on the main address and only for reading. Anything that creates, changes, sends, or deletes requires an approved assistant connection tied to a user. See the [API reference](/api-reference/introduction) for what keys are for. ## Privacy The [privacy policy](https://trypopcorn.ai/privacy-policy/) has a section on Popcorn in ChatGPT: what Popcorn receives from the assistant and how long it keeps connection records, for example 10 minutes for confirmation previews and 7 days for temporary uploads. It also states that Popcorn does not use your content, including what passes through the ChatGPT app, to train or fine-tune AI models. Disconnecting an assistant does not delete the records it created in your workspace or data already sent on to others, such as messages to customers. ## Related * [Overview](/ai-assistants/overview) * [What you can do](/ai-assistants/what-you-can-do) * [Team and roles](/settings/team-and-roles) # What you can do Source: https://docs.trypopcorn.ai/ai-assistants/what-you-can-do Example requests for a connected assistant in every area of Popcorn, the built-in workflows it can run, and what it cannot do. Once an assistant is connected, you ask for things in plain language and it works through Popcorn. This page shows what to ask for in each area, which requests will stop for your confirmation, and where the assistant deliberately cannot go. Everything depends on the access you approved and your Popcorn role; see [Permissions and safety](/ai-assistants/permissions-and-safety). ## Campaigns and templates | Ask | Needs your confirmation? | | - | - | | "List my templates and which ones Meta has approved." | No | | "Draft a template for a 20% weekend sale with a Shop now button." | No, it saves a draft | | "Clone the Eid template and change the offer to free delivery." | No, it saves a draft | | "Submit that template to Meta for review." | Yes | | "Preview how many customers ordered in the last 60 days and live in Riyadh." | No | | "Create a campaign to that audience with the approved template, scheduled for Thursday 6pm." | No for the draft; **yes** to launch | | "Pause the running campaign." / "Resume it." / "Stop it." | Yes | | "Why did deliveries fail on yesterday's campaign?" | No | | "Set up an abandoned-cart campaign for my Shopify store." | Yes | | "Delete the old draft campaigns." | Yes | The launch preview shows the audience, template, timing, and delivery details so you can check it before agreeing, and warns when some of the audience unsubscribed from your campaigns. Credits are charged as they are for any campaign. If the workspace can't cover the campaign's credits, the launch is refused, nothing is sent, and the assistant is told how many credits it needs; see [Send a campaign](/campaigns/send-a-campaign) and [Credit usage](/billing/credit-usage). ## Inbox | Ask | Needs your confirmation? | | - | - | | "Which conversations are waiting on a human?" | No | | "Show me the full conversation with +9665... and any internal notes." | No | | "Assign this conversation to Sara and add a note that the customer wants a refund." | No | | "Close all conversations that have been idle for a week." | No | | "Tag this conversation as 'refund'." | No | | "Take over this conversation so the agent stops replying." | No | | "Reply to this customer: your order ships tomorrow." | Yes | | "Send them the product photo." / "Send them these two products." | Yes | | "Start a new WhatsApp chat with this customer using the order-update template." | Yes | | "Hand this conversation back to the AI agent and let it reply now." | Yes | | "Create a macro for our return policy." | No | The assistant sees customer messages as information to work with, not instructions to follow. It should never send a message without first showing you the exact recipient, channel, and text. Free-form text, media and product messages are refused when WhatsApp's 24-hour customer-service window for that conversation is closed, and nothing is sent; the assistant can prepare an approved template chat instead, which you confirm like any other send. Sends are also refused when the WhatsApp number itself cannot send. See [Working conversations](/inbox/working-conversations), [Tags and macros](/inbox/tags-and-macros) and [Channels troubleshooting](/channels/troubleshooting). ## Customers | Ask | Needs your confirmation? | | - | - | | "Find customers who have not ordered since March." | No | | "Update Ahmed's city to Jeddah." | No | | "Import these customers: \[names and numbers]." | Yes, after a preview of creates versus updates | | "Delete these 12 test customers." | Yes | | "Delete all my customers." / "Delete these 3,000 customers." | Yes, runs in the background | Direct deletion covers up to 100 selected customers at a time. Larger deletions (up to 5,000 selected customers, or every customer in the workspace) run as a background job the assistant can follow and cancel; the set of customers is fixed when the preview is prepared, so customers added afterwards are never included. Either way, customers who have conversations are skipped unless you explicitly ask to include them. Imports never change a customer's consent status unless you say so. See [Customers](/customers/overview). ## Products, orders, shipping, and payment | Ask | Needs your confirmation? | | - | - | | "Which products are out of stock?" | No | | "Show order #1042." | No | | "Add a product called X at 120 SAR." / "Change the price of Y to 99 SAR." | Yes | | "Import these products from this list." | Yes | | "Sync my catalog from Salla." | Yes | | "Recommend the matching bag whenever someone asks about the black shoes." | No | | "Turn off the summer recommendation rule." | No | | "Add a gift-wrap option to all candles." | No | | "Delete these discontinued products." | Yes | | "Add express delivery to Riyadh for 25 SAR." | No | | "Enable cash on delivery." | No | See [Product catalog](/products/catalog), [Recommendation rules](/products/recommendation-rules), [Orders](/orders/overview), and [Shipping and payment](/settings/shipping-and-payment). ## Analytics and performance | Ask | Needs your confirmation? | | - | - | | "Give me an overview of the workspace." | No | | "How many conversations did we handle last month, and how fast did we respond?" | No | | "How is the AI agent performing compared with the team?" | No | | "Summarise this conversation and rate how it went." | Yes for generating the summary, because it can use AI credits; reading the existing rating is free | See [Home dashboard](/analytics/dashboard) and [Reports](/analytics/reports). ## AI agents, tools, and Knowledge | Ask | Needs your confirmation? | | - | - | | "List my agents and which WhatsApp number each one answers." | No | | "Create a new agent for the support line." | No | | "Write instructions for an agent that sells abayas and handles returns." | No, it returns a draft for you to review; nothing is saved or published | | "Save the current changes as a draft version." | No | | "Compare the draft with the live version." | No | | "Publish the draft." / "Roll back to the previous version." | Yes | | "Make this agent the main agent." / "Point the sales number at this agent." | Yes | | "Add a custom tool that calls our order-tracking API." | No for creating; **yes** to publish or replace | | "Install the order-status tool from the Tools showcase." | Yes | | "Add +9665... as a test number for the agent sandbox." | No | | "Remove that sandbox test number." | Yes | | "Which articles has the agent never used?" | No | | "Restore the March version of the returns article." | No. It becomes a draft that replaces the current unpublished draft, and is never published | | "Mark the shipping article as reviewed." | No | | "Write an article about our exchange policy and publish it." | No for the draft; **yes** to publish | | "Delete the outdated shipping folder." | Yes | | "Look at our website and set up a first agent and knowledge base." | Yes, to create them, and only in an empty workspace | Only published versions can go live, and routing a number to an agent requires that agent to have a published version. The assistant cannot chat with an unpublished agent to test it; use **Test your agent** in the agent editor for that. See [Test and publish](/agents/test-and-publish), [Tools](/tools/overview), and [Knowledge](/knowledge/overview). ## Integrations and channels | Ask | Needs your confirmation? | | - | - | | "Is my Zid connection healthy?" | No | | "Connect my Shopify store." | You finish sign-in and consent in the browser | | "Connect WhatsApp." / "Connect my Meta catalog." | You finish Meta login in the browser | | "Sync the Meta catalog." | Yes | | "Update the WhatsApp business description and address." | Yes | | "Change the WhatsApp button's colour, position, or call-to-action text on my website." | No | | "Change the Website chat avatar." | No | | "Disconnect this WhatsApp number." | Yes | For a store or Meta connection the assistant gives you a link: the **WhatsApp** page under **Integrations** ready to connect (or **Integrations** itself for a catalog), where you click **Connect WhatsApp** and complete Meta's steps yourself. See [Integrations](/integrations/overview), [WhatsApp](/channels/whatsapp), [Website chat](/channels/website-chat), and [WhatsApp button](/channels/whatsapp-button). ## Team, settings, and billing | Ask | Needs your confirmation? | | - | - | | "Who is on the team, and are any invites pending?" | No | | "Invite [maha@example.com](mailto:maha@example.com) as a Manager." / "Resend that invite." / "Cancel it." | Yes | | "Change Omar's role to Agent." / "Remove Omar." | Yes | | "Turn off browser notifications for handovers." | No | | "Set my message-status webhook to this URL." | Yes | | "How many credits are left, and when does the plan renew?" | No | | "Show my last three invoices." | No | | "Buy 5 credit packages." | Yes, charged to the saved payment method | | "Pay the open invoice." | Yes, charged to the saved payment method | | "Turn on auto top-up." / "Change the billing email." | Yes | | "Open the billing portal so I can change my card." | Yes, then you finish in the browser | Credit packages are 1,000 credits each (up to 1,000 packages in one purchase). The purchase preview shows the exact amount and currency before you agree; the assistant never handles card numbers. Billing is available only through Claude Code, Codex and other clients that use the main address; ChatGPT and the Claude connector leave it out. Roles cannot be created or edited through assistants; see [Team and roles](/settings/team-and-roles). See [Team and roles](/settings/team-and-roles) and [Top-ups and renewal](/billing/top-ups-and-renewal). ## Built-in workflows Popcorn publishes four ready-made workflows. Depending on the assistant, they appear as selectable prompts or commands. Each one tells the assistant to read first, show you an exact preview, and wait for your confirmation. | Workflow | What it does | | - | - | | **Safely prepare and launch a campaign** | Takes your objective (and optionally an existing campaign), builds or updates a draft without sending, then presents the audience, template, timing, and delivery preview and waits for your confirmation before launch. | | **Triage the Popcorn inbox** | Takes an objective and a maximum number of conversations (up to 100, default 25), reviews them with the narrowest useful filters, and proposes priorities and assignments before changing anything. It never sends a customer message without showing you recipient, channel, and content first. | | **Review and publish an agent version** | Takes an agent, reads its live and draft versions with linked knowledge, tools, and channels, shows the differences and any warnings, and prepares a publication bound to that exact draft for your confirmation. | | **Connect a commerce or messaging integration** | Takes a provider (Shopify, Salla, Zid, Meta, or Slack), gives you the sign-in link, waits for you to finish in the browser, then checks connection health. It does not start a catalog sync without a separate confirmation. | ## Files When a request needs a file, such as a template header image, a product photo, a Knowledge import, an agent avatar, an Inbox attachment, or a Website chat icon, the assistant uploads it to Popcorn through a short-lived, checked upload (the upload link is valid for 15 minutes). Size limits: images (JPEG, PNG, WebP) up to 5 MB, MP4 video and audio up to 16 MB, PDF up to 10 MB, CSV up to 20 MB, plain text and JSON up to 5 MB. Images for Website chat and the WhatsApp profile must be JPEG, PNG, or WebP. ## What assistants cannot do These are deliberately unavailable, regardless of your role: * Create API keys (they can list and revoke existing ones). * Create, edit, or delete roles. * Sign in to Shopify, Salla, Zid, Meta, or Slack for you, or accept their terms. * Enter card details or complete a bank authentication. * Test-chat with an agent before it is published. * Edit or delete automated campaigns (they can create, activate, deactivate, and read them). * Delete internal notes. * Reach any workspace other than the one the connection was approved in. * Read billing, buy credits or pay invoices through ChatGPT or the Claude connector. ## Related * [Overview](/ai-assistants/overview) * [Permissions and safety](/ai-assistants/permissions-and-safety) # Home dashboard Source: https://docs.trypopcorn.ai/analytics/dashboard Read Home: your agent's summary, the conversations that need you, and sales, orders, handover, message, agent and product figures for a date range. **Home** is the first page you see after signing in. It greets you and summarises how your AI agent and team performed over a date range: what needs you right now, sales and orders, conversations and handovers, messages and delivery issues, top agents and products, and your latest campaigns. Use it for a quick daily check; use [Reports](/analytics/reports) when you need response-time, resolution and per-person breakdowns or a CSV. > [!NOTE] > > Home usually shows the banner "Dashboard insights are in beta. Some metrics may be incomplete while we improve the data." ## Before your agent is on WhatsApp While your workspace has no WhatsApp number connected and no conversations in about the last six months, Home shows your agent's setup instead of results. It has a short summary in your agent's voice ("I know your store and I'm ready to take orders. Put me on WhatsApp and I'll start answering your customers."), **Check what I know**, **Connect WhatsApp** ("About 5 minutes. A number that isn't on WhatsApp yet works best."), and a **Try your agent** chat ("Ask what a customer would. Nothing is sent to WhatsApp."). Your agent's results show up here once it is live. It appears only for roles that can connect integrations. See [Test and publish](/agents/test-and-publish). ## Choose a date range The date picker at the top right applies to every section except **Campaigns**. | Option | What it shows | | - | - | | **7 days** (default) | Today and the previous six days | | **30 days** | Today and the previous 29 days | | **90 days** | Today and the previous 89 days | | **Custom** | Pick **From** and **To** dates, then **Apply** (or **Cancel**) | A range longer than 180 days is not shown: Home says "Choose 180 days or fewer" and asks you to pick a preset or a shorter range. The range is kept in the page address, so you can bookmark or share it. Days are counted in your browser's time zone (Reports use the workspace time zone instead). Every card that shows a trend compares the selected range with the period of the same length immediately before it. A card shows no trend when the previous period had no data or the value is unchanged. While a new range loads, the previous figures stay on screen, dimmed. ## Summary and Needs you At the top, a card named after your agent prints the range and a few sentences, with **Full report** opening [Reports](/analytics/reports) for the same dates: * Sales: "I brought in 2,400 in sales, 12.4% more than the previous period." (or "less", or just the amount), or "I made no sales in this period." * Conversations: "I handled 38 of 41 conversations on my own and handed 3 to your team." * What needs you: "4 conversations need you." or "Nothing in your inbox needs you right now." Beside it, the **Needs you** panel lists up to four conversations that need a person, with the customer, the time, a status badge (**Needs you**, **Snoozed**, **Waiting on customer**, **Agent**, **Closed**, or the teammate it is assigned to, shown as **You** when it is yours) and its tag. The count shows next to the title, and **Open inbox** opens the Inbox. When there is nothing to do it reads "Nothing needs you right now". See [What sends a conversation to Needs you](/inbox/overview#what-sends-a-conversation-to-needs-you). ## Overview cards Four cards sit under the summary: | Card | How it is calculated | | - | - | | **Revenue from your agent** | Total value of all orders created in Popcorn during the range, in your workspace's default currency (**Settings → General → Default currency**). | | **Conversations** | Conversations started in the range. | | **Messages from your agent** | Number of replies the AI agent sent. Template messages and internal tool steps are not counted. | | **Your agent's response time** | Average time, in seconds, the AI agent took to reply to a customer message. It reads "No replies" when the agent sent none. A decrease is shown as an improvement. | ## Sales and Orders **Sales from conversations** is a daily chart of the revenue from your agent, with a dashed line for the **Previous period**. Hover a day to see the figures. It reads "No sales in this period" when there are none. **Orders** covers orders created in Popcorn during the range, in the default currency: | Figure | Meaning | | - | - | | **Orders** | Number of orders, with the trend against the previous period | | **Paid orders revenue** | Value of orders whose status is paid | | **Average order value** | Revenue divided by number of orders | | **Average items per order** | Total quantity of products divided by the number of orders that contain products (shipping and cash-on-delivery fee lines are excluded) | | **Order conversion rate** | Orders divided by conversations started in the range, capped at 100% | Order details, statuses and payment methods are described in [Orders](/orders/overview). ## Conversations and Handover rate **Conversations** charts conversations started per day, split into **Your agent** (conversations in which no human teammate sent a message) and **Your team** (conversations in which at least one teammate replied), with the previous period as a dashed line. It reads "No conversations in this period" when nothing started. **Handover rate** ("Share of conversations your agent handed to your team") is the percentage of conversations started in the range in which both the AI agent and a human teammate sent messages. It shows the total, "N handled by your agent" (conversations in which no human replied at all, including those with no reply yet) and **Handed to your team**, with a daily chart. A rising handover rate usually means the agent is missing knowledge or hitting its **Hand over to your team** rules. See [Capabilities](/agents/capabilities) and [Spotlight](/agents/spotlight). ## Conversations by status Conversations that are currently **Open** (including new, unanswered ones) or **Closed**, grouped by the day they started. A conversation that started in the range and was closed later still counts as **Closed**. ## Messages and Top delivery issues **Messages** counts outbound messages sent by the AI agent and by your team (template sends and internal tool steps excluded): | Figure | Meaning | | - | - | | **Sent** | All outbound messages in the range | | **Delivered** | Messages WhatsApp confirmed as delivered or read, with no error | | **Failed** | Messages WhatsApp reported as failed, or that returned an error | **Top delivery issues** groups the failed messages by cause and shows each cause's count and share of all failures: * Spam rate limit hit * Rate limit issues * Temporarily blocked for policies violations * Country restricted * Message Undeliverable * Business eligibility payment issue * Service unavailable * Other delivery issues If there were no failures, the panel reads "No delivery issues in this period". To understand and fix the causes, see [Delivery and reachability](/campaigns/delivery-and-reachability). ## Top agents Up to five AI agents, ranked by **Total**. Numbers are attributed through the WhatsApp number each agent is attached to; a number with no agent of its own counts towards the workspace's default agent. | Column | Meaning | | - | - | | **Rank**, **Name** | The agent's position and name | | **Resolved** | Conversations started in the range that are now **Closed**, in which the agent replied and no teammate ever sent a message | | **Assisted** | Conversations in which both the agent and a teammate sent messages | | **Total** | Conversations in which the agent sent at least one message | | **Messages** | Messages the agent sent in the range (template messages and internal tool steps excluded) | **Agent report** opens the **Team** tab of [Reports](/analytics/reports) for the same dates. Until an agent has handled a conversation, the panel reads "No agent activity in this period". ## Most recommended and Best-selling products * **Most recommended products**: the five products the AI agent recommended most often in the range, with "N recommendations" each. Empty state: "No product recommendations in this period". * **Best-selling products**: the five products that appear in the most orders in the range, with "N orders" each (ties are broken by revenue). Empty state: "No sales in this period". Recommendation rules that influence what the agent suggests are in [Product catalog](/products/catalog) and [Recommendation rules](/products/recommendation-rules). ## Campaigns **Campaigns** shows the total number of campaigns in your workspace (all time, not limited to the date range) and a table of the first five, with **Name**, **Status**, **Audience** (number of recipients) and **Delivered**. **All campaigns** opens [Campaigns](/campaigns/overview), where each campaign's delivery and failure figures live. With none yet, it reads "No campaigns yet" and offers **Create campaign** to roles that can edit campaigns. ## Warnings you may see | Message | What to do | | - | - | | "Your Meta catalog connection has expired" | Click **Reconnect**, which opens **Integrations**. See [Products in WhatsApp](/channels/whatsapp-catalog). | | "Part of your dashboard didn't load" | A temporary loading problem. Click **Try again**. | | "Couldn't load this section" inside a panel | The same, for one section. Click **Try again** at the top. | | "No metrics in this period" | Nothing happened in the range. Widen the range. | | A chart shows a placeholder sentence instead of a line | There is no data to plot for the range. It is not a missing feature; widen the range. | ## Related * [Reports](/analytics/reports) for response times, resolution, per-person tables and CSV export * [Spotlight](/agents/spotlight) for a quality review of AI conversations * [Credit usage](/billing/credit-usage) for what the period cost in credits # Reports Source: https://docs.trypopcorn.ai/analytics/reports Use Reports to measure conversation volume, first reply and resolution times, what your agent resolves alone, and team performance, and export CSVs. **Reports** answers the operational questions [Home](/analytics/dashboard) does not: how fast customers get a first reply, how many conversations your AI agent resolves without a person, why conversations are handed over, and how each teammate performs. Every report covers a date range you choose and can be exported as CSV. ## Before you start * Reports are visible to every predefined role (Owner, Admin, Manager, Agent and Viewer all have **Analytics** view access). See [Team and roles](/settings/team-and-roles). * Reports use your workspace time zone (**Settings → Profile → Time zone**) for day boundaries and peak hours. Business-hours figures also use **Working hours** from **Settings → General**. See [Workspace settings](/settings/workspace). * Test conversations (the **Test conversations** folder in the Inbox) are excluded from every report. ## Pick a date range Use the picker at the top right: **7 days**, **30 days** (default), **90 days** or **Custom** with **From** and **To**, then **Apply**. Dates are inclusive calendar days, so 1–7 March is seven full days. A range longer than 180 days is not allowed; the page shows "Date range too long" and "Reports cover up to 180 days. Pick a shorter range." and no report loads until you shorten it. The selected tab and dates are kept in the page address, so you can bookmark or share a link to a specific report and period. The four reports are tabs under the title: **Volume**, **Response time**, **Resolution** and **Team**. **Export all conversations** sits beside the date picker. If a report can't load you see "Couldn't load this report" with **Try again**; choose a shorter range if it keeps failing. ## Volume What came in, from where, and when. With no conversations in the range, the tab reads "No conversations from" the first date "to" the last, and suggests a longer range. | Figure | Meaning | | - | - | | **Total conversations** | Conversations started in the range, with the percentage change against the period of the same length before it and "Previous period" with its count | | **Agent only** | Conversations in which no teammate sent a message and nobody assigned them to a human; "N% of all conversations" is shown underneath | | **Team involved** | Conversations in which a teammate replied or the conversation was assigned to a human | * **Conversations over time**: conversations started per day. **Export CSV** downloads a `Date, Conversations` file. * **By source**: counts per origin of the conversation: **WhatsApp**, **Website widget**, **Template** (started by a template you sent), **Sandbox** (the test number) or **API**. Other origins show under a readable version of their name. * **By tag**: the ten most common conversation tags; untagged conversations are grouped as "Untagged". Tags are managed in [Tags and macros](/inbox/tags-and-macros). * **Peak hours**: conversations started per hour of the day (0:00 to 23:00) in your workspace time zone. Use it to plan shifts. ## Response time How long customers wait for a first reply, and how long conversations take to close. | Figure | Meaning | | - | - | | **Median first reply** | Median time from a customer's first message to the first reply from the AI agent or a teammate. The change against the previous period is shown; a decrease is shown in green because lower is better. | | **Median first reply in business hours** | The same median, counting only time that falls inside your **Working hours**. A message received at 20:00 and answered at 09:05 the next day counts as 5 minutes. | | **Median time to resolve** | Median time from the start of a conversation to when it was last closed, over conversations started in the range that have since been closed ("Closed: N") | | **Total conversations** | Conversations started in the range | **First reply speed** ("Share of conversations that got a first reply within each time.") shows **Under 1 minute**, **Under 5 minutes**, **Under 30 minutes** and **Under 1 hour** as the percentage of conversations whose first reply arrived within that time. Conversations that were never answered are not part of these percentages. * **First reply time**: median first reply per day. **Export CSV** downloads `Date, Median first reply (seconds), Average first reply (seconds), Conversations`. * **Who replied first**: **Agent first reply** and **Team first reply**, each with the median and "Median of N conversations" in which the first reply came from the AI agent or from a teammate. First-reply calculations count the first reply from the AI agent or a teammate after the customer's first message. Follow-ups, handover notices, internal notes, rejected AI drafts and internal tool steps are ignored, and replies that took longer than seven days are dropped. ## Resolution How much your AI agent handles on its own, and why conversations are handed over to your team. Every conversation is classified by who actually replied: | Handling | Meaning | | - | - | | **Agent only** | No teammate replied and the conversation was never assigned to a human. Conversations nobody has replied to yet also count here. | | **Agent and team** | The AI agent replied, and a teammate replied or was assigned | | **Team only** | The AI agent never replied; a teammate did, or the conversation was assigned to one | | Figure | Meaning | | - | - | | **Resolved by the agent alone** | **Agent only** conversations as a percentage of all conversations, with the change against the previous period | | **Total conversations** | Conversations started in the range | | **Close rate** | Percentage of those conversations that were closed within the range ("Closed: N") | | **Handed to the team** | Number of times the AI agent stopped and handed a conversation to your team | * **Who handled conversations**: a pie of **Agent only**, **Agent and team** and **Team only**. * **Resolved by the agent over time**: the share per day. **Export CSV** downloads `Date, Total, Agent only, Resolved by the agent %`. * **Why conversations were handed to the team**: a count per reason. The reasons that can appear are "The agent handed it over" (the agent used its handover tool), "Credits ran out" (which also counts handovers because a plan billed through Zid ended), "The agent couldn't read an attachment" (the customer sent a file type the agent cannot read), "The agent's replies didn't pass its quality check" (the AI Manager rejected the reply), "The agent couldn't reply" (the reply could not be generated), "No agent was set up" (no agent was attached to the channel) and "Flagged for safety" (the Guard blocked the conversation). * **Resolved by the agent, by tag**: **Total**, **Agent only** and the share for each conversation tag, so you can see which topics the agent handles well. To reduce handovers, review the agent's [Capabilities](/agents/capabilities) (**Hand over to your team**, **Block spam and off-topic chats**, **Check replies before sending**) and its [Knowledge](/knowledge/overview). ## Team One row per human teammate who handled at least one conversation in the range. A conversation is attributed to the last teammate who was assigned to it. | Column | Meaning | | - | - | | **Teammate** | Teammate's name | | **Conversations** | Conversations started in the range that the teammate handled | | **Messages sent** | Messages the teammate sent in those conversations | | **Median first reply** | Median time from the moment the conversation was assigned or handed over to the teammate until their first reply | | **Median time to resolve** | Median time from that assignment until the conversation was closed | | **Closed** | Conversations the teammate closed within the range | | **Close rate** | **Closed** divided by **Conversations** | **Export CSV** downloads the table with the average first reply as an extra column. If nobody on the team handled a conversation, the tab says "No team activity": "This report covers conversations your team handled. No conversation was assigned to a teammate in this period." ## Export all conversations **Export all conversations** (top right) downloads one row per conversation in the range, newest first, with these columns: Teammate, Conversation ID, Tag, Source, Customer name, Customer phone, First reply (calendar time), First reply (business hours), Time to resolve, First reply at, Started at, Resolved at, Messages and Handling (`ai_only`, `hybrid` or `human_only`). Timestamps are in your workspace time zone. The export contains at most 10,000 conversations. You see **Export complete** with "Rows exported: N"; when the range has more, it reads "Exported N of total rows." Narrow the range and export again. If it fails you see "Couldn't export conversations". ## Troubleshooting | Symptom | Cause and fix | | - | - | | "Couldn't load this report", with "Check your connection and try again, or pick a shorter range." | The query timed out or failed. Click **Try again**, or choose a shorter range. | | Business-hours figures look identical to calendar figures | **Working hours** are not set. Set **Start** and **End** under **Working hours** in **Settings → General**. If they are unset, reports assume 09:00–17:00. | | Days look shifted by one | Check the workspace **Time zone** in **Settings → Profile**; reports use it, not your browser's time zone. | | A teammate is missing from **Team** | They were never assigned a conversation in the range. Assignment, not replying while the AI is in charge, is what attributes a conversation. | ## Related * [Home dashboard](/analytics/dashboard) for the high-level overview * [Working conversations](/inbox/working-conversations) for assignment, handover and closing * [Credit usage](/billing/credit-usage) for what the period cost # API Reference Source: https://docs.trypopcorn.ai/api-reference/introduction Create an API key, authenticate requests to the Popcorn API, and find the endpoints for sending templates and receiving delivery status. The Popcorn API lets your own systems send approved WhatsApp template messages through your connected WhatsApp number and receive delivery status updates back. It is meant for developers integrating an order system, CRM, or automation tool with Popcorn. Everything else, from campaigns to inbox triage, is done in the dashboard or through [AI assistants](/ai-assistants/overview). ## What the API covers | Endpoint | What it does | | - | - | | `POST /api/v2/template/send` | Send a template to one phone number, with tracking, async mode, and webhook callbacks. See [Send a template](/api-reference/templates/send). | | `POST /template/send` | The standard send endpoint without tracking. See [Send a template](/api-reference/templates/send). | | `GET /template` | List the templates in your workspace with their IDs, languages, and approval status. | | `GET /api/v2/template/health` | Check that the API is up and your key is accepted. | | Message Status Webhook | Popcorn calls your URL when a tracked message is sent, delivered, read, or fails. See [Message status webhooks](/api-reference/webhooks/message-status). | Base URL: `https://api.trypopcorn.ai` ## Before you start * A WhatsApp number connected under **Integrations** and at least one template approved by Meta. See [Connect a WhatsApp number](/channels/whatsapp) and [Templates](/campaigns/templates). * A role that can manage API keys. By default the Owner and Admin roles can create and revoke keys; the Manager role can only view the list. See [Team and roles](/settings/team-and-roles). ## Create an API key **1. Open the developer settings** Go to **Settings → API keys and webhooks** (in the **Developer** group). The **API keys** panel reads "Use a key when your own server calls Popcorn AI." **2. Create the key** Click **Create API key** (with no keys yet the page reads **No API keys yet**, with the same button), enter a **Name (optional)** such as `Production`, and click **Create key**. You see **API key created**. A key with no name is called **Default**. **3. Copy it now** **Copy your API key** shows the full key once: "You won't see this key again. Store it somewhere safe." Click **Copy**, then **Done**. The dialog closes only with **Done**. After that the list shows only a masked form, such as `sk-...abcd`. Keys start with `sk-`. The table shows each key's **Name**, **Created** date, **Last used** date (or **Never used**), and **Status** (**Active** or **Revoked**). To remove a key, click **Revoke**, then **Revoke key** on "Revoke *name*?" ("Apps using this key lose access right away. This can't be undone."). You see **API key revoked**; the key cannot be restored, and revoked keys stay in the list. > [!NOTE] > > Keep API keys for backend integrations, where your own server calls Popcorn. To let ChatGPT, Claude, or Codex work in your workspace, use [AI assistants](/ai-assistants/overview) instead; that connection needs no API key. ## Authenticate requests Send the key in the `POPCORN-API-KEY` header on every request: ```bash theme={null} curl https://api.trypopcorn.ai/api/v2/template/health \ -H "POPCORN-API-KEY: sk-your_popcorn_api_key" ``` ```json theme={null} { "status": "ok", "service": "template-v2-api", "version": "2.0", "timestamp": "2026-09-01T10:30:00.000Z" } ``` The `/api/v2` endpoints also accept `Authorization: Bearer sk-your_popcorn_api_key`. The `/template` endpoints accept only `POPCORN-API-KEY`. Each key belongs to one workspace, the one you were in when you created it. Requests act on that workspace's templates, WhatsApp numbers, and Inbox; you cannot address another workspace with a key. ## Authentication errors | HTTP status | Response | Cause | | - | - | - | | `401` | `{"error": "API Key not included in headers."}` | No `POPCORN-API-KEY` header on a `/template` endpoint. | | `401` | `{"success": false, "error": {"code": "UNAUTHORIZED", "message": "API Key or Authorization header required"}}` | No key on an `/api/v2` endpoint. | | `401` | `{"error": "Unauthorized", "message": "invalid api key"}` | The key does not exist or has been revoked. | | `401` | `{"error": "Unauthorized", "message": "api key must start with sk-"}` | The header value is not a Popcorn key. | | `401` | `{"error": "Unauthorized", "message": "organization suspended"}` | The workspace is suspended, for example after a lapsed subscription. See [Top-ups and renewal](/billing/top-ups-and-renewal). | | `403` | `{"error": "Unauthorized", "message": "The specified phone number does not belong to this organization"}` | A `POPCORN-PHONE-NUMBER` header names a number that is not connected to your workspace. | ## Choosing between the API and AI assistants | Use the API when | Use AI assistants when | | - | - | | Another system needs to send a template automatically, for example an order confirmation from your ERP. | A person wants to run the workspace in natural language from ChatGPT, Claude, or Codex. | | You need delivery status pushed to your server. | You need campaigns, inbox triage, customers, products, orders, agents, or knowledge, none of which the API exposes. | | You are building a backend integration with a long-lived key. | You want access tied to a user, their role, and an approval screen instead of a key. | ## Related > **[Send a template](/api-reference/templates/send)** > > Request and response formats for both send endpoints, and how to list templates. > **[Message status webhooks](/api-reference/webhooks/message-status)** > > Configure the webhook URL, token, and events, and read the payload. > **[Templates](/campaigns/templates)** > > Create templates and get them approved by Meta before sending. > **[AI assistants](/ai-assistants/overview)** > > Run your workspace from ChatGPT, Claude, or Codex without an API key. # Send a Template Source: https://docs.trypopcorn.ai/api-reference/templates/send Send an approved WhatsApp template to one phone number from your own system, list your templates, and handle the responses and errors. Use these endpoints to send a WhatsApp template message to a single recipient from an external system, for example an order confirmation from your ERP. Popcorn sends it from your connected WhatsApp number, creates or reopens the conversation in the **Inbox**, and optionally lets the AI agent handle the reply. There are two send endpoints. Use `/api/v2/template/send` for new integrations: it adds template lookup by name, async mode, your own tracking ID, and [status webhooks](/api-reference/webhooks/message-status). `/template/send` is the standard endpoint and stays supported. ## Before you start * An API key from **Settings → API keys and webhooks**. See [API Reference](/api-reference/introduction). * A template with Meta status **Approved**, created for a WhatsApp number that is still connected. Templates in any other status are rejected. See [Templates](/campaigns/templates). * The recipient's number in international format with the country code and no `+`, for example `966501234567`. > [!WARNING] > > If the template body has placeholders and you omit `variables`, Popcorn sends the sample values entered when the template was created. Always pass `variables` for templates with placeholders. An authentication (one-time code) template is the exception: it needs the code. See [Authentication templates](#authentication-templates). ## List your templates `GET https://api.trypopcorn.ai/template` returns every template in the workspace that has not been deleted, newest first, with the IDs you need for sending. ```bash theme={null} curl https://api.trypopcorn.ai/template \ -H "POPCORN-API-KEY: sk-your_popcorn_api_key" ``` ```json theme={null} { "success": true, "data": { "templates": [ { "id": "12345-abcd-6789-efgh", "metaTemplateName": "order_confirmation", "metaTemplateCategory": "UTILITY", "metaTemplateType": "TEXT", "metaTemplateLanguage": "en", "metaTemplateComponents": "[...]", "metaTemplateMetaId": "1234567890", "metaTemplateMetaStatus": "APPROVED", "createdAt": "2026-08-01T09:00:00.000Z", "updatedAt": "2026-08-02T09:00:00.000Z" } ], "count": 1 } } ``` Only templates whose `metaTemplateMetaStatus` is `APPROVED` can be sent. `metaTemplateComponents` is the template structure as a JSON string, including button texts, which you need for `buttonValues`. ## V2 endpoint (recommended) `POST https://api.trypopcorn.ai/api/v2/template/send` Authenticate with `POPCORN-API-KEY: sk-...` or `Authorization: Bearer sk-...`. Send `Content-Type: application/json`. | Parameter | Type | Required | Description | | - | - | - | - | | `templateId` | string | One of the two | The template ID from the list endpoint. | | `templateName` + `templateLanguage` | string | One of the two | Look the template up by name and language code (`en`, `ar`, …). The name is matched case-insensitively, treating any non-alphanumeric character as `_`; the language must match exactly. | | `toNumber` | string | Yes | Recipient number: 10 to 15 digits, optional leading `+`, spaces ignored. | | `fromNumber` | string | No | One of your connected WhatsApp numbers (digits only). If omitted, or if the number is not connected to your workspace, the template's own number is used. It must belong to the same WhatsApp Business account as the template. | | `variables` | string\[] | No | Values for the body placeholders `{{1}}`, `{{2}}`, … in order. For an authentication template, the first value is the verification code and it is required. | | `buttonValues` | object | No | Values for URL buttons, keyed by the button's text. See [Dynamic URL buttons](#dynamic-url-buttons). | | `autoPilot` | boolean | No | `true`: the AI agent bound to the sending number replies when the customer answers. `false` (default): the agent does not reply and the conversation is placed in the **Unassigned** folder for your team. | | `async` | boolean | No | `true`: respond `202` immediately and send in the background. Default `false`. | | `messageId` | string | No | Your own ID for the message. Returned in the response and in every webhook. If omitted, Popcorn generates one in the form `msg--`. | | `metadata` | object | No | Any JSON object, stored with the message's tracking record. Not sent to the customer or included in webhooks. | ```bash theme={null} curl -X POST https://api.trypopcorn.ai/api/v2/template/send \ -H "POPCORN-API-KEY: sk-your_popcorn_api_key" \ -H "Content-Type: application/json" \ -d '{ "templateName": "order_confirmation", "templateLanguage": "en", "toNumber": "966501234567", "variables": ["Sara", "ORD-4521"], "buttonValues": { "Track Order": "ORD-4521" }, "autoPilot": true, "messageId": "order-4521-confirmation", "metadata": { "orderId": "ORD-4521" } }' ``` ### Responses Synchronous (`async` omitted or `false`), HTTP `200`, after WhatsApp accepted the message: ```json theme={null} { "success": true, "messageId": "order-4521-confirmation", "conversationId": "3f2b7c1e-...", "timestamp": "2026-09-01T10:30:00.000Z" } ``` Async (`async: true`), HTTP `202`, before anything is sent: ```json theme={null} { "success": true, "messageId": "order-4521-confirmation", "timestamp": "2026-09-01T10:30:00.000Z" } ``` In async mode, validation, template lookup, and sender lookup still happen before the `202`, so a wrong template or number is reported synchronously. A failure at WhatsApp itself is only logged: no error response and no webhook, because tracking starts once WhatsApp accepts the message. Use synchronous mode when you need to know that the send went through. If the request to WhatsApp fails at the network level (timeout, connection reset, DNS), Popcorn makes up to three attempts with a short backoff before giving up. Error responses from WhatsApp itself are not retried. This applies to both synchronous and async sends. ### Errors Errors use HTTP `400`, `404`, or `500` with this body: ```json theme={null} { "success": false, "timestamp": "2026-09-01T10:30:00.000Z", "error": { "code": "TEMPLATE_NOT_FOUND", "message": "Template not found: order_confirmation", "details": { "templateName": "order_confirmation", "templateLanguage": "en" } } } ``` | HTTP | Code | When | | - | - | - | | `400` | `MISSING_REQUIRED_FIELD` | Neither `templateId` nor `templateName` + `templateLanguage`, or `toNumber` missing. | | `400` | `INVALID_PHONE_NUMBER` | `toNumber` is not 10 to 15 digits. | | `400` | `INVALID_PARAMETERS` | An authentication template was sent without a verification code (`Enter the verification code to send with this authentication template.`) or with one over 15 characters (`Verification codes can be at most 15 characters.`). Checked before async mode answers `202`. | | `404` | `TEMPLATE_NOT_FOUND` | No template with that ID, or with that name and language, in your workspace. | | `500` | `WABA_NOT_CONFIGURED` | `Template sender mapping is no longer active`: the number the template was created on has been disconnected. | | `500` | `WHATSAPP_API_ERROR` | `message` says which: `Template is not approved for sending`, `No active Meta WhatsApp sender found` (including a `fromNumber` on a different WhatsApp Business account), `Customer cannot receive outbound messages` (the customer is blocked or unsubscribed), `This customer has no WhatsApp delivery identity. Ask them to message you first.`, `WhatsApp has not approved this number's display name yet, so it cannot send messages` (see [WhatsApp profile](/channels/whatsapp-profile)), or `Error sending template message` when WhatsApp rejected the request (for example a paused template or a variable count mismatch). | | `500` | `INTERNAL_ERROR` | Unexpected failure. Retry later. | WhatsApp's own error details are not returned in the response; check the message in the **Inbox** or your WhatsApp Business account for the reason. Authentication errors (`401`, `403`) are listed in [API Reference](/api-reference/introduction#authentication-errors). ### Health check `GET https://api.trypopcorn.ai/api/v2/template/health` requires the same authentication and returns `{"status": "ok", "service": "template-v2-api", "version": "2.0", "timestamp": "..."}`. Use it to confirm a key works before going live. ## Standard endpoint `POST https://api.trypopcorn.ai/template/send` Authenticate with `POPCORN-API-KEY` only. This endpoint has no tracking, no webhooks, and no async mode. | Header | Required | Description | | - | - | - | | `POPCORN-API-KEY` | Yes | Your API key. | | `Content-Type` | Yes | `application/json`. | | `POPCORN-PHONE-NUMBER` | No | Send from a specific connected number (digits only). Omit to use the template's own number. A number that is not connected to your workspace returns `403`. | | Parameter | Type | Required | Description | | - | - | - | - | | `templateId` | string | Yes | The template ID from the list endpoint. | | `recipientNumber` | string | Yes | Recipient number with country code, no `+`. | | `variables` | string\[] | No | Values for the body placeholders, in order. | | `buttonValues` | object | No | Values for URL buttons, keyed by button text. | | `enableAutoPilot` | boolean | No | Same as `autoPilot` above. Default `false`. | ```json theme={null} { "templateId": "12345-abcd-6789-efgh", "recipientNumber": "966501234567", "variables": ["Sara", "ORD-4521"], "buttonValues": { "Track Order": "ORD-4521" }, "enableAutoPilot": true } ``` Success returns HTTP `200` with `{"success": true}`. A send failure also returns HTTP `200`, so check `success` rather than the status code: ```json theme={null} { "success": false, "error": "Template is not approved for sending", "templateId": "12345-abcd-6789-efgh", "timestamp": "2026-09-01T10:30:00.000Z" } ``` `error` is one of: `Template not found`, `Template is not bound to an active Meta sender`, `Template sender mapping is no longer active`, `Template is not approved for sending`, `No active Meta WhatsApp sender found`, `Customer cannot receive outbound messages` (blocked or unsubscribed), `This customer has no WhatsApp delivery identity. Ask them to message you first.`, `WhatsApp has not approved this number's display name yet, so it cannot send messages`, the two verification-code messages above for an authentication template, or `Error sending template message` when WhatsApp rejected the request. This endpoint does not retry network failures. A missing `recipientNumber` or `templateId` returns HTTP `400` with `{"error": "Request error: recipientNumber is required"}`. > [!WARNING] > > The legacy form `POST /template/{templateId}`, with the template ID in the path and the same body without `templateId`, still works but is deprecated. Use `/template/send` or the V2 endpoint for new integrations. ## Authentication templates An authentication template sends a one-time code. Pass the code as the first (and only) item of `variables`, for example `"variables": ["482913"]`. Popcorn also fills the template's copy-code button with the same value, so do not pass `buttonValues`. A missing code, or one longer than 15 characters, is refused before anything is sent: `400 INVALID_PARAMETERS` on the V2 endpoint, `success: false` with the message on the standard endpoint. The Inbox shows the message without the code. Authentication templates cannot be used in bulk campaigns; send them from the Inbox or the API. ## Dynamic URL buttons `buttonValues` fills URL buttons at send time. Keys must match the button text exactly as defined in the template. * **Parameterized URL** (the button URL contains a placeholder, for example `https://example.com/track/{{1}}`): pass only the value. `{"Track Order": "ORD-4521"}` produces `https://example.com/track/ORD-4521`. If you pass a full URL here, only its last path segment is used. * **Static URL**: pass a complete URL to replace it, for example `{"Visit Website": "https://example.com/offer"}`. A static button you do not include keeps its template URL. A parameterized button you do not include is sent with an empty value in place of the placeholder, so always pass a value for every parameterized button. ## What happens after a send * If the recipient's number is not yet a customer in your workspace, Popcorn creates one. * The message appears in the conversation in the **Inbox**. With `autoPilot: false` the agent does not reply and the conversation is placed in **Unassigned**; with `true` the AI agent connected to the sending number answers the customer's replies. See [Inbox overview](/inbox/overview). * V2 sends create a tracking record, so status webhooks follow if you configured them. ## Related * [Message status webhooks](/api-reference/webhooks/message-status) * [Templates](/campaigns/templates) * [Connect WhatsApp](/channels/whatsapp) # Message Status Webhooks Source: https://docs.trypopcorn.ai/api-reference/webhooks/message-status Configure a webhook URL and token, choose which delivery events to receive, and read the payload Popcorn sends for sent, delivered, read, and failed. When you send a template through `POST /api/v2/template/send`, Popcorn tracks that message and calls your webhook URL each time WhatsApp reports a new status: sent, delivered, read, or failed. You get delivery status in real time without polling. Webhooks are sent only for messages sent through the `/api/v2` endpoint. Messages sent through the standard `/template/send` endpoint, from campaigns, or from the Inbox do not trigger them. ## Before you start * An HTTPS endpoint that accepts `POST` requests with a JSON body and answers with a `2xx` status within 10 seconds. Plain `http://` URLs, `localhost`, and private network addresses are rejected. * A role that can edit settings. By default only the Owner and Admin roles can change webhook configuration or run a test. Managers see the panel read-only, with "Only people who can edit workspace settings can change these." ## Configure the webhook **1. Open the webhook settings** Go to **Settings → API keys and webhooks** and find the **Message status webhook** panel ("Get a request on your server whenever a message changes status."). **2. Enter your endpoint** Turn on **Send status updates**, enter your **Webhook URL** ("We send each status change to this URL."), and optionally an **Authentication token**. The token is sent as `Authorization: Bearer ` on every request. Once one is saved, the field reads "A token is saved." and is never displayed again; enter a new value to replace it. **3. Choose the events** Under **Events to send**, tick the statuses you want: **Sent**, **Delivered**, **Read**, **Failed**. All four are on by default, and you need at least one ("Pick at least one event."). Unticked statuses are dropped silently. **4. Save, then test** Click **Save changes** in the **Unsaved changes** bar; you see **Webhook saved**. Then click **Test webhook** at the foot of the panel. It is unavailable until your changes are saved ("Save your changes to test the new URL.") and until a URL is saved ("Save a URL to send a test."). The test goes to the saved URL. ### Status indicators | Indicator | Meaning | | - | - | | **Inactive** | **Send status updates** is off. | | **Not tested** | Enabled, but no delivery or test has happened yet. | | **Active** | The most recent delivery or test succeeded. | | **Test failed** | The most recent delivery or test failed. Check **Last test** and your server logs. | | **Last test** | "Passed on" or "Failed on" with the date and time of the last test. This row and **Success rate** appear only after you have run **Test webhook** at least once. | | **Success rate** | Successful deliveries divided by all real deliveries since the webhook was configured. Test requests are not counted. Shown as **No tests yet** until the first delivery. | The panel also shows an **Example payload**, a short sample of what your server receives. ## Test payload **Test webhook** sends one request, with no retries, and waits up to 10 seconds. It uses the `User-Agent` `Popcorn-Webhook-Test/1.0` and placeholder values so you can tell it apart from real traffic: ```json theme={null} { "version": "1.0", "messageId": "test-1725184200000", "toNumber": "test-recipient", "fromNumber": "test-sender", "timestamp": "2026-09-01T10:30:00+0000", "status": "whatsapp_sent", "providerMessageId": "test-wamid", "statusCode": 0, "reason": "Test webhook" } ``` A successful test shows **Test passed** with "Responded in N ms". A failed test shows **Test failed** with the reason, for example when the URL points to a private address. ## Webhook payload Each status update is a `POST` to your URL with these headers: ```http theme={null} Content-Type: application/json User-Agent: Popcorn-Webhook/1.0 Authorization: Bearer ``` The `Authorization` header is present only when you configured a token. ```json theme={null} { "version": "1.0", "messageId": "my-tracking-id-001", "toNumber": "971501234567", "fromNumber": "971509876543", "timestamp": "2026-09-01T10:30:00+0000", "status": "whatsapp_delivered", "providerMessageId": "wamid.HBgNOTcxNT...", "statusCode": 0, "reason": "Message processed successfully" } ``` | Field | Type | Description | | - | - | - | | `version` | string | Payload version, currently `"1.0"`. | | `messageId` | string | The `messageId` you sent in the request, or the one Popcorn generated (`msg-...`) if you omitted it. Use it to match the event to your record. | | `toNumber` | string | The recipient number from your request. | | `fromNumber` | string | The `fromNumber` from your request. If you did not send one, this is the literal string `"default"`. | | `timestamp` | string | When Popcorn created the notification, in UTC, formatted `yyyy-MM-ddTHH:mm:ss+0000`. | | `status` | string | `whatsapp_sent`, `whatsapp_delivered`, `whatsapp_read`, or `whatsapp_failed`. | | `providerMessageId` | string | WhatsApp's message ID (`wamid`). | | `statusCode` | number | `0` for every non-failure status; an error code for `whatsapp_failed` (see below). | | `errorMessage` | string | Present only on `whatsapp_failed`: the error details WhatsApp returned, as a JSON string. | | `reason` | string | `"Message processed successfully"` on success, or the same text as `errorMessage` on failure. | ## Status events You receive one request per status update WhatsApp reports. A delivered message typically produces `whatsapp_sent`, then `whatsapp_delivered`, then `whatsapp_read`; a message that fails produces `whatsapp_failed`. Popcorn relays statuses as WhatsApp reports them, so a message does not always receive every status, and a failure may arrive without a prior `whatsapp_sent`. | Status | Meaning | | - | - | | `whatsapp_sent` | WhatsApp accepted the message. | | `whatsapp_delivered` | The message reached the recipient's device. | | `whatsapp_read` | The recipient opened the message. | | `whatsapp_failed` | WhatsApp could not deliver the message. Read `errorMessage`. | ### Error codes For `whatsapp_failed`, Popcorn derives `statusCode` from keywords in WhatsApp's error text. When no keyword matches, the code is `9988`. | Code | Name | Set when the error text mentions | | - | - | - | | `2006` | User blocked | "blocked" | | `2008` | Message expired | "expired" | | `2009` | Message undelivered | "undelivered" or "not delivered" | | `2014` | Max retries exhausted | "retry" or "retries" | | `2024` | User not opted in | "not opted in" or "opt-in" | | `9988` | Generic error | Anything else. | Example failure: ```json theme={null} { "version": "1.0", "messageId": "my-tracking-id-002", "toNumber": "971501234567", "fromNumber": "default", "timestamp": "2026-09-01T10:35:00+0000", "status": "whatsapp_failed", "providerMessageId": "wamid.HBgNOTcxNT...", "statusCode": 9988, "errorMessage": "[{\"code\":131026,\"title\":\"Message undeliverable\"}]", "reason": "[{\"code\":131026,\"title\":\"Message undeliverable\"}]" } ``` ## Retries and timeouts Popcorn treats any `2xx` response as success. Anything else, including a timeout after 10 seconds, is a failed attempt. | Attempt | Delay before it | | - | - | | 1st | Immediate | | 2nd | 1 second | | 3rd (final) | 3 seconds | Popcorn does not retry when your endpoint answers with a `4xx` status, except `408` and `429`, which are retried like network errors. After the final failure the event is dropped: it is not queued or resent later. The failure is recorded on the message, counts against **Success rate**, and switches the indicator to **Test failed**. > [!WARNING] > > Return `2xx` as soon as you have stored the payload, and process it afterwards. A handler that takes longer than 10 seconds is treated as failed and retried, so you may receive the same event again. ## Verifying requests Configure an **Authentication token** and reject any request whose `Authorization` header does not carry it. Popcorn does not sign payloads; the bearer token is the only way to confirm a request came from Popcorn. ## Related * [Send a template](/api-reference/templates/send): the `/api/v2` request that creates the tracking record, including `messageId` and `metadata`. * [Delivery and reachability](/campaigns/delivery-and-reachability): what sent, delivered, read, and failed mean for WhatsApp messages in general. # Credit usage Source: https://docs.trypopcorn.ai/billing/credit-usage Track plan and extra credit balances, usage by source, each credit movement per conversation or campaign, and export the list as CSV. The **Credit usage** page ("See where your plan and extra credits go.") shows how your credits are being spent in the current billing period, with one line for every charge, refund and credit added. Use it to find which conversations or campaigns used credits, to check a campaign's final cost, and to reconcile an invoice. ## Before you start * Open **Plan and billing** and click **Credit usage** at the top right. The button is there on every plan, including the free plan. The **Billing** link above the title returns to the Billing page. * The page is available to anyone who can open Billing: Owners, Admins and Managers. ## Usage summary The summary covers the current billing period: from the start of your current subscription period to the date under **Renews on**. On the free plan, or when no subscription is active, the period is the 30 days before your plan's end date. There is no period picker. A link that carries a past period in its address opens that period instead: the **Usage summary** then says, for example, "Sep 1, 2026 to Oct 1, 2026", **Renews on** is left out and the meter never turns amber or red. The **Usage summary** panel shows: * **Plan credits used**, with "of N allocated": your plan's credits for the period. Free credits granted to a new workspace are counted here too. * **Extra credits used**, with "N remaining": credits you bought, automatic top-ups, and credits added by the Popcorn team. Extra credits are used only once plan credits are gone. * **Renews on**: the date your next billing period starts. On the free plan it shows the end of the current plan period. It is hidden when the date has already passed. * A **Plan credits used** meter ("used / allocated", "N plan credits remaining"). It turns amber or red only when all your credits, plan and extra together, are low or gone. When there is no plan allowance, the meter is left out instead of showing "0 of 0". > [!NOTE] > > The **Credits** meter on the Billing page counts free, plan and extra credits together. Credit usage separates plan credits from extra credits, so the remaining figures differ when you hold extra credits. **Usage by source** sits beside the summary. It lists the credits consumed by each source in the period, net of refunds, largest first: | Source | What it covers | | - | - | | **Inbox** | Agent replies in conversations | | **Campaigns** | Campaigns you send from [Campaigns](/campaigns/overview) | | **Automated campaigns** | Messages sent by automated campaigns | | **Popcorn AI team** | Adjustments made by Popcorn support | | **Plan and billing** | Credits added by your plan, purchases and automatic top-ups | ## Credit activity The **Credit activity** table lists every credit movement in the period, newest first, 25 per page. Its description reads "One credit covers every message your agent sends in a single reply." Columns: **Date**, **Activity**, **Customer or campaign** and **Credits**. On a phone the date and customer sit under the activity. Charges appear as plain negative numbers; refunds and credits added appear in green with a plus sign. Use the filter above the table to show **All activity** or a single source: **Inbox**, **Campaigns**, **Automated campaigns**, **Popcorn AI team** or **Plan and billing**. | Activity | Source | What it means | | - | - | - | | **Agent reply** | Inbox | One credit for an agent reply. The customer's name links to the conversation; if the name is unknown you see **View conversation** | | **Campaign send** | Campaigns | Credits reserved when a campaign was launched or scheduled: the audience size divided by 10, rounded up. The campaign name links to the campaign, or you see **View campaign** | | **Campaign refund** | Campaigns | Reserved credits returned after the campaign finished or was stopped, based on messages actually sent | | **Automated campaign send** | Automated campaigns | Whole credits charged for successful sends (1 credit per 5 messages). Fractions carry over, so a line appears only when a whole credit is due | | **Monthly credits added** | Plan and billing | Plan credits for a new billing period, or the free credits of a new workspace | | **Credits purchased** | Plan and billing | Credits bought under **Buy credits** on the Billing page | | **Auto top-up** | Plan and billing | Credits bought by automatic top-up | | **Adjustment by the Popcorn AI team** | Popcorn AI team | Credits added or removed manually by Popcorn support | | **Feature adoption reward** | Plan and billing | Bonus extra credits granted through a product announcement, once per announcement | Expired credits do not appear as activity. When free, plan or extra credits reach their expiry date they simply stop counting toward your balance. ### Reservations and deductions Campaigns and automated campaigns are charged differently, and the table shows the difference: * **Campaigns** reserve their full estimated cost up front. Launching a campaign to 1,000 contacts adds a **Campaign send** line of −100 immediately. If 940 messages are sent, the campaign's real cost is 94 credits and a **Campaign refund** line of +6 appears once the campaign completes or is stopped. A scheduled campaign reserves credits when it is scheduled; if it fails to launch, the reservation is released the same way. * **Automated campaigns** reserve nothing. Each successful send adds a fifth of a credit to a running total, and a whole credit is deducted when the total reaches one. Before sending, Popcorn checks that the balance can cover the next whole credit; if it cannot, the message is not sent and the campaign's results show **Not sent: out of credits**. Chats you start from **Try your agent** on Home or from setup use no credits, so they never appear here. See [What uses credits](/billing/plans-and-credits#what-uses-credits). ## Export CSV **Export CSV** (above the table; it is disabled while the list is empty) downloads the full filtered list, not just the current page, as `credit-usage-YYYY-MM-DD.csv`. The export is capped at 10,000 entries. You see **Export ready** with "Entries exported: N"; when there are more, it reads "Exported the first 10,000 entries. Narrow the filters to get the rest." The file has more detail than the table. Columns: **Date and time** (as `2026-09-30 14:05`), **Source**, **Reason**, **Status**, **Customer or campaign**, **Details** and **Credits**. Source and reason use the same labels as on screen. **Credits** is the signed number, with charges negative, so a spreadsheet reads it as a number. **Status** values: | Status | Meaning | | - | - | | **Charged** | Credits deducted (including campaign reservations) | | **Refunded** | Credits returned | | **Added** | Credits added by a plan period, purchase, top-up or reward | | **Adjusted** | A manual adjustment by the Popcorn AI team | | **Failed** | An agent reply was attempted while no credit could be taken. Nothing was deducted | | **Charged (estimated)** | Usage reconstructed from message history for the period before the activity list existed. Treat these totals as approximate | | **Expired** | Credits that reached their expiry date. Popcorn does not record these today | **Details** carries extra context where it exists, for example `2 inbound messages → 1 assistant reply` when several customer messages arrived in a burst and produced one agent reply. ## Troubleshooting | Symptom | Explanation | | - | - | | **No usage yet** ("Credit activity for this period will appear here.") | Nothing was charged or added in the period with the current filter. Switch the filter to **All activity** | | A large **Campaign send** charge right after launch | This is the reservation for the whole audience. The refund for unsent messages arrives when the campaign completes or is stopped | | **Usage by source** total does not match **Plan credits used** | The breakdown counts credits consumed from all pools in the period, including extra credits, while **Plan credits used** counts the plan pool only | | **Renews on** shows a date but you are on the free plan | On the free plan the date is the end of the current plan period, not a payment date | | **Couldn't load credit activity**, **Couldn't refresh credit activity** or **Couldn't load your credit summary** | The data could not be fetched. Click **Try again** | | **Couldn't export credit activity** | "Check your connection and try again." If the period is very large, filter by source first | ## Related > **[Plans and credits](/billing/plans-and-credits)** > > What a credit is, what uses credits, and what happens when they run out. > **[Top-ups, plan changes and renewal](/billing/top-ups-and-renewal)** > > Buy credits, set up automatic top-up, and manage renewal. > **[Send a campaign](/campaigns/send-a-campaign)** > > The audience preview and credit estimate before you launch. > **[Campaign troubleshooting](/campaigns/troubleshooting)** > > Campaign not sending because of credits, sender, or working hours. # Plans and credits Source: https://docs.trypopcorn.ai/billing/plans-and-credits Popcorn's plans, what a credit is, what uses credits, what happens when they run out, and how the Billing and usage page is laid out. Popcorn charges a monthly plan that includes a fixed number of credits, plus any extra credits you buy. Credits pay for what your AI agent and your campaigns send. Your plan, balance and payments live on the **Billing and usage** page. ## Open the billing page Open the workspace menu at the top of the sidebar and choose **Plan and billing**, or click the credits shown under your agent in the sidebar ("Credits", with how many are left). The sidebar only shows these to roles that can open Billing; see [Who can see Billing](#who-can-see-billing). ## What the page shows On a paid plan the title carries a badge with your plan name, and the top right has **Manage billing** (opens Stripe's billing portal) and **Credit usage** (see [Credit usage](/billing/credit-usage)). Under it: | Part | What it shows | | - | - | | **Plan** | Your plan's name and price, for example "USD 299.00 a month, billed monthly". Once the plan has ended, "Ended on" and the date instead of the price | | **Credits left** | Credits remaining across all pools, with "of N" for the total | | **Extra credits** | Only when you hold bought or added credits: how many are left, with "of N" | | **Renews on** | When the plan renews. Left out when the date is unknown or already past, or once the plan has ended | | **Credits** | A **Credits used** meter ("used / total"), plus one meter per pool when you hold more than one | | **Automatic top-up**, **Early renewal**, **Buy credits**, **Payment method**, **Billing email** | Covered in [Top-ups, plan changes and renewal](/billing/top-ups-and-renewal) | | **Credit costs** | A short panel with the per-message rates; see [What uses credits](#what-uses-credits) | | **Billing history** and **Change plan** | Your invoices, and the plan list | The **Credits** meter changes colour as credits run down. It turns amber when a quarter or less is left, with the hint "Credits are running low. Buy more or turn on automatic top-up." It turns red when none are left: "You're out of credits, so your team answers every conversation." Otherwise the hint is "Renews on" and the date. When a plan billed through Zid has ended, the hint reads "Your plan has ended, so your agent isn't replying to customers. Renew it to turn your agent back on." > [!NOTE] > > The free plan shows a shorter page: a **Credit usage** button and the plan list, described as "Each plan includes monthly credits. You can buy extra credits once you're on a plan." There is no balance, **Manage billing** or **Buy credits** until you subscribe. Your free credits show in the sidebar. ## Plans The plan list is titled **Change plan** on a paid plan and **Plans** on the free plan. Each plan is billed monthly and adds its credits at the start of every billing period. | Plan | Credits per month | Monthly price | Listed features | | - | - | - | - | | **Cheese** | 4,000 | USD 299 | Multiple agents, WhatsApp integration, Marketing campaigns, E-commerce integrations | | **Caramel 10K** | 10,000 | USD 599 | Everything in Cheese, Advanced analytics, Priority support | | **Caramel 20K** | 20,000 | USD 999 | Everything in Cheese, Advanced analytics, Dedicated account manager | | **Caramel 40K** | 40,000 | USD 1,699 | Everything in Cheese, Advanced analytics, Dedicated account manager | Your current plan is marked **Current**; the others show **Upgrade** or **Downgrade**. See [Top-ups, plan changes and renewal](/billing/top-ups-and-renewal#change-your-plan) for what happens when you switch. The public pricing page (trypopcorn.ai/pricing) also lists a **Plain** plan with 2,000 credits a month, Caramel tiers up to 60,000 credits, annual billing at a lower monthly price, and **Enterprise** with custom pricing. Those are not selectable on the Billing page. ### The free plan A new workspace starts on the free plan with 100 free credits, which expire one month after the workspace is created. To keep your agent replying after that, choose a plan. ## What a credit is A credit is the unit Popcorn deducts for agent replies and campaign messages. Your balance is made of up to three pools: | Pool | Where it comes from | When it expires | | - | - | - | | **Free credits** | The 100 credits granted when the workspace is created | One month after creation. They are not renewed | | **Plan credits** | Your plan's monthly allowance, added at the start of each billing period | At the end of the billing period; for a Zid plan, when Zid suspends it (at most two days later). Unused plan credits do not roll over | | **Extra credits** | Credits you buy, automatic top-ups, and credits added by the Popcorn team | Bought credits and automatic top-ups expire one year after they are added | Popcorn spends free credits first, then plan credits, then extra credits. Campaign refunds go back to the pool they were taken from. ## What uses credits | Action | Cost | When it is charged | | - | - | - | | Agent reply in a conversation (WhatsApp or Website chat) | 1 credit per reply | When the agent starts answering a customer message. One credit covers everything the agent sends in a single reply, even when a long reply is split into several WhatsApp messages | | Campaign message | 1 credit per 10 messages | Reserved when you launch or schedule the campaign, from the audience size. When the campaign finishes or is stopped, the cost is recalculated from messages actually sent and the difference is refunded | | Automated campaign message | 1 credit per 5 messages | Charged after messages are sent successfully, in whole credits as sends add up | The **Credit costs** panel on Billing lists three rows: "Template messages and agent replies" at "1 credit per message", "Bulk campaigns" at "1 credit per 10 messages" and "Automated campaigns" at "1 credit per 5 messages". Read the first row as one credit per agent reply, as in the table above. Messages your team sends from the Inbox, including templates sent one by one, do not use credits. Messages that fail to send are not charged: campaigns are settled on messages that reached WhatsApp, and automated campaigns only count successful sends. Test chats from Home and setup are free. A chat you start from **Try your agent** on Home, or from the agent step of setup, is a test conversation. It uses no credits and stays in **Test conversations** in the [Inbox](/inbox/overview). If your workspace has no credits left, the agent stays quiet in a test chat, as it does for a customer. Chats in the **Test your agent** panel of the agent editor and on the sandbox WhatsApp number are charged like any other agent reply. ## What happens when credits run out When your total balance across all pools reaches zero: * The agent stops replying. Each new customer message is handed over to your team: the conversation lands in **Needs you** with "Your agent is out of credits, so it isn't replying". An admin (or the only member) gets a **Conversation Handover - Credits Exhausted** notification in the app, and the agent's Slack or email handover notifications fire if they are set up. * A banner appears across the app: **Your agent stopped replying to customers**, with "You're out of credits, so your team answers every conversation until you top up." Its button reads **Top up credits** (opens Billing at **Buy credits**) on a paid plan and **Choose a plan** on the free plan. Roles that can't open Billing see "Ask your account owner or an admin to top up." instead of a button. * The agent card in the sidebar reads **Stopped, out of credits**. * Campaigns cannot be launched, because the credits for the audience cannot be reserved. * Automated campaigns keep running, but their messages are not sent and appear in the campaign's results as **Not sent: out of credits**. The agent resumes automatically once credits are available again, whether from a purchase, an automatic top-up or your next plan renewal. > [!TIP] > > Popcorn emails the workspace Owner when usage crosses 50%, 80% and 95% of the credits allocated for the period (subject: **Popcorn AI: Your organization has reached 80% usage threshold**, for example) and again when credits are exhausted (**Popcorn AI: Your organization has exhausted its credits**). Each alert is sent once, and can be sent again after a renewal or top-up brings usage back down. Turn on automatic top-up to avoid the interruption; see [Top-ups, plan changes and renewal](/billing/top-ups-and-renewal). ## When a Zid plan ends This applies only to plans billed through the Zid App Market. When Zid suspends your plan at the end of a period (Zid then shows the app as Not Activated), the plan has ended and your agent stops answering customers, even if you still hold credits, extra credits included: * Conversations still with the agent show "Your plan has ended, so your agent isn't replying". Each new customer message is handed to your team and lands in **Needs you**, and the conversation reads "Your plan ended, so *agent* handed this to your team". An admin (or the only member) gets a **Conversation Handover - Plan Ended** notification in the app, and the agent's Slack or email handover notifications fire if they are set up. * The agent card in the sidebar reads **Stopped, plan ended**. * The banner **Your plan has expired** appears, and on the Billing page **Plan** reads "Ended on" and the date. * The period's plan credits stop at the suspension. Extra credits are kept for when the plan is back. Renew in the Zid App Market to turn the agent back on. If you don't, Zid removes the app five days after the end date and Popcorn removes the plan; the agent stays stopped until you subscribe again. See [Renewal](/billing/top-ups-and-renewal#renewal). ## How you are billed Where you subscribed determines where your plan is managed. Extra credits are always bought by card on the Billing page, whichever way your plan is billed. ### Directly, by card (Stripe) Choosing a plan on the Billing page opens Stripe to complete the subscription. The plan activates, and its credits are added, when Stripe confirms the payment. From then on: * **Manage billing** and **Update payment method** open Stripe's billing portal for your account. * Invoices appear under **Billing history**. * The subscription renews monthly on the same date. **Renews on** shows the next date. ### Through the Zid App Market Subscribe to Popcorn in the Zid App Market and connect your Zid store in **Integrations**. The plan is applied to your workspace once the store is linked; if you subscribed before connecting, Popcorn applies the subscription as soon as the connection completes. Popcorn's Cheese plan is offered on Zid monthly or yearly, and plan credits are added for each subscription period Zid reports. When a Zid period ends without a renewal, Zid suspends the plan, usually within a day of the end date. Until then your plan and its remaining plan credits keep working, for at most two days past the end date. The suspension ends the plan and stops your agent; see [When a Zid plan ends](#when-a-zid-plan-ends) and, for renewals, [Top-ups, plan changes and renewal](/billing/top-ups-and-renewal#renewal). ### Through the Salla App Store Subscribe to Popcorn in the Salla App Store with your Salla store connected in **Integrations**. Subscription starts, renewals and trials from Salla activate the plan and add its credits for the period Salla reports; cancellations and expiries (including an expired trial) remove the plan immediately. > [!WARNING] > > If your plan is billed through Zid or Salla, change or cancel it in that app store. The **Upgrade** and **Downgrade** buttons on the Billing page create a separate card subscription with Stripe, which would bill you twice. ## Who can see Billing **Plan and billing** appears for Owners, Admins and Managers. Only Owners and Admins can change anything: buy credits, change the plan, turn on automatic top-up, set the billing email, or open the billing portal. Managers can view the page and [Credit usage](/billing/credit-usage). Agents and Viewers do not see it. See [Team and roles](/settings/team-and-roles). ## Related > **[Credit usage](/billing/credit-usage)** > > See where credits went, by source and per conversation or campaign. > **[Top-ups, plan changes and renewal](/billing/top-ups-and-renewal)** > > Buy credits, set up automatic top-up, renew early, and change plans. > **[Campaign credits and delivery](/campaigns/delivery-and-reachability)** > > How campaign statuses and failed messages relate to what you pay. > **[Automated campaigns](/campaigns/automated-campaigns)** > > Why automated messages were not sent, including when credits ran out. # Top-ups, plan changes and renewal Source: https://docs.trypopcorn.ai/billing/top-ups-and-renewal Buy extra credits, turn on automatic top-up, renew early, change your plan, pay invoices and fix payment problems on the Billing page. When your plan's monthly credits are not enough, you can buy extra credits, let Popcorn top up automatically when the balance drops, or move to a bigger plan. This page covers those actions and what happens at renewal, on the **Billing and usage** page (**Plan and billing** in the workspace menu). ## Before you start * A paid plan. **Buy credits**, **Payment method**, **Automatic top-up**, **Early renewal**, **Billing email** and **Billing history** appear only after you subscribe; the free plan shows the plan list alone. * An Owner or Admin role. Managers can view Billing but cannot buy or change anything. * For one-click purchases, automatic top-up and early renewal: a card saved under **Payment method**. > [!WARNING] > > If your plan is billed through the Zid App Market or the Salla App Store, change or cancel the plan in that app store. **Upgrade** and **Downgrade** on the Billing page start a separate card subscription with Stripe. Buying extra credits by card on the Billing page is fine for every workspace. ## Buy credits **1. Choose an amount** In **Buy credits**, pick **1K**, **3K**, **5K**, **10K** or **20K**, or click **Custom** and type a number. The price per 1,000 credits is shown under the title. Credits are sold in blocks of 1,000, from 1,000 to 1,000,000 at a time. A custom amount is rounded up to the next block, and the page says "Credits are sold in blocks of 1,000, so you'll get N credits." **2. Check the total** The panel shows the credits, the block count times the unit price, and the total. Click **Buy credits**. **3. Confirm and pay** With a saved card, Popcorn asks first: **Buy N credits?** "We'll charge USD X to your card ending in 4242 now." Click **Pay USD X**. You stay on the page and see "N credits added" once the payment is confirmed. Without a saved card, Popcorn opens Stripe checkout, where Stripe shows its own review, and returns you to Billing when you are done. Bought credits are extra credits, valid for one year, and are used only once free and plan credits are gone. They appear in [Credit usage](/billing/credit-usage) as **Credits purchased**, and the invoice appears under **Billing history** as "N credits". Links in the app such as the out-of-credits banner open this panel directly. If Popcorn can't confirm a charge, a banner says **We couldn't confirm this payment**: the payment may have gone through, so check **Billing history** and Credit usage before you try again. ## Payment method **Payment method** shows the saved card, for example "Visa ending in 4242" with "Expires 04/2028". **Update payment method** opens Stripe's billing portal, where you enter the card. With no card it reads **No payment method**: "Add a card to buy credits, pay invoices and turn on automatic top-up." with **Add payment method**. An expired card shows **Card expired**: "Update this payment method before purchasing credits or paying invoices." ## Automatic top-up Automatic top-up buys credits for you whenever the balance falls below a threshold you set, so the agent never stops for lack of credits. **1. Turn it on** In **Automatic top-up**, switch on **Top up automatically**. Without a saved card the switch can't be turned on and the panel says "Add a payment method to turn on automatic top-up." with **Add payment method**. You can always switch it off. **2. Set the threshold** **Low balance threshold**: "A top-up starts when your balance drops below this many credits." The default is 1,000 credits. **3. Set the amount** **Top-up amount** is how much to spend each time. The default is USD 150, and the row shows the credits it buys, such as "Buys 3,000 credits each time". When you leave the field the amount is rounded to a multiple of USD 50, with a USD 50 minimum. **4. Set a monthly limit** **Monthly spending limit** is on by default at USD 500 and reads "Up to 10,000 credits a month". Switch it off and it reads "No monthly cap on automatic top-ups." The minimum limit is USD 50, in multiples of USD 50. **5. Save** A bar appears with "Unsaved changes". Click **Save changes** (or **Discard**). Popcorn confirms with **Billing settings saved**. If it can't, you see **Couldn't save billing settings** and your changes stay in the fields. Leaving the page with unsaved changes asks **Leave without saving?** Once it is on, the description reads, for example, "Buys USD 150.00 of credits whenever your balance drops below 1,000 credits." **This month** shows what automatic top-ups have spent, with "of USD 500.00" when a limit is set. The same **Save changes** bar also saves the **Billing email**. How it runs: * Popcorn checks the balance after credits are deducted. When the remaining credits are at or below the threshold, it charges the saved card for the top-up amount through a Stripe invoice and adds the credits once the payment is confirmed. They are extra credits, valid for one year, listed as **Auto top-up** in Credit usage and in **Billing history**. * The workspace Owner receives **Popcorn AI: Auto top-up completed successfully** by email. * The **This month** counter resets when your subscription renews or a new plan period starts. When a top-up does not happen: | Situation | What happens | | - | - | | The next top-up would exceed the monthly limit | No purchase is made and you receive **Popcorn AI: Auto top-up failed**. Automatic top-up stays on; raise the limit or buy credits manually | | The card is declined, has expired, or has insufficient funds | The purchase fails, automatic top-up is switched off, and you receive **Popcorn AI: Auto top-up failed** with the reason. Update the card, then switch it back on | | No card is on file | Same as a failed payment: switched off, with an email asking you to add a payment method | | The balance is above the threshold when the check runs | Nothing happens, for example because a purchase or renewal just landed | ## Change your plan **1. Pick a plan** In **Change plan**, click **Upgrade** or **Downgrade** on the plan you want. **2. Confirm with Stripe** Stripe opens to confirm the change. If Stripe can't open the page for that plan, its general billing portal opens instead. You return to Billing afterwards. Once Stripe confirms the change, your remaining plan credits are replaced by the new plan's full monthly credits, whether you moved up or down. Extra credits are not affected. The **Plan** figure at the top updates to the new name and price. ## Renewal * Card subscriptions renew monthly. Each renewal adds the plan's credits for the new period; plan credits left over from the previous period expire. Extra credits keep their own expiry. **Renews on** shows the next date. * If a renewal payment fails, nothing changes immediately: your plan and credits stay as they are, and the invoice shows as **Unpaid** in **Billing history**. Pay it with **Pay now**, or update the card first. If Stripe eventually cancels the subscription, see [When a subscription ends](#when-a-subscription-ends). * Zid subscriptions: each renewal Zid reports adds the new period's credits. Plan credits left from the previous period last until its end date at the latest: renew early and both are usable until then; renew after the end date and the old ones end when the renewal arrives. * When a Zid period ends without a renewal, Zid suspends the plan, usually within a day of the end date. Until then the plan and its credits keep working, for at most two days past the end date. The suspension ends the plan: plan credits stop and the agent stops answering customers, whatever credits remain. See [When a Zid plan ends](/billing/plans-and-credits#when-a-zid-plan-ends). Renewing in Zid brings the plan back with the new period's credits. Five days after the end date Zid removes the app and Popcorn removes the plan. A refund through Zid removes the plan immediately. * Salla subscriptions: a cancellation, expiry or expired trial reported by Salla removes the plan immediately. ## Renew early Early renewal lets you pay the next period of a card subscription before it is due, without moving your renewal date. The **Early renewal** panel ("Pay for your next period now. Your usual renewal date stays the same.") appears on the Billing page only when Popcorn has turned the option on. If you don't see it, it isn't available to you yet. > [!NOTE] > > Paying early does not add credits today. The credits for the future period are added when that period starts. To add credits now, use **Buy credits**. **1. Preview** Click **Preview renewal**. Popcorn shows **Paid through**, **Period you're paying for**, **Charge now** and the **Saved card** that will be charged, with the banner **Your renewal date won't change**. Nothing is charged yet. **2. Confirm** Click **Confirm and pay USD X**. On success you see **Early renewal paid** and the invoice appears in **Billing history**. A preview stays valid for 15 minutes; after that, or if anything about your subscription changed, click **Refresh preview** and confirm again. If you see **Early renewal isn't available yet**, the banner says why: | Message | What to do | | - | - | | "Add a payment method before renewing early." | Click **Update payment method**, then **Refresh preview** | | "Pay your open invoice in billing history before renewing early." | Pay the invoice under **Billing history**, then **Refresh preview** | | "This subscription can't be renewed early right now. Contact support if you need help." | Any other reason. Contact support | If a confirmation fails, a banner explains: **Your renewal is still processing** (don't confirm again; refresh in a moment), **Billing details changed** (the preview reloads so you can check the new amount and card) or **Early renewal didn't go through** (your plan and renewal date haven't changed). ## When a subscription ends When a card subscription is cancelled, a Zid or Salla subscription expires, or a Zid subscription is refunded: * Your workspace returns to the free plan. The remaining plan credits are removed; free credits and extra credits stay until they are used or expire. * With a card or Salla plan, the agent keeps replying while any credits remain, then stops as described in [Plans and credits](/billing/plans-and-credits#what-happens-when-credits-run-out). With a Zid plan, the agent stops when the plan ends (at Zid's suspension, or at a refund) and stays stopped, whatever credits remain, until you subscribe again; see [When a Zid plan ends](/billing/plans-and-credits#when-a-zid-plan-ends). * If a billing period ends without a renewal being confirmed, a banner reads **Your plan has expired**: "Renew it to keep using everything in Popcorn AI." Its button, **Renew plan**, opens Billing. Roles that can't open Billing see "Ask your account owner or an admin to renew the plan." On the Billing page, **Plan** shows "Ended on" and the date in place of the price, and **Renews on** is left out. ## Billing history and billing email **Billing history** ("Your invoices and credit purchases.") lists your invoices with **Invoice**, **Date**, **Description**, **Amount**, **Status** and an action. On a phone it shows the date, amount and status. | Status | Meaning | | - | - | | **Paid** | The invoice is settled | | **Unpaid** | An open invoice waiting for payment | | **Failed** | The charge failed | | **Void**, **Uncollectible**, **Draft** | Nothing is left to pay on it | * **Description** shows the plan name, **Auto top-up**, "N credits" or **Credits purchased**, or Stripe's own text for an invoice created by hand. * **Pay now** on an unpaid invoice charges your saved card after you confirm **Pay this invoice?** (the amount and card are shown) and then shows **Invoice paid**. Without a saved card it opens Stripe's payment page for the invoice. An unpaid credit purchase with no Stripe page shows **Add payment method** instead. An uncollectible invoice with a Stripe page also shows **Pay now**. * **View** opens the invoice PDF or page. * With no invoices the panel reads **No invoices yet**. **Billing email** ("Invoices and payment receipts go to this address.") takes an address under **Email address**. Save it with **Save changes**. Until you set one, the field shows your own email and says "Leave it empty to use" that address. An incomplete address is refused with "Enter a full email address, like [name@store.com](mailto:name@store.com)". ## Payment problems A red banner at the top of the Billing page describes the problem and, where there is something to do, offers one action: **Update payment method**, **Pay through Stripe** or **Contact support** ([support@trypopcorn.ai](mailto:support@trypopcorn.ai)). You can close the banner. | Banner | What to do | | - | - | | **Card declined**, **Card expired**, **Card details need updating**, **Insufficient funds** | Click **Update payment method**, or **Pay through Stripe** to pay the open invoice with another card | | **Bank verification required** | Complete your bank's verification, or pay through Stripe | | **Add a payment method** | No card is on file. Add one, then try again | | **Payment needs attention** | Stripe could not confirm the payment. Pay the invoice through Stripe or update the card | | **We couldn't confirm this payment** | The payment may have gone through. Check **Billing history** and Credit usage before trying again | | **Payment could not be completed**, **Payment request did not go through**, **Checkout could not be started** | Temporary failure. Try again in a moment | | **Choose another amount** | You can buy 1,000 to 1,000,000 credits at a time | | **Billing account not found**, **Invoice is not payable here**, **Invoice unavailable**, **Workspace not found** | Click **Contact support** | > [!NOTE] > > These banners are about your Popcorn plan and credits. WhatsApp's own message fees are billed by Meta. When Meta refuses payment for your WhatsApp account, Popcorn shows **Meta is refusing your WhatsApp messages** with **Open Meta billing** instead, emails the workspace's Owner and Admins, and holds campaigns and automatic messages until Meta accepts a payment again. Fix it in Meta billing, not here; see [Channels troubleshooting](/channels/troubleshooting). ## Related > **[Plans and credits](/billing/plans-and-credits)** > > Plans, what a credit is, and what uses credits. > **[Credit usage](/billing/credit-usage)** > > Where every credit went, and the CSV export. > **[Connect Zid](/integrations/zid)** > > Connecting a Zid store, including subscription through the Zid App Market. > **[Connect Salla](/integrations/salla)** > > Connecting a Salla store, including subscription through the Salla App Store. # Automated campaigns Source: https://docs.trypopcorn.ai/campaigns/automated-campaigns Send a WhatsApp template automatically when something happens in your Shopify, Salla or Zid store, such as an abandoned cart or a new order. An automated campaign watches your connected store for one event (an order is paid, a cart is abandoned, a shipment is created) and sends an approved WhatsApp template to the customer involved, either right away or after a wait you choose. Use it for abandoned-cart recovery, order confirmations, shipping updates and review requests. For a one-time send to a chosen audience, use a [campaign](/campaigns/send-a-campaign) instead. Automated campaigns are on the **Automated** tab of **Campaigns**. ## Before you start * A connected Shopify, Salla or Zid store. Without one the form says **Connect your store first** and offers **Connect a store**; see [Connect your store](/integrations/overview). * A connected WhatsApp number, and a template that belongs to that number. See [Templates](/campaigns/templates). * Credits. Automated campaigns cost 1 credit per 5 messages. A message is not sent when your balance is empty; see [Credits and failed messages](/campaigns/delivery-and-reachability#credits-and-failed-messages). ## Create an automated campaign On the **Automated** tab, click **Create campaign**. Everything is on one page, **New automated campaign**, with a live WhatsApp preview and your price beside it. **1. Trigger** Choose the **Store** (only connected stores are listed), then **When this happens**: the event that triggers the message. The events for each store are listed [below](#trigger-events-by-platform). If you change the store or the event later, conditions that no longer apply are removed and a notice says so. **2. Conditions** Optional. Without conditions the campaign sends every time the event happens. Click **Add condition**, then choose a **Field**, a **Comparison** and a **Value**. The comparisons are **equals**, **does not equal**, **contains**, **is greater than**, **is less than**, **is empty**, **is not empty**, **is one of** and **is not one of**. The message is sent only when every condition is met. To send only for some payment methods, pick the **Payment method** field and choose them from the list, up to 50. The list shows the methods enabled in your store, or the ones used on your recent orders, or the common ones for your platform. A method that isn't listed can be typed under **Add a payment method that isn't listed** and added with **Add**; capital letters don't matter. **3. Message** Choose the **WhatsApp number**, then the **Template**. Only templates for that number are shown, **Approved** ones and ones still in review. A template still in review shows "This template is still in review": Meta has to approve it before messages can be delivered, so choose an approved one to start sending right away. Changing the number clears the template, and says so. **New template** opens the template editor in a new tab. For every variable in the template, choose a field from the event (the customer's name, the order number, the total, the cart link) or **Custom value** to use the same text in every message. A variable that feeds a link button is marked **Used in a button link**, and **Link preview** shows where the button will go. The form refuses a choice that would break the link, such as a full checkout address placed after a domain the button already has. **4. Audience** Each message goes to the customer from the event, such as the one who placed the order or left the cart. **Send to unsubscribed customers** is off by default. Turn it on only for essential messages such as order confirmations or shipping updates; with it off, customers who have unsubscribed are skipped, including those who asked your agent to stop or tapped Stop in WhatsApp (see [Customers](/customers/overview#subscribed-and-unsubscribed)). **5. When** **Send** is **Right away** or **After a wait**. For a wait, enter the **Wait** time and choose a **Unit** of minutes, hours, days, weeks or months. The wait can be at most one year (525,600 minutes, 8,760 hours, 365 days, 52 weeks or 12 months). **6. Replies** **The agent answers replies** is on by default: when a customer replies, your agent answers. Turn it off to send replies to your team. **7. Name and launch** **Campaign name** is optional, and customers never see it. Leave it empty to use the suggested name. The **Cost** panel shows "1 credit per 5 messages" and **Credits left**; with none left it says "You're out of credits" and offers **Top up credits**. Click **Launch campaign** and confirm **Launch this campaign?** The campaign becomes **Active** and you see **Automated campaign launched**. If a field needs fixing, it is marked in place and the launch stops there. You can pause a launched campaign at any time. ## Trigger events by platform The list is fixed per platform. Names are as shown in the form. > **Shopify** > > | Event | Fires when | > | - | - | > | **Order Created** | a new order is created | > | **Order Paid** | an order is paid | > | **Order Updated** | an order is updated | > | **Order Edited** | an order is edited | > | **Order Fulfilled** | an order is fulfilled | > | **Order Partially Fulfilled** | part of an order is fulfilled | > | **Order Cancelled** | an order is cancelled | > | **Checkout Created** | a checkout is started (use this for abandoned-cart recovery) | > | **Checkout Updated** | checkout details change | > **Salla** > > Orders: **Order Created**, **Order Updated**, **Order Status Updated**, **Order Payment Updated**, **Order Products Updated**, **Order Coupon Updated**, **Order Total Price Updated**, **Order Shipping Address Updated**, **Order Customer Updated**, **Order Refunded**, **Order Cancelled**, **Order Deleted**, **Invoice Created**, **Review Added**. > > Carts: **Abandoned Cart**, **Abandoned Cart Updated**, **Coupon Applied**. > > Customers: **Customer Created**, **Customer Updated**. > > Shipments: **Order Shipment Creating**, **Order Shipment Created**, **Order Shipment Cancelled**, **Order Return Shipment Creating**, **Order Return Shipment Created**, **Order Return Shipment Cancelled**, **Shipment Creating**, **Shipment Created**, **Shipment Updated**, **Shipment Cancelled**. > **Zid** > > | Event | Fires when | > | - | - | > | **Order Created** | a new order is created | > | **Order Status Updated** | an order's status changes | > | **Order Payment Status Updated** | an order's payment status changes to paid or unpaid | > | **Abandoned Cart Created** | a shopping cart is abandoned | > | **Abandoned Cart Completed** | an abandoned cart is completed | > [!TIP] > > Events such as **Order Updated** or **Abandoned Cart Updated** can fire several times for the same order or cart. Add a condition (for example on the order status) if you only want one message per change. ## What happens when an event fires 1. Popcorn checks your conditions. If they do not match, nothing is sent and no credit is used. 2. The recipient's phone number is taken from the event. If the event carries no valid phone number, it is skipped. If the number is not in **Customers** yet, a customer is created. 3. The message is sent right away, or queued as a scheduled message when you set a wait. Scheduled messages are counted on the campaign page. 4. Right before sending, Popcorn checks that the phone number is valid, that the customer is subscribed (unless **Send to unsubscribed customers** is on), that the customer is reachable (marketing templates only; see [unreachable contacts](/campaigns/delivery-and-reachability#unreachable-contacts)), and that you have credits. 5. The message is sent and a conversation opens in the Inbox. With **The agent answers replies** on, your agent handles the reply. A single campaign handles at most 100 events a minute; extra events in that minute are dropped. While Meta refuses payment for your WhatsApp Business account, messages Meta refuses are not dropped: they wait and are tried again every hour, and go out by themselves once the payment problem is fixed. See [When Meta refuses payment](/campaigns/delivery-and-reachability#when-meta-refuses-payment). ### Abandoned-cart messages are skipped after a purchase For campaigns with a wait that are triggered by a cart or checkout event, Popcorn asks your store right before sending whether the customer has ordered since the cart was abandoned. If they have, the recovery message is not sent. If the store cannot answer in time, the message is sent anyway rather than dropped. Messages sent right away are not checked, and campaigns triggered by completion events, such as Zid's **Abandoned Cart Completed**, are never held back. ## The campaign list The list has the filters **All**, **Active**, **Paused** and **Draft**, **Search campaigns**, and these columns: | Column | What it shows | | - | - | | **Campaign** | The name, with the event that triggers it. | | **Status** | **Active**, **Paused**, **Draft**, **Inactive** or **Failed**. | | **Delivery timing** | **Right away**, or the wait, such as "1 hour after the event". | | **Last triggered** | When an event last arrived. | | **Triggers** | How many events arrived. | | **Messages sent** | How many messages went out. | | **Success rate** | The share delivered, or "No sends yet". | ## Pause, resume and status Open a campaign and click **Pause campaign** to stop it, or **Activate campaign** to resume. A paused campaign receives no events, and nothing is sent. When no messages are waiting, it pauses at once and a notice offers **Undo** to switch it back on. > [!WARNING] > > Pausing cancels the campaign's scheduled messages for good. When some are waiting, the dialog **Pause and cancel scheduled messages?** says how many, and those customers will not receive the message when you resume. Confirm with **Pause and cancel messages**. Messages already handed to WhatsApp that are waiting for an automatic retry are not affected. ## Results and why messages were not sent Open a campaign to see, under its name, the number it sends from ("Sending from" the number), the event and the delivery timing. If that number is no longer connected, it reads "The assigned number is no longer available". The page shows **Times triggered**, **Sent**, **Delivered**, **Read**, **Clicks** (each with its rate), **Unsubscribed** ("Opted out after this campaign"; see [Unsubscribes](/campaigns/delivery-and-reachability#unsubscribes)), **Scheduled messages**, **Couldn't deliver** and **Credits used**. **Export** downloads contacts as an Excel file: **Delivered**, **Read**, **Couldn't deliver**, **Unsubscribed** or **All recipients**. Below them, **Details**, **Trigger**, **Conditions**, **Message** and **Settings** show every choice you made, including **Delivery timing**, **Recipients** and whether it sends to unsubscribed customers. What each delivery status means is explained in [Delivery and reachability](/campaigns/delivery-and-reachability). Click **Couldn't deliver** to open **Why some messages didn't deliver**. Besides the WhatsApp failure causes, automated campaigns have two reasons where the message never left Popcorn: | Reason | What it means | What to do | | - | - | - | | **Not sent: out of credits** | The event fired and the customer was eligible, but your balance was empty. No credit was charged. | Top up under **Plan and billing**. These events are not retried, and the customers were never contacted. | | **Not sent: no WhatsApp sender connected** | The campaign had no live WhatsApp sender when the event fired. This came from an older version of Popcorn and stopped on 12 July 2026. | Nothing; it is history. | **Show contacts** and **Export all** give you the affected phone numbers. ## Credits * Automated campaigns are charged 1 credit per 5 messages, deducted after each successful send. Failed sends are not charged. * Nothing is reserved at launch. Each message checks your balance right before it goes out, so keep the balance topped up in busy periods. See [Top-ups and renewal](/billing/top-ups-and-renewal). * Automatic retries of a message that hit a temporary WhatsApp error reuse the original charge, so they are never billed twice. ## Related * [Delivery and reachability](/campaigns/delivery-and-reachability) * [Campaign troubleshooting](/campaigns/troubleshooting) * [Credit usage](/billing/credit-usage) # Delivery and reachability Source: https://docs.trypopcorn.ai/campaigns/delivery-and-reachability What campaign message statuses mean, how daily limits, retries and Meta payment problems affect sending, and why some contacts stop getting campaigns. After you launch a campaign, every recipient moves through WhatsApp's delivery statuses, and some messages fail for reasons on Meta's side. This page explains what you see on the campaign page, what Popcorn does about temporary failures, and how it protects your account from sending to numbers that cannot be reached. It applies to both [campaigns](/campaigns/send-a-campaign) and [automated campaigns](/campaigns/automated-campaigns). ## Message statuses The campaign page shows a card for each status and a **Recipients** table you can filter with its **Status** selector: **All recipients**, **Sent**, **Delivered**, **Queued**, **Couldn't deliver**, **Retrying** and, on a stopped campaign, **Not sent**. | Status | Meaning | | - | - | | **Queued** | Not sent yet. The message is waiting its turn, waiting for working hours, or waiting for your daily limit to free up. | | **Sent** | WhatsApp accepted the message. It has left Popcorn but has not necessarily reached the phone. | | **Delivered** | WhatsApp confirmed the message reached the customer's phone. Read messages count as delivered too. | | **Read** | The customer opened the message. | | **Couldn't deliver** | The message failed and will not be retried. Click **See why** on the card for the breakdown. | | **Retrying** | WhatsApp returned a temporary error and Popcorn has scheduled another attempt. The table shows **Attempts**, **Next retry** and the **Reason**. | | **Not sent** | You stopped the campaign before this message went out, so it was cancelled. | The campaign list shows a **Delivery rate**, which is delivered ÷ sent, and a **Read rate**, which is read ÷ delivered. A status only ever moves forward: a late "sent" update never overwrites a "delivered" one. ## WhatsApp daily limits Meta gives each WhatsApp business portfolio a limit on how many different customers you can start conversations with in a rolling 24-hour window: 250, 1,000, 2,000, 10,000, 100,000 or unlimited. Popcorn reads the limit from Meta and refreshes it daily. You can see it in the **Message limit** column under **Integrations → WhatsApp → Account**, and beside each number in the campaign form. It shows **Syncing with Meta** right after connecting, or **Limit unavailable** if Meta could not be reached. How the limit affects campaigns: * Popcorn keeps 10% of the limit free for one-to-one messages and uses the remaining 90% for campaigns. * When your audience is larger than that, the **When** panel of the campaign form says the campaign exceeds the daily WhatsApp limit and roughly how many days it will take. Messages beyond the limit stay **Queued** and go out as the window frees up. The campaign keeps running until everyone has been messaged. * If the limit has not synced yet, sending waits for up to an hour. If Meta still has not returned a limit after that, the remaining messages are marked as failed rather than sent blind. Fix the connection under **Integrations** and see [Channel troubleshooting](/channels/troubleshooting). * A campaign cannot start, resume or retry while its sender needs attention, for example a number that needs to be reconnected. Reconnect it, or choose another number. ## Why messages fail Click **Couldn't deliver** to open **Why some messages didn't deliver**: "Messages that didn't reach customers, grouped by cause." It shows the totals for **Couldn't deliver** and **Recipients**, and each group has an explanation, steps to take and the error code. Groups that need you to act are tagged **Needs you**. **Show contacts** lists the affected customers, and **Export all** downloads them. | Category | Typical cause | Retried automatically? | | - | - | - | | **Marketing message limits** | The customer has already received as many marketing messages from all businesses as WhatsApp allows, or their number is in a Meta test group. Try again in 12 to 48 hours, or use a utility template if the message is urgent. | Yes | | **Contact issues** | The number is not registered on WhatsApp, cannot receive messages, or the customer blocked marketing messages from your business. Remove these contacts from the audience. | No | | **Sending limits** | Your account hit its hourly or daily sending limit, or was restricted after spam reports. Wait 1 to 4 hours and spread future campaigns out. | Yes | | **Payment issues** | Meta refused the messages because of a payment problem on your WhatsApp Business account. Check the account's payment method in Meta billing, pay any balance due, or replace an expired card. See [When Meta refuses payment](#when-meta-refuses-payment). | Yes, every hour while it lasts | | **Template setup errors** | The template expected a different number of variables than the campaign supplied, or WhatsApp paused or disabled the template for low quality. A paused template resumes by itself; a disabled one needs a new template. | Only a paused template | | **Temporary WhatsApp errors** | An internal error on WhatsApp's side, usually temporary. Try again in 1 to 2 hours. | No | Automated campaigns add two "not sent" reasons for events that never produced a message; see [Automated campaigns](/campaigns/automated-campaigns#results-and-why-messages-were-not-sent). For one-to-one messages in the Inbox, a failed message shows the Meta error number with a short explanation and what you can do. ## Automatic retries Some Meta errors are temporary: the per-user marketing limit, "sending too quickly", a spam-rate restriction, a Meta experiment on the recipient's number, a per-recipient rate limit, a temporarily locked account, a paused template, or a payment problem on your WhatsApp Business account. When WhatsApp rejects a message with one of these, Popcorn marks the recipient **Retrying** and tries again, up to four times: * Per-user marketing limit: once a day, up to four days. * Paused template: after 4 hours, 4 hours, 24 hours and 24 hours. * Payment problem: every hour. While Meta keeps refusing payment, waiting messages don't use up these attempts; see [When Meta refuses payment](#when-meta-refuses-payment). * Other temporary errors: after 1 hour, then 24, 48 and 72 hours. Retries send the same message with the original content, and they are never charged a second time. A message that WhatsApp already accepted is never sent again, even if Popcorn lost the confirmation. Retries follow the campaign's state: * **Paused**: the retry waits and checks every hour. If the campaign stays paused for seven days, the retry gives up and the recipient is marked as failed. * **Stopped** or **Completed**: outstanding retries are cancelled. Permanent errors (unknown number, opt-out, template mismatch) are never retried. ## Paused templates WhatsApp pauses a template when too many recipients block or report it: for 3 hours the first time and 6 hours the second, after which it resumes by itself. A third time, it disables the template for good. While a template is **Paused**, a campaign does not send it. Popcorn holds those messages and checks again every hour, up to 8 times, so the pause can run its course. A message that still hits the pause after that goes to the retry schedule above. A **Disabled** template cannot be sent at all: switch the campaign to another template. See [Templates](/campaigns/templates#statuses). ## When Meta refuses payment If your WhatsApp Business account has a payment problem in Meta billing, Meta refuses every message it would charge you for. From the first refused message, Popcorn holds campaign and automated campaign messages from every number on that account instead of letting them fail: * A one-time campaign keeps its unsent messages **Queued**, and messages Meta already refused show **Retrying**. Popcorn looks again every hour, and a held message keeps its retry attempts. * Each hour, one message per WhatsApp Business account goes to Meta as a check. Once Meta accepts and bills a message again, the waiting messages go out on their next hourly look. You don't need to resume anything. * Messages are held for up to seven days after the problem began. After that they go to Meta again, and messages Meta still refuses end in **Couldn't deliver** under **Payment issues**. Popcorn also shows **Meta is refusing your WhatsApp messages** with **Open Meta billing**, and the number's status reads **Meta payment problem**. Fix the payment method or pay the balance there; see [Channel troubleshooting](/channels/troubleshooting). ## Unreachable contacts If WhatsApp reports "message undeliverable" for the same customer on two marketing messages in a row, Popcorn stops including that customer in marketing campaigns. Sending to numbers WhatsApp cannot reach wastes credits and hurts your number's quality rating. What happens: * The customer's profile under **Customers** shows the banner **Campaigns are paused for this customer**. * The audience count, the credit estimate and the launch audience of campaigns that use a **Marketing** template leave the customer out. * Automated campaigns with a Marketing template skip the customer. Utility and Authentication templates still go through. * One-to-one conversations in the Inbox are not affected. The pause lifts by itself when the customer sends you a WhatsApp message, or when you change their phone number. To lift it yourself, open the customer's profile and click **Re-enable campaigns**; the banner goes away and the customer is back in your audiences immediately. A successful delivery in between resets the failure count, so two undeliverable failures separated by a delivered message do not pause the contact. ## Unsubscribes A customer unsubscribes from your campaigns by asking your agent to stop (with **Let customers opt out** on) or by tapping Stop on your marketing messages in WhatsApp. Popcorn counts it against the last campaign message the customer received in the 7 days before, on that campaign's **Unsubscribed** figure. Each customer counts once per campaign, and an opt-out with no campaign message in the week before counts against no campaign. A customer who comes back later stays counted. If WhatsApp refuses a marketing message because the customer had already tapped Stop, Popcorn marks them unsubscribed too, without counting it against the campaign. What else changes for an unsubscribed customer is on [Customers](/customers/overview#subscribed-and-unsubscribed). ## Credits and failed messages * **One-time campaigns** reserve credits when you send or schedule: 1 credit per 10 recipients, rounded up, based on the contacts matching your conditions at that moment, with unreachable contacts left out for Marketing templates. When the campaign is stopped or completes, credits for recipients who were never sent a message are returned to your balance. * **Automated campaigns** do not reserve. Each message costs 1 credit per 5 messages, checked and charged as it is sent. If the balance is empty the message is not sent and the event is not retried. * **Credits used** counts credits for delivered messages. Failed messages are not charged, and a retry reuses the original charge. You can see every reservation, deduction and refund by campaign name under **Plan and billing → Credit usage**; see [Credit usage](/billing/credit-usage). ## Related * [Campaign troubleshooting](/campaigns/troubleshooting) * [Send a campaign](/campaigns/send-a-campaign) * [Customers](/customers/overview) # Link buttons and tracking Source: https://docs.trypopcorn.ai/campaigns/link-buttons-and-tracking Set up Open a link buttons with a fixed, personalised, or complete-link destination, and see how Popcorn tracks and reports clicks. An **Open a link** button sends the customer to a web page when they tap it. Popcorn wraps every link button in a tracking link, so you can see who clicked, and lets you personalise the destination per customer, for example a link straight to their own cart. This page covers the three destination types, how clicks are counted, and what happens when a customer taps. ## Before you start * You add link buttons in the template editor: **Add buttons**, then **Open a link**. See [Templates](/campaigns/templates). * Links must start with `https://`. A template can have up to 2 link buttons, each with a label of up to 25 characters. * The **Their cart or checkout** option needs a connected Zid or Shopify store. See [Integrations](/integrations/overview). ## Choose where the button goes When you add an **Open a link** button, answer **Where should this button go?** | Option | When to use it | What you enter | | - | - | - | | **A fixed web address** | Everyone should land on the same page: a sale page, your homepage, a form. | **Web address**, for example `https://yourstore.com/sale`. | | **Their cart or checkout** | Each customer should open their own cart, checkout or order page. Used with automated campaigns such as abandoned cart. | Nothing. Each customer gets their own complete link automatically. | | **Your link + each customer's ID** | You have a page on your own site that takes an identifier at the end, such as an order or booking number. | **Your web address**, for example `https://yourstore.com/orders`. Popcorn adds each customer's value to the end; no brackets needed. | The editor shows **Opens:** with a preview of the final address. You never type a `{{1}}` placeholder yourself; Popcorn builds it from your choice. Three examples of what a customer ends up opening: | Option | You enter | Value at send time | Customer opens | | - | - | - | - | | **A fixed web address** | `https://yourstore.com/sale` | none | `https://yourstore.com/sale` | | **Your link + each customer's ID** | `https://yourstore.com/orders` | `10234` | `https://yourstore.com/orders/10234` | | **Their cart or checkout** | nothing | the customer's checkout link from your store | that checkout link | If **Their cart or checkout** is greyed out and reads "(connect your store first)", no Zid or Shopify store is connected. Salla stores cannot use this option; use a fixed address or your own link with an ID instead. > [!NOTE] > > Carousel card links are always fixed addresses: each card gets its own **Web address**. ## Where the value comes from For **Their cart or checkout** and **Your link + each customer's ID**, something has to supply the per-customer value at send time. * **One-time campaigns.** In the **Message** panel, a field named **Button link** followed by the button's label appears under the variables. For an ID-style button, enter only the value that goes on the end ("Enter only the parameter value"); the hint says what it replaces in the template URL. For a link with no variable part, the hint reads "This link has no variable part." and you enter nothing more. You cannot send while a link button's value is missing: "Enter the value for this link." See [Send a campaign](/campaigns/send-a-campaign). * **Automated campaigns.** The value comes from the store event, for example the cart's checkout link. In the **Message** panel, the variable is marked **Used in a button link** and **Link preview** shows where the button will go. See [Automated campaigns](/campaigns/automated-campaigns). ## How tracking works When you submit a template, Popcorn replaces each link button's address with a tracking link on `api.trypopcorn.ai/link/…`. Meta reviews and approves the template with that link in it, which is why you may see it in Meta Business Manager instead of your own address. When a customer taps the button: 1. Popcorn records the click against the campaign and against the recipient the message was sent to, carousel card links included. 2. The customer is redirected to the real destination. Clicks are counted for link buttons only. **Call us**, **Quick reply** and **Copy a code** buttons are not tracked. ## Where clicks appear * On the campaign page, **Clicks** counts recipients who tapped a link button at least once. A customer who taps twice counts once. * In the **Recipients** table, the **Clicks** column shows the number of taps for each contact. Click counts are available for both one-time and automated campaigns. Links in messages sent before 19 October 2026 did not always identify the recipient, so campaigns sent before then can show fewer clicks than customers made. ## What the customer sees In WhatsApp the button shows your label. Tapping it opens the customer's browser, passes through the tracking link, and lands on the destination. If the destination cannot be resolved, the browser shows **Not Found.** instead of your page; the reasons are below. ## When a link shows Not Found. Popcorn refuses to redirect rather than send a customer somewhere unexpected. A tap ends on **Not Found.** when: * The per-customer value was missing or empty when the message was sent, or was longer than 2,048 characters. * For **Your link + each customer's ID**, the value would change the domain of your address. The value can only fill in the part after your domain. * For **Their cart or checkout**, the link points at a domain that is not your connected store. Popcorn checks the destination against your store's own web address (your Zid store URL, or your Shopify store's `myshopify.com` address and primary domain). If you move your store to a new domain, submit a new template so the check uses the new address. * The tracking link is not one Popcorn recognises, for example because it was edited or shortened before being shared. > [!TIP] > > Send the campaign to yourself first with a small test audience, for example one **Phone number** condition with **Equals**, and tap the button on your phone before sending to everyone. ## Related * [Templates](/campaigns/templates) for button limits and the rest of the editor. * [Send a campaign](/campaigns/send-a-campaign) for the **Message** panel and the **Clicks** stat. * [Troubleshooting](/campaigns/troubleshooting) for links that do not track. # Campaigns overview Source: https://docs.trypopcorn.ai/campaigns/overview How WhatsApp campaigns work in Popcorn: templates, Meta approval, credits, who gets messaged, working hours, and where to read results. Campaigns send an approved WhatsApp template to your customers: a sale announcement, a restock, a seasonal offer. A one-time campaign goes to an audience you build and sends once. An automated campaign sends one message at a time, whenever an event happens in your store, such as an abandoned cart. **Campaigns** in the sidebar holds all three parts, as tabs under the page title: **One-time**, **Automated** and **Templates**. This page explains what every campaign depends on. For the step-by-step form, see [Send a campaign](/campaigns/send-a-campaign). ## Before you start * A connected WhatsApp Business number. Without one, opening **Campaigns** shows **Connect WhatsApp to continue** with a **Connect WhatsApp** button. See [Connect WhatsApp](/channels/whatsapp). * At least one template that Meta has approved for the number you want to send from. See [Templates](/campaigns/templates). * Credits. Popcorn reserves credits when you launch a one-time campaign. See [Plans and credits](/billing/plans-and-credits). ## One-time and automated campaigns | | One-time | Automated | | - | - | - | | Who receives it | An audience you build with conditions | The customer in the store event | | When it sends | **Now**, or at a time you schedule | Every time the event happens while the campaign is **Active** | | Cost | 1 credit per 10 messages | 1 credit per 5 messages | | Needs | An approved template and a WhatsApp number | A template, a WhatsApp number and a connected store | | Read more | [Send a campaign](/campaigns/send-a-campaign) | [Automated campaigns](/campaigns/automated-campaigns) | ## Templates and Meta approval WhatsApp only lets a business start a conversation with a pre-approved message, so every campaign is built on a template. You write it under **Campaigns → Templates**, submit it, and Meta reviews it. A one-time campaign lists only approved templates for the number you send from. * A template belongs to one WhatsApp number. A template made for one number is not offered when you send from another. * Meta may change a template's category during review, for example from **Utility** to **Marketing**. Popcorn then shows a **Reclassified** badge. The category affects what WhatsApp charges you and how the message is delivered. * Authentication templates, which send a one-time code to one customer, cannot be used in a bulk campaign. Send them from the Inbox or the API. Limits and statuses are on [Templates](/campaigns/templates). ## Credits and the cost estimate Campaign messages are paid for with Popcorn credits, separately from what Meta charges for WhatsApp conversations. * **Rate.** 1 credit per 10 one-time campaign messages, and 1 credit per 5 automated messages. * **Estimate.** In the campaign form, the **Estimate** panel shows **Recipients**, **Credits**, **Credits available** and **Credits left after**. If your balance is too low it says "You don't have enough credits to send this campaign." and offers **Top up credits**. If Popcorn can't read your balance it says "Couldn't check your available credits. This is an estimate." * **Reservation.** When you send or schedule, Popcorn counts the audience again on the server and reserves the credits. If your balance is too low the launch fails and nothing is sent. * **Refund.** When a campaign completes or you stop it, credits for messages that were never sent go back to your balance. **Credits used** on the campaign page counts delivered messages. Reservations and charges both appear under **Plan and billing → Credit usage**. See [Credit usage](/billing/credit-usage). ## Who receives a campaign Three things decide whether a contact is in your audience: 1. **Your conditions.** A new campaign starts with one condition, **Marketing subscription** **Is** **Subscribed**. You can add more, such as last seen, tags, order history or the recipients of an earlier campaign. The full list is on [Send a campaign](/campaigns/send-a-campaign#choose-the-audience). 2. **A phone number.** Contacts without a phone number are never messaged. 3. **Reachability.** For **Marketing** templates, customers who couldn't receive your last two marketing messages on WhatsApp are left out. Their profile in **Customers** shows the banner **Campaigns are paused for this customer**, and **Re-enable campaigns** puts them back. The audience count and the credit estimate already leave them out. See [Delivery and reachability](/campaigns/delivery-and-reachability). A customer opts out by asking your agent to stop (when **Let customers opt out** is on) or by tapping Stop on your marketing messages in WhatsApp. Either way they become unsubscribed, the default condition leaves them out, and automated campaigns skip them unless **Send to unsubscribed customers** is on. If your conditions let unsubscribed customers in, the campaign form warns you before you send. See [Customers](/customers/overview#subscribed-and-unsubscribed). ## Working hours If **Restrict to working hours** is on under **Settings → General → Working hours**, a one-time campaign launched outside the **Start** to **End** hours waits and starts at the next **Start**. The hours use your workspace time zone, which you change on **Profile**. When the setting is off, campaigns send at any time. Working hours apply to one-time campaigns only: automated campaigns send as soon as their event happens. See [Workspace settings](/settings/workspace). ## Daily sending limits Meta limits how many different customers your WhatsApp business account can start conversations with in 24 hours. The sender list in the campaign form shows each number's limit, for example "1,000 messages a day" or "Unlimited". If your audience is larger, the **When** panel says the campaign will be processed over several days, and Popcorn paces the sending. You do not need to split the campaign. See [Delivery and reachability](/campaigns/delivery-and-reachability#whatsapp-daily-limits). ## Where to see results The **One-time** tab lists every campaign with **Name**, **Status**, **Recipients**, **Delivery rate**, **Read rate** and **Created**. Filter by **All**, **Sending**, **Scheduled**, **Paused**, **Stopped**, **Completed** or **Draft**, or use **Search campaigns**. Delivery figures stay empty for drafts and scheduled campaigns. Open a campaign for **Recipients**, **Sent**, **Delivered**, **Read**, **Clicks**, **Unsubscribed**, **Credits used**, **Couldn't deliver** and **Retrying**, plus a table of every recipient you can export. **Unsubscribed** counts customers who opted out within a week of the campaign reaching them. Details are on [Send a campaign](/campaigns/send-a-campaign#read-the-results). Replies arrive in the Inbox like any other conversation. With **Your agent answers replies** on, your agent answers them. See [Inbox overview](/inbox/overview). ## Campaign statuses | Status | Meaning | | - | - | | **Draft** | Saved but not sent. You can edit or delete it. | | **Scheduled** | Waiting for its send time. Credits are reserved. | | **Sending** | Messages are going out. You can pause or stop it. | | **Paused** | Sending is on hold until you **Resume**. | | **Stopped** | You ended it. Messages not yet sent are cancelled for good. | | **Completed** | Every recipient has been processed. | ## Related > **[Templates](/campaigns/templates)** > > Build a template, submit it to Meta, and read its status. > **[Send a campaign](/campaigns/send-a-campaign)** > > The campaign form, scheduling, and the results page. > **[Automated campaigns](/campaigns/automated-campaigns)** > > Send a message when something happens in your store. > **[Troubleshooting](/campaigns/troubleshooting)** > > Rejected templates, campaigns that will not send, low delivery. # Send a campaign Source: https://docs.trypopcorn.ai/campaigns/send-a-campaign Send a one-time WhatsApp campaign: pick a template, fill its variables, build the audience, check the estimate, send or schedule, read results. A campaign sends one approved template to every contact that matches your conditions. You set it up on one page with four panels, **Message**, **Audience**, **When** and **Replies**, beside a live preview of the message and the credit **Estimate**. ## Before you start * A template that Meta has approved for the number you will send from. See [Templates](/campaigns/templates). * Enough credits: 1 credit per 10 recipients, reserved when you send or schedule. See [Campaigns overview](/campaigns/overview#credits-and-the-cost-estimate). * If **Restrict to working hours** is on under **Settings → General → Working hours**, a campaign sent outside those hours waits until the next **Start**. See [Workspace settings](/settings/workspace). ## Create and send **1. Start a campaign** Go to **Campaigns**, stay on the **One-time** tab, and click **New campaign**. Type a name where it says **Name this campaign**. If you leave it empty, Popcorn names the campaign with the date and time when you first save it. **2. Choose the message** In **Message**, pick **Send from**: the WhatsApp number that sends the campaign, with its daily limit beside it. Then open **Template** and choose a template. Only approved templates for that number are listed, and authentication templates are left out. Changing the number clears your template choice. If nothing is listed you see "No approved templates for this number"; **Create template** opens the template editor in a new tab. **3. Fill the variables** For every variable in the template, open its **Choose a value** list. Under **From the customer** you can pick the customer's first name, last name, phone number or email. Under **Same for everyone** you can pick one of the template's example values, or click **Add custom value**, type a fixed value and click **Add**. The preview updates as you choose. If the template has a link button, fill **Button link** for it. See [Link buttons and tracking](/campaigns/link-buttons-and-tracking). **4. Build the audience** In **Audience**, add conditions until "N customers match" shows the people you want. See [Choose the audience](#choose-the-audience). **5. Choose when to send** In **When**, set **Send** to **Now**, or to **Schedule** and pick a **Send date** and **Send time**. See [Scheduling rules](#scheduling-rules). **6. Decide who answers replies** In **Replies**, **Your agent answers replies** is on by default: when a customer replies to the campaign, your agent answers. Turn it off to leave replies in your inbox for your team. **7. Send** Check the **Estimate**, then click **Send campaign**, or **Schedule campaign** when you chose a time. A dialog asks "Send to N contacts?" or "Schedule for a date at a time?" and reminds you that every matching contact gets the template and credits are used for delivered messages. Confirm to go. If the audience includes customers who unsubscribed, the dialog warns you again and the button reads **Send anyway**. You see **Campaign launched** or **Campaign scheduled** and land on the campaign page. If the launch fails, the draft stays as it was and the error says why, for example that you need more credits. If a section is incomplete, Popcorn scrolls to it and says what is missing, such as "Choose a template to continue." or "Your audience must include at least one recipient." ## Save a draft Nothing saves on its own. Click **Save draft** (you see **Draft saved**) to keep your work and come back later. A saved campaign shows a **Draft** badge, and its **⋯** menu (**More actions**) has **Delete draft**. Open a draft from the **Draft** filter on the **One-time** tab. ## Choose the audience Every condition starts with **Where** (the first) or **And** (the rest), and all conditions must match. Click **Add condition** for another and **Remove condition** to drop one. The first condition is **Marketing subscription** **Is** **Subscribed**. **See who** opens **Matching contacts** with each **Customer** and **Phone number**, and **Load more** for the rest. The count follows your conditions and the template you chose. After a change, the send dialog's button waits until the new count is in. If counting fails, you see "Couldn't load matching contacts" and can't send until **Try again** succeeds. | Condition | What it matches | | - | - | | **Marketing subscription** | **Subscribed** or **Not subscribed**, with **Is** or **Is not**. | | **Last seen**, **Date added**, **Customer since**, **Last store order date**, **Conversation order date**, **Conversation date**, **Last conversation date** | Dates: **On**, **On or after**, **On or before** or **Between**. | | **Phone number**, **Email**, **First name**, **Last name** | Text: **Equals**, **Does not equal**, **Contains**, **Starts with** or **Ends with**. | | **Tags** | Contacts that carry a customer tag (**Contains**). | | **Conversation order count**, **Conversation order value** | Orders your agent took in conversations, with **Equals**, **Greater than**, **Greater than or equal to**, **Less than** or **Less than or equal to**. | | **Store platform**, **Lifetime store orders**, **Lifetime store spend** | Lifetime figures synced from your connected Shopify, Zid or Salla store. | | **Conversation count** | How many conversations the customer has had. | | **Activity in a previous campaign** | **Include** or **Exclude** the recipients of an earlier campaign (**Previous campaign**), optionally only those whose **Recipient status** is **All**, **Delivered**, **Read** or **Failed**. Use **Exclude** to avoid messaging the same people twice. | For **Marketing** templates, customers who couldn't receive your last two marketing messages on WhatsApp are left out, and contacts without a phone number are never messaged. See [Delivery and reachability](/campaigns/delivery-and-reachability#unreachable-contacts). ### Unsubscribed customers in the audience Only the **Marketing subscription** condition keeps unsubscribed customers out. If you remove or change it so that some match, the **Audience** panel shows a warning such as "12 customers here unsubscribed from your campaigns": "They asked not to get campaigns. Sending to them anyway can get your number reported and limited by WhatsApp." **Leave them out** adds **Marketing subscription** **Is** **Subscribed** back. If you send anyway, the send dialog repeats the warning and its button reads **Send anyway**. How customers unsubscribe is explained in [Customers](/customers/overview#subscribed-and-unsubscribed). ## Scheduling rules * The send time must be at least 5 minutes ahead and no more than 30 days ahead. * Times are in your workspace time zone, in one-hour slots. **Send time** names the zone. * Credits are reserved when you schedule, not when sending starts. Stopping a **Scheduled** campaign returns them. ## Daily limit and sender warnings If the audience is larger than the sender number's daily limit, **When** shows a banner saying the campaign will be processed over several days. Popcorn paces the messages to stay inside the limit. If Meta's limit can't be read, the number shows **Limit unavailable** and sending waits until it is known; right after connecting it reads **Syncing with Meta**. See [WhatsApp daily limits](/campaigns/delivery-and-reachability#whatsapp-daily-limits). A number that can't send shows **Needs reconnect** or **Reconnecting** in place of its limit, and can't be picked. A notice says why, for example "Reconnect needed for" the number or "Meta is checking" it, with a **Reconnect** link. A campaign cannot be sent, resumed or retried from such a number. Choose another number, or ask your account owner or an admin to reconnect it. A number whose customers' messages go to another app shows **Not receiving**. You can still send from it, but a notice says "Replies to" the number "go to another app": customers' replies reach that app, not your agent. **Open Meta Business Suite** and choose Popcorn AI in Conversation routing. See [Channel troubleshooting](/channels/troubleshooting). ## Read the results Click a launched campaign in the list to open its page, which refreshes on its own. The header shows the name, a status badge and "Sending from" the number with the recipient count. **Export**, **Pause**, **Stop** and **Resume** sit beside it. A paused or stopped campaign shows a banner, and a scheduled one shows "Scheduled for" its time. | Stat | Meaning | | - | - | | **Recipients** | Contacts in the audience when you sent. | | **Sent** | Accepted by WhatsApp, with its share of recipients. | | **Delivered** | Confirmed on the phone, with its share of sent. | | **Read** | Opened by the customer, with its share of delivered. | | **Clicks** | Recipients who tapped a link button at least once. | | **Unsubscribed** | Customers who unsubscribed within 7 days of this campaign reaching them, when it was the last campaign message they got. Click **See who** to list them. See [Unsubscribes](/campaigns/delivery-and-reachability#unsubscribes). | | **Credits used** | Credits charged for delivered messages. It reads **Not used yet** until sending starts. | | **Couldn't deliver** | Failed for good. Click **See why** to open **Why some messages didn't deliver**. | | **Retrying** | Failed with a temporary Meta error and will be tried again. Click **Show retries**. | Below the stats you see the template preview and **Audience criteria**, "Contacts who matched every condition below." ### The recipients table **Recipients** lists every contact with a **Status** selector: **All recipients**, **Sent**, **Delivered**, **Queued**, **Couldn't deliver**, **Retrying**, **Not sent** on a stopped campaign, and **Unsubscribed** once someone has unsubscribed after the campaign. The columns change with the choice: * **All recipients**: **Customer**, **Status**, **Clicks**, **Sent at**. * **Couldn't deliver**: **Reason** and **Sent at**. * **Queued**: **Sent**, **Queued** and **Created at**. * **Retrying**: **Attempts** ("1 of 4"), **Next retry** and **Reason**. * **Not sent**: "The campaign was stopped before this message was sent", and **Stopped at**. Click a row to open that customer's conversation in the Inbox. ### Export contacts **Export** offers "Download contacts as an Excel file" with **Delivered**, **Read**, **Couldn't deliver**, **Unsubscribed** and **All recipients**, each with its count. **Export this list** under the table exports the list you are looking at. The file has Name, Phone, Email, Status, the time of the last status change, and for failures the error code, error message and failure category. Headers follow your language and times follow your browser's time zone. There is no row limit, and up to three exports can run at once for a workspace. ### Why some messages didn't deliver Failures are grouped by cause, with an explanation and what to do. Each group can **Show contacts** and **Export all**, and the ones that need you are tagged **Needs you**. The causes are explained in [Delivery and reachability](/campaigns/delivery-and-reachability#why-messages-fail). ## Pause, resume, stop, delete | Action | Available when | Effect | | - | - | - | | **Pause** | **Sending** | Queued messages wait. Confirm with **Pause campaign**. | | **Resume** | **Paused** | Remaining messages continue. Confirm with **Resume campaign**. | | **Stop** | **Sending**, **Paused**, **Scheduled** | Messages not sent yet are cancelled and cannot be sent later. You can add a **Reason for stopping (optional)**. Confirm with **Stop campaign**. Credits for unsent messages are returned. | | **Delete** | **Draft** | Removes the draft. A launched campaign cannot be deleted. | After a stop, the cancelled recipients show as **Not sent**, and the export labels them "Not sent (campaign stopped)". ## Related * [Campaigns overview](/campaigns/overview) for credits, working hours and limits. * [Link buttons and tracking](/campaigns/link-buttons-and-tracking) for button values and click counts. * [Delivery and reachability](/campaigns/delivery-and-reachability) for statuses, retries and paused contacts. * [Troubleshooting](/campaigns/troubleshooting) if a campaign will not send. # Templates Source: https://docs.trypopcorn.ai/campaigns/templates Create a WhatsApp message template, add media, variables, buttons or a card carousel, submit it to Meta, and manage its status. A template is a pre-approved WhatsApp message. You need one to start a conversation with a customer who has not written to you in the last 24 hours, which is what every campaign does. Templates live on the **Templates** tab of **Campaigns**; the same list feeds one-time campaigns, automated campaigns and the Inbox. ## Before you start * A connected WhatsApp Business number. A template belongs to one number; if you have several, you pick which one in **Setup**. * Permission to create templates in your [role](/settings/team-and-roles). * Any media you want in the header or carousel cards: JPEG or PNG images, MP4 video, or a PDF, each at most 5 MB. ## Create a template **1. Open the editor** Go to **Campaigns**, open the **Templates** tab and click **New template**. **2. Answer What are you sending?** Pick the purpose that fits best: **Order confirmation**, **Shipping update**, **Receipt or invoice**, **Appointment reminder**, **Customer support reply**, **Promo or offer**, **Welcome message**, **Abandoned cart**, **Feedback request**, **OTP / verification code** or **Something else**. The purpose sets the category, where the template shows and a starting name. You can change all three afterwards; **Change** next to the purpose lets you pick again. **3. Check Setup** In the **Setup** card: * **Internal name** accepts letters, numbers and underscores only. If you type anything else the field shows "Will be saved as" and the converted name. Customers never see this name. * **Send from** is the WhatsApp number. Once the template exists, it is locked: "A template stays on the number it was made on." * **Category** and **Language**. * **Where you'll use it**: **Inbox replies**, **Campaigns**, or both. **4. Write the message** In **Message**, type the body in **Enter message body** (up to 1,024 characters). Use the toolbar for bold, italic and strikethrough, and **Add variable** to insert a placeholder. For a head start, use **Draft with agent**, described below. **5. Add optional parts** Use **Add header**, **Add footer**, **Add buttons** or **Add carousel**. Each is described below, and **Remove header**, **Remove footer**, **Remove buttons** or **Remove carousel** takes it away again. **6. Save or submit** **Save as draft** keeps the template in Popcorn only. **Submit for review** asks you to confirm: WhatsApp reviews the template before you can send it, and after you submit you can't edit it. **Keep editing** takes you back. The checklist beside the form reads **Ready to submit**; otherwise it counts the things to fix and says what they are. > [!TIP] > > The preview beside the form shows the message as customers will see it, and updates as you type. When a step changes a lot at once, such as using an agent draft, **Undo** appears so you can reverse it. ## Draft with the agent Under **Need a starting point?** describe the template you want and click **Generate**. If the agent needs more, it asks **A couple of details first**, and you click **Continue**. When **Draft ready** appears, **Use this draft** fills in the form and **Start over** discards it. The draft can suggest a different category or language; the notes read "Changes the category to" and "Changes the language to". If your content looks likely to be moved to another category by WhatsApp, the helper warns you before you submit. ## Variables and example values Variables are numbered placeholders such as `{{1}}` and `{{2}}`. When you send a campaign, you map each one to a customer field or a fixed value. Meta's rules, which the editor checks as you type: * Number them 1, 2, 3 in order with no gaps. Named placeholders such as `{{name}}` are not accepted. * The body cannot start or end with a variable, two variables cannot sit next to each other, and the body cannot be only a variable. * Up to 10 variables in the body. * Every variable needs a value in **Example values for variables**, so Meta's reviewers can read the message. * A text header can hold at most one variable, and it must be `{{1}}`. The footer and carousel card text cannot contain variables. ## Header, footer and buttons **Header**: click **Add header** and answer "What kind of header?" with **Image**, **Video**, **Document** or **Bold title**. A bold title is text of up to 60 characters, with no line breaks and no emoji. Media is uploaded from your computer, 5 MB at most. **Footer**: **Add footer** gives a short note of up to 60 characters, with no variables and no line breaks. **Buttons**: **Add buttons** asks "What should this button do?", then **Add another button** adds more. | Button | What you enter | Rules | | - | - | - | | **Open a link** | A label and where it goes | Up to 2 per template. Links must start with `https://`. See [Link buttons and tracking](/campaigns/link-buttons-and-tracking) for the destination types. | | **Call us** | A label and a phone number | 1 per template. International format, for example `+966501234567`. | | **Quick reply** | A label | The customer taps it to reply with that text. | | **Copy a code** | A **Code**, such as a coupon | 1 per template. Up to 15 characters: letters, numbers, hyphens and underscores. WhatsApp sets the button label and translates it, so you can't edit it. | Labels are limited to 25 characters and cannot contain emoji or line breaks. A template can have up to 10 buttons in total. ## Card carousels A carousel is a message followed by 2 to 10 swipeable cards, each with its own image or video. Click **Add carousel**. A carousel template is the body plus cards only, so the editor hides the header, footer and top-level buttons. * **Card media** is **Image** or **Video**, and every card uses the same format. Switching the format clears the media on all cards, and **Undo** brings it back. * **Card buttons**: WhatsApp shows the same buttons on every card. Click **Add a button to every card**, choose **Open a link**, **Call us** or **Quick reply** (up to 2 per card), and set its label once. Then give each card its own link or phone number. * **Card text (optional)** is up to 160 characters. If one card has text, every card needs text. * **Add card** and **Remove card** change the count, and **Remove carousel** returns to a normal template. Card links are tracked the same way as top-level link buttons, and are always fixed web addresses. ## Authentication templates For **OTP / verification code**, WhatsApp writes the message for you: a standard verification text in the template's language with the code and a copy button. There is nothing to type. Choose: * **Security reminder**, which adds "For your security, do not share this code." * **Show when the code expires**, with **Code expires after (minutes)**, a whole number from 1 to 90 (10 by default). * **Copy button label (optional)**. Leave it empty to use WhatsApp's own label. Authentication templates send a one-time code to one customer at a time, so they cannot be used in a bulk campaign. Send them from the Inbox or the API. ## Category **Marketing**, **Utility** and **Authentication** are Meta's categories. Meta reviews the category during approval and may change it: the editor then shows "Meta reclassified this template from" the old category "to" the new one, and the list shows a **Reclassified** badge. A reclassified template still works, but delivery and WhatsApp pricing follow the new category. If you need the original category, create a new template whose content matches it. ## Statuses Use the status filter above the list to find templates by status: **All**, **Draft**, **Pending review**, **Approved**, **Rejected**, **Paused**, **Disabled** or **Flagged**. **Search templates** narrows the list further. | Status | Meaning | | - | - | | **Draft** | Saved in Popcorn only. You can edit it. | | **Pending review** | Submitted and waiting for Meta. | | **Approved** | You can use it in campaigns and the Inbox. | | **Rejected** | Meta declined it. Duplicate it, fix the content, and submit the copy. | | **Paused** | Meta paused it, usually for low quality. Campaign messages wait and try again; see [Delivery and reachability](/campaigns/delivery-and-reachability#paused-templates). | | **Disabled** | Meta turned it off. It cannot be sent. | | **Flagged** | Meta flagged the template, or reported a status Popcorn doesn't list. | The list shows **Template**, **Category**, **Updated** and **Status**. Status changes arrive from Meta automatically; you do not need to refresh anything. ## Edit, duplicate, delete * Only a **Draft** can be edited. Once submitted, the page says "This template is" followed by its status "and can't be edited", and "To make changes, duplicate this template and submit the copy." Click **Duplicate** to get an editable draft copy. **Duplicate** is also in a row's **⋯** menu. * **Delete** asks you to confirm with **Delete template**. It removes the template from Popcorn, and for a template you already submitted, from WhatsApp too. It cannot be undone. ## Related * [Send a campaign](/campaigns/send-a-campaign) to use an approved template. * [Link buttons and tracking](/campaigns/link-buttons-and-tracking) for personalised links and click counts. * [Troubleshooting](/campaigns/troubleshooting) if a template is rejected or paused. # Campaign troubleshooting Source: https://docs.trypopcorn.ai/campaigns/troubleshooting Fix common campaign problems: rejected templates, campaigns that will not send, low delivery, repeated messages, wrong values, untracked links. Most campaign problems fall into a handful of causes, and the app usually names the cause somewhere: on the template, in the campaign form, on the campaign page, or in **Why some messages didn't deliver**. Find your symptom below. ## The template was rejected, paused or disabled On the **Templates** tab of **Campaigns**, each template shows a status: **Draft**, **Pending review**, **Approved**, **Rejected**, **Paused**, **Disabled** or **Flagged**. Popcorn updates the status as soon as Meta reports a change. A one-time campaign can only use **Approved** templates. An automated campaign also lists templates still in review, but Meta has to approve them before messages can be delivered. * **Rejected**: Meta refused the template. A template that has been submitted can no longer be edited (the page says "This template is rejected and can't be edited"). Click **Duplicate** to create an editable copy, fix the content against the rules the editor checks, and click **Submit for review**. * **Paused**: WhatsApp paused the template for low quality, for 3 hours the first time and 6 hours the second. Messages wait and are tried again once it resumes; see [paused templates](/campaigns/delivery-and-reachability#paused-templates). To avoid a third pause, send only to customers who want your messages. * **Disabled**: Meta turned the template off. Duplicate it, revise it, submit the copy, then switch your campaigns to the new template. * **Flagged**: Meta flagged the template. Wait for the status to change, or duplicate it and submit the copy. * Meta may also reclassify a template's category after approval; the template page shows "Meta reclassified this template from" the old category "to" the new one. That changes how it is priced and delivered, and a template that became **Marketing** is now subject to per-user marketing limits and to [unreachable-contact exclusion](/campaigns/delivery-and-reachability#unreachable-contacts). See [Templates](/campaigns/templates) for what the editor checks before you submit. ## The campaign is not sending Check the campaign's status first: **Draft** campaigns have not been sent, **Scheduled** ones wait for their time, and **Paused** ones stop until you click **Resume**. > **Not enough credits** > > The **Estimate** panel shows **Recipients**, **Credits**, **Credits available** and **Credits left after**. If it says "You don't have enough credits to send this campaign.", the launch is blocked until you click **Top up credits**; see [Top-ups and renewal](/billing/top-ups-and-renewal). If it says "Couldn't check your available credits. This is an estimate.", the number is an estimate and the exact charge is checked again when you click **Send campaign** or **Schedule campaign**. > **Outside working hours** > > If **Restrict to working hours** is on under **Settings → General → Working hours**, a campaign sent outside the **Start** and **End** hours is held as **Queued** until the next start time, in your workspace time zone (change it on **Profile**). Turn the restriction off, adjust the hours, or wait. Automated campaigns are not affected by working hours. > **Scheduled time was refused** > > A scheduled campaign must start at least 5 minutes in the future and no more than 30 days ahead. The form says "Pick a time at least 5 minutes in the future." or "Campaigns can only be scheduled up to 30 days in advance." Pick another **Send date** and **Send time**. > **The sender needs attention** > > A campaign cannot be sent, resumed or retried from a WhatsApp number that cannot send. The **Send from** list says why, for example "Reconnect needed for" the number, or "Meta is checking" it, which usually takes a few minutes. Click **Reconnect**, or ask your account owner or an admin to. You can also choose another number. > **Meta is refusing payment** > > If Popcorn shows **Meta is refusing your WhatsApp messages** and the number reads **Meta payment problem**, Meta refuses your messages because of a payment problem on your WhatsApp Business account. Campaign messages wait as **Queued** or **Retrying** instead of failing. Click **Open Meta billing**, then pay any balance due or replace an expired card. Once Meta bills a message again, the waiting messages go out within about an hour, without you resuming anything. See [When Meta refuses payment](/campaigns/delivery-and-reachability#when-meta-refuses-payment). > **No template available for the number** > > Templates belong to one WhatsApp number. Choose **Send from** first; only that number's approved templates appear. If a draft says the template is no longer approved for the number, choose another one. If the number was disconnected after launch, recipients fail with "Campaign template or sender is no longer active for this organization"; reconnect the number under **Integrations → WhatsApp** and create a new campaign. > **Messages stay Queued for a long time** > > Large audiences are sent within your WhatsApp daily limit and can take several days; the **When** panel warned you about this. Right after connecting a number, sending also waits until the limit has synced from Meta (**Message limit** under **Integrations → WhatsApp → Account** shows **Syncing with Meta**). See [WhatsApp daily limits](/campaigns/delivery-and-reachability#whatsapp-daily-limits). > **An authentication template was chosen** > > Authentication templates send a one-time code to one customer at a time, so they can't be used in bulk campaigns or scheduled launches. Send them from the Inbox or the API, and pick a **Marketing** or **Utility** template for the campaign. ### An automated campaign does not fire * The campaign must be **Active**. A **Paused** campaign receives no events; click **Activate campaign**. * The store must still be connected under **Integrations**. If you reconnected the store, active campaigns re-register with it automatically; if events still do not arrive, pause and activate the campaign again. * The event must contain a valid phone number for the customer. Events without one, for example a checkout where the customer has not typed a phone yet, are skipped. * Your conditions must all be met. Check them under **Conditions** on the campaign page. If you changed the store or the event while creating the campaign, conditions that did not apply were removed. * The customer must be subscribed, unless **Send to unsubscribed customers** is on, and must not be paused (**Campaigns are paused for this customer**; Marketing templates only). * You need credits. Events that arrive while your balance is empty appear as **Not sent: out of credits** and are not retried. * A single campaign handles at most 100 events a minute; extra events in that minute are dropped. ## Low delivery or read rates Open **Why some messages didn't deliver** on the campaign page. The category tells you what to change: | What you see | What to do | | - | - | | **Marketing message limits** | WhatsApp caps marketing messages per person across all businesses. Popcorn retries these over the following days. For order updates and shipping notices, use a **Utility** template, which is not subject to this cap. | | **Contact issues** | The number is not on WhatsApp or the customer blocked your marketing messages. Remove them from your audience. Contacts with two undeliverable messages in a row are left out automatically; see [unreachable contacts](/campaigns/delivery-and-reachability#unreachable-contacts). | | **Sending limits** | You hit WhatsApp's sending limit. Wait 1 to 4 hours, then spread future campaigns out and send only to customers who expect your messages. | | **Payment issues** | Open Meta billing and check the payment method of your WhatsApp Business account: pay any balance due or replace an expired card. Campaigns wait while the problem lasts and send by themselves once it's fixed; messages held longer than seven days end here. | | **Template setup errors** | The template expected a different number of variables, or WhatsApp paused or disabled it. Duplicate the template and check its variables, or create a new one if it was disabled. | | **Temporary WhatsApp errors** | An error on WhatsApp's side. Try again in 1 to 2 hours, and contact support if it keeps happening. | A low **Read rate** with a healthy **Delivery rate** is not a delivery problem: the messages arrived. Look at the template content and timing. ## Customers received the same message twice * Automated campaigns send once per event, and some events fire repeatedly for the same order or cart, such as **Order Updated**, **Checkout Updated** or **Abandoned Cart Updated**. Add a condition on the field that identifies the change you care about, for example an order status, or trigger on a one-time event such as **Order Created** or **Order Paid**. * Two automated campaigns on overlapping events, **Order Created** and **Order Paid** for example, both send to the same customer. Check the list on the **Automated** tab. * Automatic retries never duplicate a message: a message WhatsApp already accepted is not sent again, and a recipient is retried only after WhatsApp rejected the earlier attempt. ## Messages show the wrong text or a broken link * In a one-time campaign, every variable and button link must be filled in the **Message** panel; the form refuses to send otherwise. Check the preview before sending. * In an automated campaign, a variable set to **Custom value** shows the same text in every message. Choose an event field instead. Open the campaign and check the **Message** section. * A link button that opens a broken page usually comes from a nested link: a full checkout address placed in a button that already starts with your domain, or a bare placeholder button given a field that is only an ID. The form warns about both ("This choice would break the button's link. Choose another field."); change the field, or edit the button's destination in the template. A value with spaces around it also breaks the link. * Recovery links for carts and checkouts (**Their cart or checkout** in the template editor) require a connected Shopify or Zid store so Popcorn can verify the destination. ## Links are not tracked Every link button in a template goes through a Popcorn tracking link, and **Clicks** counts recipients who opened one. A click is attributed to a recipient only when the link Popcorn generated for that recipient is opened. If clicks stay at zero: * Confirm the template has an **Open a link** button. Quick reply, call and copy-code buttons are not tracked. * Check the destination: a broken or blocked destination still records the click, but customers stop tapping links that do not work. * **Clicks** counts unique recipients, so repeated taps by the same customer do not increase it. * Campaigns sent before 19 October 2026 can show fewer clicks than customers made: links in those messages did not always identify the recipient. Messages sent since then count each click for the recipient who tapped, in one-time and automated campaigns and on carousel cards. See [Link buttons and tracking](/campaigns/link-buttons-and-tracking). ## Related * [Delivery and reachability](/campaigns/delivery-and-reachability) * [Send a campaign](/campaigns/send-a-campaign) * [Automated campaigns](/campaigns/automated-campaigns) * [Channel troubleshooting](/channels/troubleshooting) # Changelog Source: https://docs.trypopcorn.ai/changelog See what's new in Popcorn AI Stay updated with the latest features, improvements, and bug fixes to Popcorn AI. **October 2026** v1.3.17 ### New Features * A guided setup experience helps you describe your business or connect your store, review what your agent knows, test it, and bring it live on WhatsApp. * Agents can now handle richer WhatsApp conversations, including typing indicators, images from GIFs and stickers, and carousel product templates. * Store-connected agents can guide customers through delivery options, payment details, order confirmation, and order tracking in chat. ### Improvements * Inbox search now includes closed and historical conversations while preserving your loaded results as you assign, move, or reply to conversations. * WhatsApp connection and storefront widget setup provide clearer status, recovery guidance, and safer save controls. * Automated campaign views now show the sending number, and long conversations retain more useful context for the agent. **August 2026** v1.3.16 ### New Features * Storefront widgets can now combine WhatsApp and web chat, with branding and channel visibility managed from Popcorn so merchants can update their customer experience without replacing installed code. * Event-driven campaign reporting now explains why messages were not sent, including when credits ran out or no sender was connected. ### Improvements * Connected Zid stores now retry temporary customer-sync interruptions and preserve access during the provider’s grace period before subscription expiry. **August 2026** v1.3.15 ### Bug Fixes * Newly synced catalogs on free and demo accounts now support image-based product search, helping shoppers find relevant products from images. **August 2026** v1.3.14 ### Improvements * Shopify-powered demos can now include more of a store’s product range, making larger catalogs more useful to explore. **August 2026** v1.3.13 ### New Features * Failed one-to-one WhatsApp messages now appear in Needs Attention so your team can follow up promptly. ### Bug Fixes * Direct credit purchases are now credited reliably after payment confirmation. * Campaign delivery now handles paused and ended campaigns more reliably, keeping retries and results up to date. * Store catalog and inventory updates now recover more reliably from rate limits and overlapping activity. **August 2026** v1.3.12 ### Improvements * Store demos now preserve localized storefront products and show more accurate currencies and product links when a storefront redirects between regional versions. * Store demos now present clearer, higher-quality merchant logos with improved handling for different logo formats and backgrounds. * Product catalog updates are more dependable during busy periods, helping changes reach connected shopping experiences more consistently. * Address collection stays connected to the active conversation, making it more reliable for customers using multiple messaging numbers. **August 2026** v1.3.11 ### Improvements * Reports and date filters now apply inclusive calendar-day ranges consistently, including when dates cross time zones or a saved link contains invalid values. * Signing out is easier to find and use on smaller screens with a clearer account control and a larger touch target. **August 2026** v1.3.10 ### Improvements * General reliability and maintenance improvements. **August 2026** v1.3.9 ### Improvements * One-to-one WhatsApp assistant and template messages are now retried automatically after temporary delivery issues, helping messages reach customers more reliably. * WhatsApp delivery statuses for product messages are now handled more accurately, including messages containing multiple products. **August 2026** v1.3.8 ### Improvements * General reliability and maintenance improvements. **August 2026** v1.3.7 ### Improvements * General reliability and maintenance improvements. **August 2026** v1.3.6 ### Bug Fixes * Campaign delivery statuses and inbox replies now remain consistent in more edge cases. ### Improvements * General reliability and maintenance improvements. **August 2026** v1.3.5 ### Bug Fixes * **More helpful results when image or video search cannot analyze a file**: Popcorn no longer silently shows unrelated products. When your message includes a meaningful product name or model number, it searches using that text and tells you that the image or video could not be analyzed. Otherwise, it explains what went wrong and asks for a clearer photo, product link, or exact product name. ### Improvements * **More natural Arabic announcements**: Arabic in-app announcements now use professional, clear Modern Standard Arabic and avoid literal translations and technical jargon. **August 2026** v1.3.4 ### New Features * Marketing campaigns automatically exclude contacts WhatsApp repeatedly cannot reach, reducing wasted sends. * Contact profiles show when campaign delivery is paused and provide a manual re-enable control. * Contacts return to campaign audiences automatically after they become reachable again. * Audience previews and campaign credit estimates now reflect reachable recipients. ### Bug Fixes * Confirmed delivery statuses no longer revert to earlier states. * Connecting a Meta catalog no longer resets the cart-ordering preference. * The demo signup button recovers correctly after an unsuccessful submission. * Arabic pages now direct search visitors to Arabic pricing. ### Improvements * Connected AI assistant sessions now receive stronger account and access protection. * Arabic marketing and privacy copy is more natural and consistent. **August 2026** v1.3.3 ### Bug Fixes * Event-triggered WhatsApp campaign retries remain recoverable through a wider range of temporary interruptions. * Messages already accepted by WhatsApp are no longer sent twice during recovery. * Late failure updates no longer cancel recoverable retries or replace newer delivery results. ### Improvements * General reliability and maintenance improvements. **August 2026** v1.3.2 ### Bug Fixes * Event-triggered WhatsApp campaign retries now recover automatically after temporary interruptions instead of being lost. * Scheduled retries remain on time, and paused campaigns resume without duplicate or missing messages. * Late delivery updates no longer overwrite newer outcomes, keeping campaign reporting accurate. * Retried messages preserve their original content. ### Improvements * Retry recovery remains responsive on large workspaces. **August 2026** v1.3.1 ### New Features * Product updates can now appear in a dedicated announcement center and optional in-app highlights. * Communication preferences let each person choose email, WhatsApp, or no product updates. * Working hours let AI agents pause replies outside business hours. * Billing supports early renewal so workspaces can add credits before the current period ends. * WhatsApp catalog health, delivery reports, and default sender controls make channel operations easier to manage. * Campaign links can be tracked to show customer engagement. * Prospective customers can try guided demos built from their store catalog. * The marketing site now offers an expanded Arabic experience with updated pricing and solution pages. ### Bug Fixes * Inbox messages and conversation previews stay correctly ordered and update reliably during busy periods. * Campaign sends, unused credit reservations, and store syncs recover more reliably from temporary interruptions. * Checkout confirmations, customer merges, template guidance, and expired WhatsApp conversations behave more consistently. ### Improvements * Live inbox updates and AI replies are faster and more reliable. * Inbox filtering is faster on large workspaces, with clearer delivery and integration health guidance. * Conversations now mark AI-to-human handovers clearly. **July 2026** v1.3.0 ### ✨ New Features * **Run your workspace from ChatGPT, Claude, or Codex.** Connect your assistant to Popcorn AI under Settings → AI Assistants, and it can work inside your workspace with you: launch and monitor campaigns, go through the inbox, look up customers and products, check orders, draft templates, and pull performance numbers. Setup is one line plus an approval screen, with no API key to copy or keep safe. * **Assistants now reach the whole dashboard, not just campaigns.** Coverage grew from campaign tools to the areas you work in every day: analytics, inbox, customers, products, orders, templates, agents, knowledge, integrations, channels, onboarding, team, and billing. ### 🚀 Improvements * **Your assistant asks first before anything it cannot undo.** Sending messages, publishing, importing, changing billing, or deleting data now show you exactly what is about to happen and wait for your go-ahead, so a misread instruction never lands on your store on its own. * **Access is bound to the person who approved it.** Every connection is tied to your user, your workspace, and the specific assistant you approved, and it stays inside the permissions your team role already has. ### 📌 Please note * If you connected an assistant before this release, planning a customer or product import now needs a matching read permission. Reapprove the connection in Settings → AI Assistants the first time you use those workflows. **February 2026** v1.1.0 ### New Features * WhatsApp template creation now provides AI-assisted category suggestions and content guidance. * Campaign filters can target contacts based on whether selected fields contain information, including Zid address fields. * Conversations can be organized with custom tags, and handovers can apply tags automatically. * Conversation activity history now records closures, reopenings, and handovers for easier follow-up. * The Caramel plan adds flexible credit tiers. * Playground collection items now have dedicated detail pages. * Inbox controls now support tag filtering and priority sorting. ### Bug Fixes * Template reviews now handle buttons, headers, footers, and validation more reliably while preserving form input after errors. * Conversation counts now match active tag filters, and message statuses remain consistent. * Billing now shows the correct Caramel tier pricing. * Connection prompts, filtering controls, and inbox actions behave more reliably during temporary interruptions and on smaller screens. ### Improvements * Conversation loading and filtering are faster, with general stability improvements. **January 2026** v1.0.4 ### New Features * Shopify merchants can configure additional checkout fields for details such as gift messages, delivery instructions, and special requests. ### Bug Fixes * Custom checkout field settings now remain saved when the feature is temporarily turned off and then re-enabled. ### Improvements * General stability and reliability improvements. **January 2026** v1.0.3 ### Improvements * General reliability and maintenance improvements. # Channels overview Source: https://docs.trypopcorn.ai/channels/overview Understand the WhatsApp and Website chat channels, how a number reaches an agent, what the default number does, and how to test on the sandbox. Channels are where your customers talk to your AI agent. Popcorn offers two: **WhatsApp**, for conversations on your WhatsApp Business number, and **Website chat**, for visitors on your store or website. Open **Integrations** at the foot of the sidebar to set either one up. ## The two channels On the **Integrations** page, the **Channels** panel ("Where your customers talk to your agent") has one row for each channel. A row shows **Available** until the channel is set up and **Connected** afterwards, with **Connect** or **Manage** on the right. When a WhatsApp number needs you, the row shows its status instead, such as **Needs reconnect**, **Not receiving** or **Meta payment problem**, with what happened and the button that fixes it; see [Channel troubleshooting](/channels/troubleshooting). The panel below it, **Stores & catalogs**, is for the places your products come from; see [Integrations overview](/integrations/overview). | Channel | What it is | Where to set it up | | - | - | - | | WhatsApp | Your WhatsApp Business number, connected to Popcorn through Meta. Customers message the number; your agent replies. Campaigns and templates also send from a connected number. | **Integrations → WhatsApp**, then **Connect WhatsApp**. See [Connect a WhatsApp number](/channels/whatsapp). | | Website chat | A chat window on your website or store. No phone number needed. | **Integrations → Website chat**. See [Set up Website chat](/channels/website-chat). | The WhatsApp page has three tabs once a number is connected: * **Account**: **Connected numbers**, the default number, message limits, and the **Products in WhatsApp** settings. See [Connect a WhatsApp number](/channels/whatsapp). * **Profile**: the business profile customers see on WhatsApp. See [WhatsApp business profile](/channels/whatsapp-profile). * **Website button**: a WhatsApp click-to-chat button for your website. See [Add a WhatsApp button to your website](/channels/whatsapp-button). Website chat has its own two tabs, **Chat** and **Design**. ## How a channel reaches an agent Every conversation is handled by one agent. Which agent depends on the channel. **WhatsApp numbers** are attached to agents from the agent's **Channels** tab. The **WhatsApp** panel lists every number connected to your workspace, each with a switch. A number can be attached to one agent at a time. Switching a number on or off is part of the agent's draft and takes effect when you click **Publish changes**. To move a number to a different agent, switch it off on the first agent and publish, then switch it on for the other; publishing an agent whose draft includes a number that is still attached elsewhere fails with **One or more WhatsApp channels are connected to another agent**. A number that is not attached to any agent is handled by your workspace's default agent, so once you switch a number off and publish, new messages on it go to the default agent. **Website chat** uses the embed code you copy. The code from **Integrations → Website chat** sends conversations to your default agent. The code shown under **Website chat widget** on an agent's **Channels** tab is bound to that specific agent. See [Connect knowledge, tools and channels](/agents/connect-knowledge-tools-channels) and [Test and publish](/agents/test-and-publish). ## What the default number means When you have more than one WhatsApp number, one of them is the default. It is marked **Default** in the **Connected numbers** table on the **Account** tab. The default number is: * the sender preselected when you create a campaign or send a template * the number the **Profile** tab opens on * the number preselected under **WhatsApp number** on the **Website button** tab The first number you connect becomes the default automatically. To change it, open the **⋯** menu of another number and click **Make default**. If the default number is deleted, another connected number becomes the default on its own. ## Test on WhatsApp with the sandbox number You do not need your own number connected to try your agent on WhatsApp. Popcorn runs a shared sandbox number, **+1 938 400 5252**. Messages sent to it from a phone number registered in your workspace are answered by your default agent and appear in your Inbox. The phone number you entered when you signed up is registered automatically. To register more phones, open an agent's **Channels** tab and click **Manage sandbox numbers**; the steps are in [Test and publish](/agents/test-and-publish#try-the-agent-on-whatsapp-with-the-sandbox). A phone can test with only one Popcorn AI account; if the number you add is already registered elsewhere, it is not added. > [!NOTE] > > If a phone that is not registered messages the sandbox number, it receives an automatic reply saying the number is not linked to any organization. The sandbox is for testing; it is not a channel for your customers. To try your agent without sending anything to WhatsApp, use **Try your agent** on **Home** or **Try it as a customer** during setup; those chats are free. See [Test and publish](/agents/test-and-publish). ## One script for your storefront The script you install on your website can show the WhatsApp button, the Website chat window, or both. Which channels are visible, and the branding, are managed from Popcorn, so you can switch channels on or off without pasting new code. A connected store can also show the script with **Show on my store**, without editing the theme. See [Set up Website chat](/channels/website-chat) and [Add a WhatsApp button to your website](/channels/whatsapp-button). ## Who can manage channels **Integrations** is visible to team members whose role includes the **Integrations** permission. Connecting a number needs the create level of that permission, deleting a number needs the delete level, and changing settings such as the default number, the profile or the website button, or using **Check again** on a number, needs edit access. Without edit access the settings pages are read-only. See [Team and roles](/settings/team-and-roles). ## Related > **[Connect a WhatsApp number](/channels/whatsapp)** > > Connect through Meta, connected numbers, message limits, default number. > **[WhatsApp business profile](/channels/whatsapp-profile)** > > Display name review, photo, category and contact details. > **[Use Popcorn with the WhatsApp Business app](/channels/whatsapp-coexistence)** > > Keep the app and Popcorn on the same number. > **[Products in WhatsApp](/channels/whatsapp-catalog)** > > Sync your catalog so customers see product cards. > **[Set up Website chat](/channels/website-chat)** > > Set up the chat window on your site or store. > **[Channel troubleshooting](/channels/troubleshooting)** > > Number not connecting, messages not delivering, button not showing. # Channel troubleshooting Source: https://docs.trypopcorn.ai/channels/troubleshooting Fix WhatsApp connection, reconnect, routing, payment, display-name and delivery problems, a missing site button or chat, and catalog sync. Find the section that matches what you see. Each one lists the exact message Popcorn shows, what it means, and what to do. ## Meta's window does not open or closes early * Meta's window has to open from your click on **Connect WhatsApp**. If you see **Your browser blocked Meta's window**, allow pop-ups for the Popcorn app in your browser and click **Try again**. * If you see **Meta's sign-in didn't load**, check your internet connection or any blocker that stops facebook.com, then click **Try again**. * If you close the window early, nothing is connected and you see **Meta's window closed before you finished**. The message names the step you stopped at, such as choosing your business, adding the number or entering the code Meta sent. Click **Start again**. * **Meta's window ran into a problem** means Meta reported an error. Nothing was connected. Start again. ## The number does not connect The page names what happened and offers one next step. The messages below are the ones not already explained in [Connect a WhatsApp number](/channels/whatsapp#if-the-connection-fails), where you will also find the permission, verification, two-step PIN, other-workspace and WhatsApp Business app cases. | Message | What to do | | - | - | | **The sign-in expired** | Meta's sign-in didn't reach Popcorn AI in time. Click **Try again**. | | **Meta didn't accept the sign-in** or **Meta didn't give Popcorn AI access** | Nothing was connected. Click **Try again** and finish every step in Meta's window. | | **This connection timed out** | Click **Start again**. | | **Meta couldn't finish the setup** or **Meta couldn't switch on your number** | Your number isn't connected yet. Try again in a moment. | | **Meta isn't responding** | Your number isn't connected yet. Try again in a few minutes. | | **Your connection dropped** | Your number wasn't connected. Check your internet connection, then **Try again**. If Popcorn can't tell whether it connected, you see **Couldn't confirm the connection**; click **Check again**. | | **Couldn't connect WhatsApp** | Something went wrong while connecting. Click **Try again**. | ## A number needs a reconnect When Popcorn can no longer send from a number, customers on it get no replies. Popcorn tells you in several places: a banner on every page, **WhatsApp needs a reconnect** in the sidebar, the number's **Status** on the **Account** tab, the **Integrations** row, and the Inbox composer ("WhatsApp is disconnected, so replies can't reach customers. Reconnect to continue."). It also emails the owner and admins of your workspace, with a reminder three days later if the number still needs a reconnect. | Status or banner | What it means | What to do | | - | - | - | | **Needs reconnect**, banner **WhatsApp needs a reconnect** | Popcorn AI can't send from the number anymore. | Click **Reconnect** and sign in with Facebook again. | | **Disconnected**, banner **Popcorn AI lost access to WhatsApp** | Access to the number was removed in Meta. | Click **Reconnect**. | | **Disconnected**, banner **A WhatsApp number stopped working** | Popcorn AI can no longer find the number in your WhatsApp account. | Click **Reconnect**. | | **Needs reconnect**, banner **A WhatsApp number is offline** | Meta has the number offline. | Click **Reconnect**. Meta may send a code to the number to confirm it; enter it when Popcorn asks ([Confirm your number](/channels/whatsapp#if-meta-asks-to-confirm-the-number)). | | **Needs reconnect**, banner **Meta is refusing WhatsApp messages** | Meta isn't letting Popcorn AI send from the number, usually because the WhatsApp account still belongs to your previous provider. | Click **Reconnect**, and when Meta asks which WhatsApp Business account to use, create a new one. | | **Reconnecting**, banner **Meta is checking your WhatsApp connection** | Meta is checking the account, often after a move to a new phone. Messages may pause for a few minutes. | Wait. If Popcorn still has no access about 45 minutes later, the number is taken off your workspace; connect it again. | If you can't connect numbers, the banner says "Ask your account owner or an admin to reconnect it." The banner adds "Other WhatsApp numbers need attention too." when more than one number does. **Reconnect** opens Meta's window again so you can sign in. For a number that is offline, or that Meta isn't letting Popcorn AI send from, the row also has **Check again** for team members who can edit integrations: Popcorn asks Meta again, as it does by itself about every 15 minutes. A campaign can't pick a number that needs a reconnect; it shows **Reconnect needed for** followed by the number, and you can choose another. ## Customers' messages go to another app Meta lets several apps share one number, and its Conversation routing decides which app gets the customers' messages. If another app, usually your previous provider, still gets them, your agent never sees them. Popcorn checks this when you connect, whenever Meta refuses a reply for this reason, and about every 15 minutes while it lasts. It shows it: * the number's **Status** reads **Not receiving** on the **Account** tab, and the **Integrations** row says the same with **See how to fix it** * a banner **Customers' messages go to another app**, with **See how to fix it**, which opens the number on the WhatsApp page * **WhatsApp messages go to another app** on the agent card in the sidebar, when the agent's numbers are affected * in the Inbox composer: "Customers' messages to this number go to another app, so a reply from here may not reach them." * when you choose the number as a campaign sender, a note says replies to it go to another app: the campaign can still send from it, but customers' replies reach the other app, not your agent. If you send a message, a file or products from the Inbox and Meta refuses it because the other app handles that customer's chat, you see **Couldn't send message**, **Couldn't send attachments** or **Couldn't send products** with "Another app connected to this number handles this customer's chat, so Popcorn AI can't reply in it." What you sent stays in the composer; trying again fails the same way until the routing is fixed. To fix it, click **Open Meta Business Suite** on the WhatsApp page, open Conversation routing and choose Popcorn AI for customer conversations, or remove the previous provider from the number. Then click **Check again** on the number's row. Templates and campaigns keep sending meanwhile. This problem is not emailed; only the dashboard shows it. ## Meta refuses to bill your WhatsApp account When the payment method of your WhatsApp Business account fails or a balance is unpaid, Meta refuses the messages it charges for. Popcorn shows it on the number's row (**Meta payment problem**), on the **Integrations** row, and in a banner on other pages: **Meta is refusing your WhatsApp messages**, "A payment problem in Meta billing stops campaigns and automatic messages, like abandoned cart reminders and order updates". Each offers **Open Meta billing**, which opens Meta's billing page in a new tab. The owner and admins of your workspace get an email when it starts and a reminder three days later. * **What waits**: campaigns and automatic messages wait instead of failing. Popcorn sends one of them an hour per WhatsApp account to see whether Meta accepts payment again. A week after the problem started, waiting messages go to Meta again whatever the state. See [When Meta refuses payment](/campaigns/delivery-and-reachability#when-meta-refuses-payment) for campaigns. * **What still goes out**: replies to customers are never held, and Meta still delivers the replies it doesn't charge for, so your agent keeps answering. A message Meta charges for, such as a template outside the 24-hour window, can fail. * **When it clears**: once Meta charges for a message sent after the problem started. The notices disappear, waiting messages send by themselves, and the owner and admins get an email saying your WhatsApp messages are sending again. Fix it in Meta billing: check the payment method of the WhatsApp Business account, pay any balance due, or replace an expired card. Closing the banner hides it for this session; it returns if Meta starts refusing again. ## A number is missing from Connected numbers The **Account** tab reads what Popcorn last learned from Meta and never waits on Meta, so a slow or failing Meta never hides a number. A number leaves **Connected numbers** only when it was removed: * **Someone on your team deleted it** with **Delete**. Connect the same number again to bring back its templates, AI agent and team label. * **Meta confirmed that Popcorn AI lost access**, because Popcorn AI was removed from the account or number in Meta, or because Meta's offboarding did not come back within about 45 minutes. Popcorn takes the number off your workspace and emails the owners "Your WhatsApp number was disconnected". Its templates, AI agent and settings are kept. Click **Connect another number** on the **Account** tab (or **Reconnect WhatsApp** in the email) and sign in again. If the cause was Meta's offboarding and Meta restores access within 7 days, the number comes back by itself. If every number is gone, the page reads **Connect your WhatsApp Business number**, as if nothing were connected. ## Connected, but the agent does not reply Right after **WhatsApp is connected**, the agent answers on the number straight away. If it doesn't: 1. Check the number's **Status** on the **Account** tab. Anything other than **Live** is covered above. 2. Check that the number is answered by a published agent. A number that is attached to no agent is answered by your default agent, and an agent needs a published version before a number can be routed to it. See [Connect knowledge, tools and channels](/agents/connect-knowledge-tools-channels). 3. Check your credits. When they run out, the agent stops replying; see [Inbox troubleshooting](/inbox/troubleshooting#the-agent-is-not-replying). 4. If the number also runs in the WhatsApp Business app, check **Hand over when your team replies from the app** on the **Account** tab. With it on, your agent stops replying in a conversation once your team replies from the phone. See [Use Popcorn with the WhatsApp Business app](/channels/whatsapp-coexistence). ## Message limit shows Syncing with Meta or Limit unavailable The **Message limit** column on the **Account** tab is read from Meta and refreshed every 24 hours. Until Meta has confirmed a limit, campaign messages from that number are held and retried every minute; if the limit is still unknown after about an hour, they are marked as failed. * **Syncing with Meta**: Popcorn has not received the limit yet, or Meta no longer accepts Popcorn's access to the number. If it does not change within a day, connect the number again with **Connect another number**. * **Limit unavailable**: the last check hit a temporary error. Popcorn retries by itself, starting 15 minutes later and spacing the tries out to once a day. See [Delivery and reachability](/campaigns/delivery-and-reachability) for how limits and quality affect campaigns. ## Display name pending, declined or not turned on On the **Profile** tab, **WhatsApp display name** shows the review state, and Meta won't send from some numbers until the name is approved. In that case the number's **Status** reads **Name needs approval**, **Name in review**, **Name declined** or **Name needs activation**, and a banner says "Your WhatsApp number can't send messages", "WhatsApp is reviewing your display name", "WhatsApp declined your display name" or "Your display name is approved but not turned on". | What you see | What to do | | - | - | | **Pending review** or **Name in review** | Meta is still reviewing. There is nothing to do; Popcorn checks the status by itself. | | **Approved**, **Ready** or **Name needs activation** | Click **Activate approved name**. Popcorn confirms with **Display name activated**. | | **Declined**, **Rejected** or **Name declined** | The card shows **Meta rejected this display name** with Meta's reason. Click **Change in Meta** and submit a different name in WhatsApp Manager. | | **Name needs approval** | Click **Submit name in WhatsApp Manager**. | | **Expired** | Meta closed the request. Submit the name again with **Change in Meta**. | Display names can only be changed in Meta. The full steps are in [WhatsApp business profile](/channels/whatsapp-profile#when-meta-wont-send-until-the-name-is-approved). ## Messages are not delivered Open the message in the **Inbox**: a message that did not go out shows **Not delivered** and a note under it says why and what to do. The most common ones: | The note says | What to do | | - | - | | "The 24-hour reply window has closed" | More than 24 hours passed since the customer's last message. Send an approved template. | | "Your account was flagged for spam" | Too many customers reported your messages. Send less often. | | "Meta limited this marketing message" | Meta doesn't deliver marketing templates to customers who haven't engaged lately. Send order updates and reminders as a utility template. | | "This number can't be reached" | They may not have WhatsApp, or the number is wrong. | | "Your WhatsApp account is locked" or "A payment issue on your WhatsApp account" | Resolve the account issue in Meta Business Manager or Meta billing. For payment, see [Meta refuses to bill your WhatsApp account](#meta-refuses-to-bill-your-whatsapp-account). | | "WhatsApp won't send from this number until its display name is approved" | Sending again won't help. Open **Integrations → WhatsApp → Profile** to see where the name stands. | | "The media couldn't be uploaded" | Check the file's format (JPEG, PNG, MP4 or PDF) and size, then send it again. | | "The customer opted out of marketing" | Don't include them in campaigns. You can still answer their own messages. | The full list is in [Inbox troubleshooting](/inbox/troubleshooting#a-message-shows-not-delivered). For campaigns, open the campaign and read the failure categories, such as **Marketing message limits**, **Sending limits** and **Template setup errors**. A campaign larger than the number's daily limit is spread over several days, which Popcorn tells you before you send. See [Campaign troubleshooting](/campaigns/troubleshooting) and [Delivery and reachability](/campaigns/delivery-and-reachability). ## The button or chat does not show on my site Check in this order: 1. **Is the code installed?** The snippet must be on the page, ideally before ``. Copy it again with **Get embed code** on **Integrations → WhatsApp → Website button** or on **Integrations → Website chat**. 2. **Is the channel on and saved?** The WhatsApp button needs **Show WhatsApp button** on. Website chat on a store needs **Show on my store** on. Both need **Save changes**. With both off, the storefront script shows nothing. 3. **Is a number selected?** The WhatsApp button needs a **WhatsApp number**. If that number was deleted, the form says "This number is no longer connected. Choose another one." and the button is not drawn until you choose another and save. 4. **Is another widget already on the page?** Only one Popcorn widget loads per page, and the chat bubble never loads inside an embedded frame. Remove duplicate snippets. 5. **Is the domain shared?** If your store's domain is connected to more than one Popcorn workspace, such as an old trial, Popcorn can't tell which one to use and shows nothing. Disconnect the store from the workspace you no longer use. 6. **An older Zid installation?** Zid stores installed earlier without workspace details are matched by their domain, and the WhatsApp button only shows once it has been saved. Save the **Website button** tab once with **Show WhatsApp button** on. Changes apply on the next page load, so reload the page after saving. See [Add a WhatsApp button to your website](/channels/whatsapp-button) and [Set up Website chat](/channels/website-chat). ## Product cards or the catalog are not working | What you see | What to do | | - | - | | Products arrive as plain images, not cards | **Product sharing** is off, or the catalog isn't live. Check the **Products in WhatsApp** panel on **Integrations → WhatsApp → Account**: the badge should read **Live**. | | A product shows **Sent as image** or **Sent in a carousel** in the Inbox with "WhatsApp hasn't reviewed this product yet" | WhatsApp reviews each product on its own before it can go out as a catalog card, which can take hours after it reaches the catalog. Nothing to do: Popcorn checks the review again and the product goes out as a card once WhatsApp approves it. | | The same with "WhatsApp didn't approve this product" | WhatsApp's review refused it, so it keeps going out as an image card. If you change the product, click **Sync products**: Popcorn reads WhatsApp's review again after each sync. | | **Needs reconnect** on the panel or health card | Meta no longer accepts Popcorn's connection. Products go out as image cards until it is restored. Click **Reconnect WhatsApp**. | | **Not accepted** with a count | Open **Products Meta rejected** for Meta's reason. A missing photo is one cause: add an image, then click **Sync products**. | | **Not in WhatsApp yet** with a count | Not pushed yet, or removed from the catalog at Meta. Click **Sync products**, or **Resync products** under **Integrations** after changes in your store. | | **Syncing** for a long time | Meta hasn't confirmed the batch. The card says "Meta is taking longer than usual". Click **Refresh** later; the nightly comparison with the catalog corrects anything still unconfirmed. | | **No catalog shared with Popcorn AI yet** | Click **Add a Commerce catalog in Meta** and create or choose a Commerce catalog in Meta's window. | | **WhatsApp can't show products from this catalog** or **This WhatsApp account already has a catalog** | The catalog isn't a Commerce catalog, or Meta allows one per account. Follow the steps in [If the catalog can't connect](/channels/whatsapp-catalog#if-the-catalog-cant-connect). | | A banner says "Meta didn't accept the cart setting for" a number | Click **Try again**. | | Cards show, but customers can't add to a cart | Turn on **Cart checkout** and click **Save changes**. | Full details are in [Products in WhatsApp](/channels/whatsapp-catalog) and [Integrations troubleshooting](/integrations/troubleshooting). # Set up Website chat Source: https://docs.trypopcorn.ai/channels/website-chat Add Website chat to your website or store, set its name, messages and design, and show it on your storefront. Website chat puts your AI agent on your own website as a chat bubble. Visitors chat without WhatsApp or a phone number, the same agent answers from the same knowledge bases, and every conversation lands in your Inbox. Use it for support and sales on your storefront, landing pages or help centre. ## Before you start * A published agent. Website chat is answered by your workspace's default agent unless you install an agent-specific snippet (see "Which agent answers" below). * Access to your website's HTML or your store platform's custom-code setting, unless you use **Show on my store** with the storefront script already installed. * Credits. AI replies in Website chat use credits the same way WhatsApp replies do. When your credits run out, conversations are handed to your team until you top up (see [Plans and credits](/billing/plans-and-credits)). ## Configure the chat Go to **Integrations** and open **Website chat**. The page has two tabs, **Chat** and **Design**, and a **Preview** panel ("Shows your changes before you save them.") that reflects your changes as you make them. Click **Save changes** in the bar that appears, or **Discard** to revert. If you can only view the page, it says "You can view these settings. Ask an admin to change them." ### Chat tab | Section | Field | What it does | | - | - | - | | (top) | **Show on my store** | "Adds the chat to your connected store for you. Turn off to show it only on pages where you pasted the embed code." Only an admin can turn it on or off. | | **General** | **Chat title** | Shown at the top of the chat window. | | | **Reply name** | Shown next to each reply. | | | **Welcome message** | The first message customers see when they open the chat. | | | **Fallback reply** | Sent when your agent can't answer a question. | | | **Brand description** | One sentence about what your store sells. | | **Suggested questions** | **Question 1** to **5** | Up to five questions customers can tap to start a chat. Click **Add question** to add one, or the remove button to delete it. At five, the page says "You've added the maximum of 5 questions". | | **Sources** | **Show sources** | "Let customers see where an answer came from." | | | **Show sources by default** | Appears once **Show sources** is on; shows the sources under every answer without the customer asking. | ### Design tab * **Avatar**: pick one of the five built-in avatars, or choose **Upload your own** (JPEG, PNG, GIF or WebP). It appears in the chat header and next to each reply. * **Chat button icon**: pick one of the six built-in icons, or upload your own. This is the button visitors tap to open the chat on your website. An uploaded image goes into the form like any other change: it reaches your website chat when you click **Save changes**, and you see **Website chat saved**. If an upload fails you see **Couldn't upload the image**. ## Install the chat There are two ways to put the chat on a site, and they can be combined. ### Paste the embed code **1. Copy the code** Click **Get embed code** at the top of the page. The dialog **Add website chat to your website** says "Paste this code before the closing `` tag on every page where it should appear." Click **Copy code**. **2. Add it to your pages** Paste the snippet just before the closing `` tag of every page that should show the chat, or into your store platform's custom-code or scripts setting so it loads on all pages. **3. Check the site** Open your site. The bubble appears in the bottom-right corner; click it to open the chat and send a test message. The conversation appears in your Inbox with the source **Website widget**. The snippet identifies your workspace only. The title, messages, avatar and icon are read from Popcorn each time the chat loads, so later changes need no re-installation. ### Show it on your connected store If the storefront script from the WhatsApp button is already installed on your store, you do not need a second snippet. Turn on **Show on my store** and save: the same script loads Website chat alongside, or instead of, the WhatsApp button, and you can switch between the two channels from Popcorn at any time. See [Add a WhatsApp button to your website](/channels/whatsapp-button). If saving the switch fails you see "Couldn't change whether the chat shows on your store"; your other changes are saved, so save again to retry it. ## What visitors see * A round bubble in the bottom-right corner of the page, showing your **Chat button icon**. On phones it sits closer to the edge. * Clicking it opens the chat panel: about 400 pixels wide on desktop, nearly the full screen width on phones. * The panel opens with your **Welcome message** and, underneath it, your suggested questions. * Replies are labelled with the **Reply name** and show the avatar you chose on the **Design** tab. * Closing the panel brings the bubble back; the conversation continues where it left off. ## Which agent answers The snippet from **Integrations → Website chat** uses your workspace's default agent. To bind Website chat to a specific agent, open that agent, go to its **Channels** tab and copy the code under **Website chat widget**. See [Connect knowledge, tools and channels](/agents/connect-knowledge-tools-channels). ## How Website chat conversations work * A visitor's first message creates a customer record and a conversation in the **Inbox**, listed under the source **Website widget**. See [Inbox overview](/inbox/overview). * When a teammate replies from the Inbox, the visitor sees the reply in the chat immediately. * Messages never go through WhatsApp: there is no 24-hour window, WhatsApp message templates do not apply, and media files cannot be sent from the Inbox to a Website chat conversation. * Only one Popcorn widget loads per page. If a page already has one (for example the storefront script with **Show on my store** on), a second snippet is ignored. ## Test it before going live Use the **Preview** panel on **Integrations → Website chat**: it is a working chat with your agent that reflects your title, messages and design as you edit them. To test the agent's answers in depth, use the agent's test chat (see [Test and publish](/agents/test-and-publish)). ## Related * [Channels overview](/channels/overview) * [Add a WhatsApp button to your website](/channels/whatsapp-button) * [Channel troubleshooting](/channels/troubleshooting) if the bubble does not show # Connect a WhatsApp number Source: https://docs.trypopcorn.ai/channels/whatsapp Connect your WhatsApp Business number through Meta's window, then manage connected numbers, the default number, message limits and reconnects. Connecting a WhatsApp Business number lets your AI agent answer customers on WhatsApp and lets you send campaigns and templates from that number. You connect it once through Meta's sign-up window; Popcorn registers the number and keeps its message limit in sync afterwards. ## Before you start * A Facebook login with admin access to your business. The sign-up runs in Meta's own window, so allow pop-ups for Popcorn. * A phone number that can get a code by text message or call, and your business name as customers will see it. If the number is already in use on the WhatsApp Business app and you want to keep using the app, follow [Use Popcorn with the WhatsApp Business app](/channels/whatsapp-coexistence) instead. * A role that can connect integrations. Without it, the page reads "WhatsApp isn't connected yet" and asks you to "Ask an admin to connect your WhatsApp Business number." See [Team and roles](/settings/team-and-roles). * Optional: a catalog for your products. You can also set it up later; see [Products in WhatsApp](/channels/whatsapp-catalog). ## Connect the number **1. Open WhatsApp** Go to **Integrations** and click **Connect** on the **WhatsApp** row. With no number connected, the page reads **Connect your WhatsApp Business number**. If you already have one, open the **Account** tab and click **Connect another number**. **2. Click Connect WhatsApp** Under "What Meta will ask for" you see what to have ready: your Facebook login, a phone number that can get a code, your business name and, optionally, a catalog. It takes about 3 minutes. Click **Connect WhatsApp**: Meta's window opens in the same click. **3. Finish in Meta's window** Sign in with Facebook, choose or create your WhatsApp Business account, add the phone number and verify it with the code Meta sends. Keep every permission switched on. While you work, Popcorn shows **Finish in Meta's window** with **Show Meta's window** and **Start over**. If Meta asks you to create a catalog, choose Commerce as its vertical; it starts on Generic. **4. Choose the account and number** If you shared more than one WhatsApp account, Popcorn asks "Which WhatsApp account should Popcorn AI use?". If the account has more than one number, it asks "Which number should Popcorn AI answer on?". Choose one and click **Connect**. You can add the others later. **5. Wait for the connection** **Connecting your number** shows its steps (**Signed in**, **Securing**, **Linking your number**, **Checking it can send and receive** and **Setting up products**) and takes up to 30 seconds. Keep the page open. Then you see **WhatsApp is connected**, for example "+966 5x xxx xxxx is connected. Your AI agent now answers messages here." If you connected a catalog in the same sign-in, it says so, and **Other numbers on this account** lists up to three more, each with **Add**. If the check finds something to fix, you see **Connected, one thing left** instead; see [below](#if-the-number-connects-but-needs-one-more-thing). Your agent answers on the number straight away: a number that is attached to no agent is answered by your default agent. To bind it to a specific agent, open the agent, go to its **Channels** tab and switch the number on; see [Connect knowledge, tools and channels](/agents/connect-knowledge-tools-channels). While the number connects, Popcorn registers it with Meta using a two-step verification PIN that it generates and stores, links the number to your workspace and reads its message limit. It then asks Meta whether it can send from the number and whether customers' messages to it reach Popcorn. The first number you connect becomes the default. A number that is on the WhatsApp Business app is connected as a coexistence number instead. ## If Meta asks to confirm the number Meta sometimes won't switch a number on until it is confirmed with a code sent to that phone. Popcorn then shows **Confirm your number** ("Meta needs to confirm this number before Popcorn AI can use it. Meta sends a 6-digit code to the phone with this number.") on the page, so you don't go back to Meta. **1. Ask for the code** Click **Text me the code**, or **Call me instead** to have Meta call the number and read the code out. **2. Enter it** Type it under **6-digit code** and click **Confirm and connect**. The connection then finishes as usual. Under **Didn't get it?**, **Send a new code** asks again and **Call me instead** or **Text me instead** changes how it is sent. A wrong code shows "Meta didn't accept that code. Check it and enter it again, or ask for a new one." **Meta couldn't send the code** means wait a minute and ask again, or ask for a call. **Cancel** stops without connecting the number. ## If the number connects but needs one more thing The number is saved and listed under **Connected numbers**, but the check after connecting found that it can't do your agent's work yet. **Connected, one thing left** says what is wrong and the one fix: | What it says | What to do | | - | - | | "…is connected, but Meta isn't letting Popcorn AI send from it yet. Usually the WhatsApp account picked in Meta's window still belongs to your previous provider." | Click **Connect again**, and when Meta asks which WhatsApp Business account to use, create a new one. | | "…is connected, but customers' messages still go to your previous provider, another app on this number." | Click **Open Meta Business Suite**, open Conversation routing and choose Popcorn AI for customer conversations, or remove the previous provider from the number. Templates and campaigns still send meanwhile. | | "…is connected, but Meta has it offline." | Click **Connect again**. Meta may send a code to the number to confirm it. | When you have made the change, click **Check again**. If Meta now says the number is ready, the notice turns into **WhatsApp is connected**. Otherwise a notice says nothing has changed for the number yet, and what is still wrong. The same problems and buttons stay on the number's row; see [Status and what needs you](#status-and-what-needs-you). ## If the connection fails The page shows what happened, with one next step. | Message | What to do | | - | - | | **Your browser blocked Meta's window** | Allow pop-ups for this site, then click **Try again**. | | **Meta's window closed before you finished** | Nothing was connected. The message names the step you stopped at, for example "You stopped before entering the code Meta sent to your phone." Click **Start again**. | | **Meta's sign-in didn't load** | Check your internet connection, or allow facebook.com in any blocker, then **Try again**. | | **Some permissions are switched off** | Popcorn AI needs every permission Meta asks for. Click **Connect again** and keep them all on. | | **Meta didn't share a WhatsApp account** or **Your WhatsApp account has no number yet** | Connect again, and choose your account or add your number when Meta asks. | | **Your number isn't verified yet** | Finish verifying it in Meta, then connect again. **Open Meta** takes you there. When you connect a single number, Popcorn asks for the code on the page instead; see [If Meta asks to confirm the number](#if-meta-asks-to-confirm-the-number). | | **Turn off two-step verification first** | The number still has a two-step PIN from an earlier connection. In WhatsApp Manager open the number's settings, then **Two-step verification**, and turn it off (Meta emails you a link to confirm). Then connect again. | | **This number is in another workspace** | It is connected to another Popcorn AI workspace. Contact support to move it, or delete it there first. | | **This number isn't on the WhatsApp Business app** | You chose to connect it from the app, but Meta doesn't show it there. Connect again and choose to connect it as a new number. | | **Only an admin can connect WhatsApp** | Ask your account owner or an admin. | For a dropped connection, Popcorn says "Your connection dropped. Checking whether your number connected." and offers **Check again** if it can't tell. More cases are in [Channel troubleshooting](/channels/troubleshooting). ## The Account tab **Connected numbers** lists every number in your workspace. | Column | What it shows | | - | - | | **Number** | The phone number. With several numbers, the default carries a **Default** badge. A number shared with the WhatsApp Business app carries **Uses WhatsApp Business app**. | | **Date added** | When the number was connected. | | **Status** | **Live** for a healthy number. Other values are explained below. | | **Message limit** | The number's daily limit from Meta, such as "2,000 a day" or "No limit". | The **⋯** menu (**More actions**) on a row has **Make default** for a number that is not the default, **How to disconnect** for a coexistence number, and **Delete**. **Connect another number** sits below the table. A badge next to the page title shows the status of the number that needs you most, so a healthy account reads **Live**. ### Status and what needs you | Status | Meaning | | - | - | | **Live** | The number is working. | | **Reconnecting** | "Meta is checking this connection. Messages may pause for a few minutes." Meta usually restores it by itself. If Popcorn still has no access about 45 minutes later, the number is taken off your workspace and you connect it again. | | **Needs reconnect** | Customers on the number get no replies. The row says why: "Popcorn AI can't send from this number anymore", "Meta has this number offline", or "Meta isn't letting Popcorn AI send from this number, usually because the WhatsApp account still belongs to your previous provider". Click **Reconnect** on the row, or ask your account owner or an admin to. For the previous provider, create a new WhatsApp Business account when Meta asks which one to use. | | **Not receiving** | "Customers' messages to this number go to another app." Your agent doesn't see them, but templates and campaigns still send. Click **Open Meta Business Suite**, open Conversation routing and choose Popcorn AI. | | **Disconnected** | Access to the number was lost. The row says either "Access to this number was removed in Meta, so customers on it get no replies." or "Popcorn AI can no longer find this number in your WhatsApp account, so customers on it get no replies." Click **Reconnect** on the row, or ask your account owner or an admin to. | | **Name needs approval**, **Name in review**, **Name declined**, **Name needs activation** | Meta won't send from the number until its display name is approved. **Open display name** takes you to the **Profile** tab. See [WhatsApp business profile](/channels/whatsapp-profile). | | **Meta payment problem** | "Meta refuses the messages it charges for from this WhatsApp account until its payment is fixed. Campaigns and automatic messages wait and send by themselves after that." Click **Open Meta billing**. A **Not receiving** number with the same problem keeps that status and also offers **Open Meta billing**. See [Meta refuses to bill your WhatsApp account](/channels/troubleshooting#meta-refuses-to-bill-your-whatsapp-account). | When the row says the number is offline, that Meta isn't letting Popcorn AI send from it, or **Not receiving**, it also has **Check again** for team members who can edit integrations. Popcorn asks Meta again whether the number can send and whether customers' messages reach it, then tells you either that Meta says the number is ready ("It can send messages, and customers' messages reach Popcorn AI.") or that nothing has changed yet. Popcorn also checks these numbers by itself about every 15 minutes, so the status clears on its own once the fix is made in Meta. The status comes from what Popcorn last learned from Meta, so opening the page never waits on Meta. The **Integrations** row, the sidebar ("WhatsApp needs a reconnect", or "WhatsApp messages go to another app") and the Inbox composer also say when a number needs you. ## Message limits Meta limits how many customers a number can start a conversation with in a 24-hour period. The limit belongs to your Meta business portfolio, so every number in the same WhatsApp Business account shares it. Popcorn reads it when you connect and refreshes it every 24 hours. The tiers are 250, 1,000, 2,000, 10,000, 100,000 and unlimited. * **Syncing with Meta** means Popcorn has no confirmed limit for this number yet. Campaign messages from it are held and retried every minute; if the limit is still unknown after about an hour, they are marked as failed. If it stays on this for more than a day, connect the number again with **Connect another number**, which refreshes Popcorn's access. * **Limit unavailable** means Meta returned a temporary error. Popcorn retries by itself, starting 15 minutes later and spacing the tries out to once a day. Campaign sending stays within the limit; see [Delivery and reachability](/campaigns/delivery-and-reachability#whatsapp-daily-limits). ## Make a number the default The default number is preselected as the sender for campaigns and templates, and it is the number the **Profile** tab opens on. See [what the default number means](/channels/overview#what-the-default-number-means). On the **Account** tab, open the **⋯** menu of the number and click **Make default**. You see **Default WhatsApp number updated**. Campaigns you already created keep their own sender. **Make default** only appears if your role can edit integrations. ## Delete a number Open the **⋯** menu of the number and click **Delete**. The dialog "Delete" followed by the number says: * Your AI agent stops replying to messages on this number. * At Meta, the number stops sending and receiving messages until it's connected again. For a number shared with the WhatsApp Business app, "Nothing changes in your WhatsApp Business app." * Connect the same number again later to bring back its templates, AI agent and team label. * If it was the default, another connected number becomes the default. Click **Delete number** to confirm; you see **WhatsApp number deleted**. A coexistence number can't be deleted here while Popcorn still has access to it: use **How to disconnect** and follow [disconnecting a coexistence number](/channels/whatsapp-coexistence#disconnect-the-number). ## Settings on the Account tab Below the numbers, the **Account** tab holds workspace-wide WhatsApp options. Changing a switch brings up a bar with **Save changes** and **Discard**, and you see **Settings saved**. * **Products in WhatsApp**: sync your products to a Meta catalog so customers get product cards and carts. See [Products in WhatsApp](/channels/whatsapp-catalog). * **WhatsApp Business app**: appears only when a number is shared with the app. See [Use Popcorn with the WhatsApp Business app](/channels/whatsapp-coexistence). ## What customers see while your agent replies * When your agent is about to reply, the customer's message is marked as read and WhatsApp shows that you are typing until the reply arrives. * Stickers and GIFs a customer sends reach your agent as pictures, so it can take them in context, as long as **Let the agent handle media messages** is on under **Settings → General**. See [Workspace settings](/settings/workspace). ## Related > **[WhatsApp business profile](/channels/whatsapp-profile)** > > Display name, photo, category and contact details customers see. > **[Use Popcorn with the WhatsApp Business app](/channels/whatsapp-coexistence)** > > Keep replying from the app on the same number. > **[Send a campaign](/campaigns/send-a-campaign)** > > Choose the sender number and estimate credits. > **[Channel troubleshooting](/channels/troubleshooting)** > > Number not connecting, display name pending, messages not delivering. # Add a WhatsApp button to your website Source: https://docs.trypopcorn.ai/channels/whatsapp-button Set up the WhatsApp click-to-chat button for your website or store, customise its text and look, and install the embed code once. The WhatsApp button is a floating **Chat with us on WhatsApp** button for your website or store. A visitor who clicks it lands in a WhatsApp chat with your connected number, with a message already typed, and the conversation arrives in your Inbox like any other WhatsApp message. Use it to turn store visitors into WhatsApp conversations your agent can handle. ## Before you start * At least one WhatsApp number connected under **Integrations → WhatsApp**. Without one, the **Website button** tab says **No WhatsApp number connected**: "Connect a number in the Account tab, then come back to add the button to your website." * A role that can edit settings, to save the button. Members without it can view the tab ("You can view these settings. Ask an admin to change them.") and still copy the embed code. See [Team and roles](/settings/team-and-roles). * Access to your site's HTML or your store platform's custom-code setting. ## Configure the button **1. Open the Website button tab** Go to **Integrations → WhatsApp** and open the **Website button** tab. **2. Keep it on** Leave **Show WhatsApp button** on. When it is off, the button is hidden on your site without removing the code, and the preview reads "Turn on the button to see a preview". **3. Fill in the Button section** Choose the **WhatsApp number** customers will message, write the **Button text** and the **Starting message**. **4. Adjust Appearance** Pick the **Button color**, **Position** and **Size**. The **Preview** panel ("Shows your changes before you save them.") shows the result. **5. Save** Click **Save changes**. You see **Button settings saved**. Saved changes reach your site on its next page load, without re-installing the code. ## What the settings mean | Setting | Details | | - | - | | **Show WhatsApp button** | Shows or hides the button on your site. Saving with it off keeps your other settings. | | **WhatsApp number** | The connected number the chat opens with. Your default number is preselected; see [Connect WhatsApp](/channels/whatsapp) for **Make default**. | | **Button text** | The text on the button. Required, up to 50 characters. Popcorn suggests **Chat with** followed by your workspace name, or **Chat with us on WhatsApp**. | | **Starting message** | Typed into the visitor's WhatsApp composer when the chat opens, up to 500 characters. They can edit it before sending. | | **Button color** | The button's background, chosen with the color picker. A color code like `#25D366`, WhatsApp green, is the default. | | **Position** | **Bottom right**, **Bottom left**, **Top right** or **Top left**. | | **Size** | **Small**, **Medium** or **Large**. | If a value is invalid, Popcorn shows the reason under the field, for example "Keep the button text to 50 characters or fewer" or "Enter a color code like #25D366", and "Check the highlighted fields" when you try to save. > [!NOTE] > > The small **Powered by Popcorn AI** line is always shown under the button and cannot be removed. ## Install it on your site **1. Get the code** Click **Get embed code**. The dialog **Add the WhatsApp button to your website** says "Paste this code before the closing `` tag on every page where it should appear." Click **Copy code**; you see **Code copied**. **2. Paste it once** Add the snippet to your site's HTML before ``, or to your store platform's custom-code or scripts setting so it loads on every page. **3. Test it** Open your site, click the button and confirm WhatsApp opens with the starting message. Send it: the conversation appears in your Inbox. The snippet carries only your workspace identifier. The number, text, color, position and size are read from Popcorn each time a page loads, so you paste the code once and manage everything from the **Website button** tab. If you copy the code before saving, a notice says "Your button settings aren't saved yet": until you save, the code shows the button with its default text and color. ## What visitors see * A rounded button in the corner you chose, drawn above the page content, with the WhatsApp logo and your **Button text** in white on your **Button color**. On phones it sits closer to the edge of the screen. * Underneath it, the small **Powered by Popcorn AI** line. * Clicking the button opens WhatsApp in a new tab (or the WhatsApp app on a phone) with a chat to your selected number and the **Starting message** ready to send. * Once the visitor sends that message, the conversation appears in your Inbox on that number and is handled by whichever agent the number is attached to (see [Connect knowledge, tools and channels](/agents/connect-knowledge-tools-channels)). ## Change or hide it later * To hide the button on every page, turn **Show WhatsApp button** off and click **Save changes**. The installed code stays where it is and can be switched back on at any time. * **Discard** in the save bar returns the form to the last saved settings. * If you delete the number selected under **WhatsApp number**, it shows "(disconnected)" and the form says "This number is no longer connected. Choose another one." The button isn't drawn until you select another number and save. ## One script, two channels The same storefront script also serves Website chat. What visitors see depends on two switches: | **Show WhatsApp button** | **Show on my store** (Website chat) | What visitors see | | - | - | - | | On | Off | The WhatsApp button | | Off | On | The Website chat bubble | | On | On | Both | | Off | Off | Nothing | Change either switch in Popcorn and the site follows on its next page load; the installed code never needs to change. **Show on my store** lives on the **Integrations → Website chat** page; see [Set up Website chat](/channels/website-chat). Zid and Shopify stores can also be recognised from the store's own domain, so an older Zid installation of the snippet without workspace details keeps working. ## Related * [Channels overview](/channels/overview) * [Set up Website chat](/channels/website-chat) * [Channel troubleshooting](/channels/troubleshooting) if the button does not appear # Products in WhatsApp Source: https://docs.trypopcorn.ai/channels/whatsapp-catalog Connect a Meta catalog so your agent sends product cards in WhatsApp, turn on cart checkout, read the health card, and see when products go as images. **Products in WhatsApp** links the products in Popcorn to a Meta commerce catalog. Once connected, the products your AI agent recommends, and the products your team sends from the Inbox, arrive as WhatsApp product cards that customers can open and add to a cart, instead of plain image messages. Use it when you have products in Popcorn and at least one WhatsApp number. It is a panel on the **Account** tab of **Integrations → WhatsApp**. Its badge shows where the catalog stands: **Not set up yet**, **Syncing**, **Live**, **Needs attention** or **Needs reconnect**. ## Before you start * At least one WhatsApp number connected. See [Connect WhatsApp](/channels/whatsapp). * Products in Popcorn, synced from your store or added by hand. See [Product catalog](/products/catalog). * A Meta catalog of the **Commerce** type, shared with Popcorn AI. A catalog that Meta's sign-in window creates is shared in the same step. A catalog made anywhere else, such as Commerce Manager, is invisible to Popcorn until it is shared through that window. * Meta allows one catalog per WhatsApp account, and the catalog is shared by every number on that account. * A role that can manage products. Without it, the panel says "Ask an admin to finish setting up your products." ## Connect the catalog You can connect it while connecting a number, or later. **While connecting a number.** Meta's window can create a catalog or let you pick one you already have, and Popcorn connects it in the last step (**Setting up products**). The success message then adds "Your catalog" and its name "is connected too." **Later, from the Account tab.** **1. Click Set up products** On the **Products in WhatsApp** panel ("Sync your Popcorn AI products so customers can browse them and receive product cards in WhatsApp."), click **Set up products**. Popcorn looks at the catalogs Meta has shared with it. **2. Choose a catalog if asked** With one catalog, Popcorn connects it. With several, **Choose where to sync your products** lists them ("We found these catalogs in the Meta business connected to your WhatsApp number."). Each option under **Use an existing catalog** shows its name, "Catalog ending in" its last digits, **Products** with a count, **Owner**, and "Already linked to this WhatsApp account" where that applies. Pick one and click **Connect products**. **3. Let the first sync run** You see **Catalog connected**: "Your products are syncing to WhatsApp. This can take a few minutes." The sync runs on Popcorn's servers, so you can close the tab. If Meta has shared no catalog, the panel says **No catalog shared with Popcorn AI yet**. Click **Add a Commerce catalog in Meta**: it opens Meta's window to create one or choose one you already have. If you create one, choose **Commerce** as its vertical; it starts on **Generic**. ### If the catalog can't connect The panel names the problem and its one next step. | What you see | What to do | | - | - | | **WhatsApp can't show products from this catalog** | It isn't a Commerce catalog. Go through Meta's window again and choose **Commerce**. If your WhatsApp account already uses it, unlink it in Meta first (**How to unlink it in Meta** shows the steps), click **Check again**, then add a Commerce catalog. | | **This WhatsApp account already has a catalog** | Meta allows one per account. Click **Use** followed by that catalog's name, or unlink it in Meta and choose another. | | **Another WhatsApp account uses this catalog** | A catalog can be on one WhatsApp account only. **Choose another catalog**, or unlink it from the other account in Meta. | | **Another Popcorn AI workspace uses this catalog** | A catalog syncs with one workspace only. Choose another. | | **Popcorn AI can't use this catalog yet** | Click **Reconnect WhatsApp** and share the catalog when Meta asks. | | **Your connection to Meta expired** | Click **Reconnect WhatsApp** to keep your products in sync. | | **Meta can't find this catalog** | It may have been deleted in Meta. Choose another catalog. | | **This catalog belongs to another Meta account** | Choose a catalog from the Meta account that owns your WhatsApp number. | | **Meta didn't respond** | Try again in a minute. | ## What syncs to Meta For every product in Popcorn the catalog receives the name, description, price and currency, the sale price when it is below the regular price, the product link, the images and availability: * Availability follows stock: a product with stock is sent as in stock, a product with none as out of stock. * Inactive products are sent as archived, so customers do not see them. * Products without an image get no placeholder. Meta rejects them, and they stay in the health card until you add a photo. Syncs run after the catalog is connected, whenever products are added, changed or removed by a sync from your store (including **Resync products** under **Integrations**), whenever you delete a product or a variant in **Products** (it is removed from the catalog), and every night, when Popcorn compares its products with the Meta catalog and repairs differences. **Sync products** on the panel pushes everything again at once. ## Read the catalog health card Once a catalog is connected, the panel shows the card below. It counts active products only. | What you see | Meaning | | - | - | | **Products live in WhatsApp**, with "12 of 14" | Live products can be sent as product cards. | | **Your products are live in WhatsApp.** | Nothing to fix. | | **Not accepted** with a count, and **Products Meta rejected** | Meta refused these items. The list shows the first five with Meta's reason, and **Show all** reveals the rest. Fix the product, then **Sync products**. | | **Not in WhatsApp yet** with a count | Not pushed yet, or removed from the catalog at Meta. **Sync products** sends them again. | | **Syncing** with a count | Pushed and waiting for Meta to confirm. The card says "Meta is taking longer than usual" after about five minutes; click **Refresh** later. | | **No active products to sync yet** | Your workspace has no active products. | | **Needs reconnect** | Meta no longer accepts Popcorn's connection. Until it is restored, products go out as image cards. Click **Reconnect WhatsApp**. | **Catalog:** followed by its name, and **Last verified** with a time, show which catalog it is and when Meta last confirmed it. **Refresh** reloads the numbers; "Couldn't load catalog health" offers **Try again**. Reasons Meta gives for a rejected product, and the fix: | Reason shown | Fix | | - | - | | Meta couldn't load the photo | Replace it with a JPG or PNG under 5 MB. | | Add a photo | Meta needs one for every product. | | Check the price | It must be a number above zero. | | Choose your currency in Settings | Set the default currency, then sync again. | | Meta's commerce rules don't allow this product | Change or remove the product. | | Check the name, description, photo and price | Then sync again. | If the catalog also receives products from another source in Meta, a warning says some products may show twice. ## Product sharing and Cart checkout Two switches sit under the health card. Change them, then click **Save changes**; you see **Settings saved**. ### Product sharing "When on, your AI agent sends products as WhatsApp catalog cards. When off, it sends product photos instead." With it on, products go out as catalog cards, whether the agent recommends them or a teammate sends them from the Inbox: * One product becomes a single product card. * Several products become one product list message. WhatsApp allows 30 items per message, so larger selections are split into consecutive messages. * Products that are not live in the catalog (rejected, not synced, or still syncing), or that WhatsApp hasn't approved yet, go out as image cards instead. With it off, or while the catalog connection has expired, every product goes out as an image card. ### Cart checkout "Customers can order from their WhatsApp cart." When you save, Popcorn turns the WhatsApp cart on or off for every connected number. With it on, customers can add products from your cards to their WhatsApp cart and send the cart to you. It arrives in the conversation, and the agent continues with the order from there; see [Orders](/orders/overview). If Meta doesn't accept the setting for a number, a banner says so ("Meta didn't accept the cart setting for") and offers **Try again**. ## When products go out as image cards Two or more products that go out as image cards and each have a photo, a name and a link are sent together as one swipeable carousel, up to 10 cards per message. Each card shows the photo, the name, a line of description, the price and a button that opens the product page, or adds the product to the order when your agent is taking one. The rest go out on their own image card with the name, description, price and link, or as text when the product has no photo. The Inbox shows how many items reached the customer, for example **3 of 4 delivered to the customer**, and marks each product that didn't go as a catalog card with **Sent as image**, **Sent in a carousel** or **Sent as text** and the reason, such as "This product is still syncing to the catalog". ### WhatsApp's review of each product WhatsApp reviews every product on its own before it can appear in a catalog card, which can take hours after the product reaches the catalog. Until WhatsApp approves it, the product goes out as an image card or in a carousel, and the Inbox gives the reason "WhatsApp hasn't reviewed this product yet", or "WhatsApp didn't approve this product" if the review refused it. Popcorn reads the review after each sync, several times over the next two days and every night, and the product goes out as a catalog card once it is approved. The health card does not show this review: a product can count as live there and still be waiting for WhatsApp. ## If cards still do not appear Check that **Product sharing** is on and saved, that the badge reads **Live**, that the product shows as live in the health card, and what the Inbox says under the product, for example that [WhatsApp hasn't reviewed it yet](#whatsapps-review-of-each-product). See [Channel troubleshooting](/channels/troubleshooting#product-cards-or-the-catalog-are-not-working). ## Related * [Meta Business catalog](/integrations/meta-business) for how this connects to the **Integrations** page. * [Product catalog](/products/catalog) for what your products contain and **Resync products**. * [Channel troubleshooting](/channels/troubleshooting) when the catalog will not sync. # Use Popcorn with the WhatsApp Business app Source: https://docs.trypopcorn.ai/channels/whatsapp-coexistence Keep the WhatsApp Business app on the same number as Popcorn: set up coexistence, choose what happens when you reply from the app, and disconnect. Coexistence lets one phone number work in the WhatsApp Business app and in Popcorn at the same time. Your AI agent answers customers through Popcorn, your team can still reply from the app on their phones, and both sides see the same conversation. Use it when you already run your business on the WhatsApp Business app and do not want to give the number up. ## Before you start * The number is active in the WhatsApp Business app. * A Meta login that can manage your business. * A role with edit access to **Integrations**. ## What changes in the WhatsApp Business app Popcorn's setup lists these before you connect (**See what keeping the app changes** in [Quickstart](/quickstart#already-on-the-whatsapp-business-app)). Your number and chats stay, and a few things work differently: | Area | What changes | | - | - | | Who your agent answers | Everyone who messages the number, family and friends too. | | Keeping the app in use | Open WhatsApp Business on your phone at least once a week. After about 2 weeks without it, WhatsApp disconnects your agent. | | Broadcast lists and chat features | Broadcast lists stop working, and disappearing messages, view-once messages and live location switch off in customer chats. Send offers from **Campaigns** instead, to customers who agreed to get them. WhatsApp charges for each campaign message. | | Linked devices | Everything linked to WhatsApp Business signs out when you connect. You can link devices again, except WhatsApp for Windows and Wear OS, which don't work with a connected number. | | Groups | Groups stay in the app and don't show in Popcorn. | | WhatsApp's fee | The first 1,000 messages a month that your agent and your team send to answer customers are free, then about SAR 0.04 each, charged to a card in your Meta account. Campaigns aren't part of the free 1,000. Messages you send from WhatsApp Business stay free. | Before you connect, update WhatsApp Business: Facebook's window asks you to confirm in the app on your phone and to choose whether to share your chats. Turn off greeting and away messages under Business tools so customers get one answer, and add anything they mention that your agent should know, such as your working hours, to your agent first. Connect the number customers already message. Your chats stay on your phone; new chats show in Popcorn, and so do the last 6 months if you share them. ## Set up coexistence **1. Start the WhatsApp connection** Go to **Integrations → WhatsApp** and click **Connect WhatsApp** (or **Connect another number** on the **Account** tab). See [Connect a WhatsApp number](/channels/whatsapp) for the full flow. **2. Choose your WhatsApp Business app number in Meta's window** Meta's sign-up offers to connect a number that is already on the WhatsApp Business app. Pick that option and follow Meta's steps for the app. Popcorn also asks Meta directly whether the number is on the app, so a number that is on the app is connected through coexistence even if you took the standard option in Meta's window. **3. Check the number in Popcorn** After **WhatsApp is connected**, the number appears under **Connected numbers** with a **Uses WhatsApp Business app** badge next to **Live**. If you chose the app option but Meta doesn't show the number on the app, the connection stops with **This number isn't on the WhatsApp Business app**. Click **Connect again** and choose to connect it as a new number, or set the number up in the app first. **4. Connect the number to an agent** A number that is attached to no agent is answered by your default agent. To bind it to a specific agent, open the agent, go to its **Channels** tab, switch the number on and publish. See [Connect knowledge, tools and channels](/agents/connect-knowledge-tools-channels). Right after the connection, Popcorn asks Meta for the number's contacts and chat history from the app. Imported conversations are placed in the **Closed** folder of your Inbox with the AI switched off, so old chats do not trigger replies. ## Choose what happens when you reply from the app Every message your team sends from the WhatsApp Business app also appears in the Popcorn conversation, as an outgoing message labelled **via WhatsApp app**. If the conversation was closed, it reopens. What your agent does next is a workspace setting. On the **Account** tab, the **WhatsApp Business app** panel appears when at least one of your numbers is shared with the app: | **Hand over when your team replies from the app** | What happens after someone replies from the app | | - | - | | Off (default) | Your agent stays in charge. It records the message and keeps answering the customer's next messages. Use this when your team starts conversations from the phone and wants the agent to take it from there. | | On | "When your team sends a message from the WhatsApp Business app, your agent stops replying and your team takes over." Use this when a reply from the phone means a person is personally handling the customer. | Switch it, then click **Save changes** in the bar that appears; you see **Settings saved**. The change applies to messages sent from the app after you save; it does not change conversations already handed over. To give a conversation back to the agent, use **Hand back to agent** in the Inbox. See [Work a conversation](/inbox/working-conversations#hand-back-to-the-agent). ## How a coexistence number behaves differently | Area | Behaviour on a coexistence number | | - | - | | Automatic follow-ups | The agent's follow-up messages skip any conversation that received a message from the app in the last 24 hours, so an automated nudge never lands on top of a reply your team just sent. | | Replies outside the 24-hour window | If the AI's reply is refused because the customer's 24-hour window is closed, Popcorn sends the template you set as **Follow-up template** in **Settings → General** instead, and adds the note **Message window expired. A template message was sent instead.** to the conversation. If no template is set, the reply is marked as failed. See [Workspace settings](/settings/workspace). | | Campaign speed | Popcorn sends campaigns from a coexistence number at up to 20 messages per second, compared with 55 from a standard number, so large campaigns take longer. | | Display name | Popcorn cannot activate an approved display name on a coexistence number. Activate it from Meta or from the WhatsApp Business app. See [WhatsApp business profile](/channels/whatsapp-profile). | | Removing the number | There is no **Delete** for a coexistence number while Popcorn still has access to it. Disconnect it from the app as described below. | Messages from the app that Popcorn shows in the Inbox are copies of what your team already sent; Popcorn does not send them again. If you later move the number off the WhatsApp Business app onto the Cloud API and connect it again, Popcorn treats it as a standard number from then on: the **Uses WhatsApp Business app** badge disappears, **Delete** replaces **How to disconnect**, and campaigns send at the standard speed. ## Disconnect the number Meta does not allow Popcorn to disconnect a coexistence number, so you do it from the app. On the **Account** tab, the row menu shows **How to disconnect** instead of **Delete**, with these instructions: **1. Open the WhatsApp Business app** Go to **Settings > Account > Business Platform** and choose **Disconnect Account**. **2. Let Popcorn catch up** Meta notifies Popcorn, which removes the number from **Connected numbers**. Your conversation history in Popcorn is kept. If the number was your default, the most recently updated remaining number becomes the default. The same happens if Popcorn's access to the number is removed on Meta's side: the number disappears from **Connected numbers** without you deleting it. To connect it to Popcorn again, repeat the setup above. ### If you move the app to a new phone Moving the WhatsApp Business app to another phone can make Meta briefly take the connection down. Popcorn shows the number as **Reconnecting** ("Meta is checking this connection. Messages may pause for a few minutes.") and keeps it. Meta normally restores it by itself. If access is still gone after about 45 minutes, Popcorn takes the number off **Connected numbers**; if Meta restores it within 7 days, Popcorn brings it back. > [!NOTE] > > A number can be connected to only one Popcorn workspace. If the connection stops with **This number is in another workspace**, contact support to move it, or disconnect it there first. ## Related > **[Connect a WhatsApp number](/channels/whatsapp)** > > The standard connection, connected numbers and message limits. > **[Inbox overview](/inbox/overview)** > > Where handed-over conversations go and how to give them back to the AI. > **[Delivery and reachability](/campaigns/delivery-and-reachability)** > > Message statuses, limits and retries for campaigns. > **[Channel troubleshooting](/channels/troubleshooting)** > > Number not connecting and messages not delivering. # WhatsApp business profile Source: https://docs.trypopcorn.ai/channels/whatsapp-profile Set what customers see on WhatsApp: the display name and its Meta review status, profile photo, category, description, address, email, and website. The **Profile** tab controls how your business appears to customers on WhatsApp: the display name next to your messages, the profile photo, and the details shown when a customer opens your business info. Changes are sent to Meta and apply to the number you are editing. ## Before you start * At least one connected WhatsApp number. See [Connect a WhatsApp number](/channels/whatsapp). * For a display name change: access to Meta's WhatsApp Manager. Meta requires display-name changes to be submitted there, not in Popcorn. * A role that can edit integrations. Without it, the tab reads "Ask an admin to change this profile." ## Open the profile Go to **Integrations → WhatsApp** and open the **Profile** tab. It opens on your default number. Under **Number**, choose the number whose profile you want to edit; each number has its own profile. If you switch numbers with unsaved edits, Popcorn asks **Discard unsaved changes?** ("Your edits to this number's profile haven't been saved."); **Keep editing** returns you to the form. ## Display name The **WhatsApp display name** card shows the name Meta has approved for this number and its status. Changing the name takes two parts: you submit the new name in Meta, and Popcorn activates it on the number once Meta approves it. **1. Submit the new name in Meta** Click **Change in Meta**. This opens the phone numbers page of your WhatsApp Business account in WhatsApp Manager. Submit the new display name there. **2. Let Popcorn follow the review** Back on the **Profile** tab, the card shows the **Requested name** and the status **Pending review**. While the tab is open, Popcorn re-reads the status from Meta every 15 seconds; Meta also notifies Popcorn when it decides, so you do not need to keep the tab open. **3. Activation** When Meta approves the name, Popcorn turns it on for the number. If it can't, **Activate approved name** appears on the card: click it. The status becomes **Activating**, then **Active**, and you see **Display name activated**. | Status | Meaning | | - | - | | **Not submitted** | No name change has been requested. | | **Pending review** | Meta is reviewing the requested name. | | **Approved** | Meta approved the name; it still needs to be activated on the number. | | **Ready** | Meta accepted the name without a review; it still needs to be activated. | | **Activating** | Popcorn is activating the approved name. | | **Active** | The approved name is live on this number. | | **Declined** / **Rejected** | Meta refused the name. The card shows **Meta rejected this display name** with Meta's reason, or "Meta did not provide a rejection reason. Open WhatsApp Manager for details." Submit a different name in Meta. | | **Expired** | Meta closed the request without a decision. Submit it again in Meta. | | **Status unavailable** | Popcorn could not read the status from Meta. Reload the page; if it persists, see [Channel troubleshooting](/channels/troubleshooting). | Activation can fail in these cases, shown under **Couldn't activate the display name**: * **This number is connected through the WhatsApp Business app.** Coexistence numbers are activated from Meta or from the WhatsApp Business app, not from Popcorn. See [Use Popcorn with the WhatsApp Business app](/channels/whatsapp-coexistence). * **Reconnect this WhatsApp number so Popcorn can securely activate the approved display name.** Connect the number again with **Connect another number** on the **Account** tab, then activate. * **Meta has not approved this display-name change yet.** Wait for the review to finish. * **The approved display name is already being activated.** An activation is already running; wait a moment and reload the page. * Any other failure shows Meta's own message. Fix the cause in WhatsApp Manager and click **Activate approved name** again. ### When Meta won't send until the name is approved Some numbers, such as the US +1 555 numbers Meta offers during sign-up, can't send until Meta approves their display name. When Meta refuses a send for that reason, Popcorn shows it in three places: the number's **Status** on the **Account** tab (**Name needs approval**, **Name in review**, **Name declined** or **Name needs activation**), a notice on the **Integrations** row, and the Profile tab's card. | State | What to do | | - | - | | **Name needs approval** | "WhatsApp won't send from this number until its display name is approved." Click **Submit name in WhatsApp Manager**. If WhatsApp Manager already shows the name **In Review**, it is submitted and there is nothing more to do here. | | **Name in review** | "Messages are paused while WhatsApp reviews the display name." Nothing to do. **View in WhatsApp Manager** shows the review. | | **Name declined** | "WhatsApp declined the display name." In WhatsApp Manager, open the number's settings, then **Profile**, then **Display name**, then **Edit**, and submit a different name with **Submit another name**. | | **Name needs activation** | "The display name is approved. Turn it on to start sending." Click **Activate approved name**. | This notice only reports what Meta did. It never blocks a send by itself, and it clears once Meta accepts a send or the name is approved and activated. ## Edit profile information **1. Profile** * **Profile photo**: click **Choose file** (or **Change** if a photo exists) and pick a JPEG or PNG image. * **Team label**: a short label such as Sales or Support. "Only your team sees this. It replaces the phone number in the inbox," so your team can tell numbers apart. Customers never see it. * **Category**: the business type Meta shows on your profile: Apparel, Auto, Beauty, Education, Entertainment, Event planning, Finance, Government, Grocery, Health, Hotel, Nonprofit, Professional services, Restaurant, Retail, Travel or Other. * **Description**: the text customers read about your business. **2. Contact details** Fill in **Address**, **Email** and **Website**. Popcorn stores one website per number. **3. Check the preview and save** The **Preview** panel shows the profile as WhatsApp lays it out. When you are done, click **Save changes** in the bar at the bottom, or **Discard** to drop your edits. Popcorn confirms with **Profile saved**. Everything except the **Team label** is sent to Meta and appears in your WhatsApp business profile; the label stays inside Popcorn. Saving only the label does not contact Meta. > [!NOTE] > > The display name is not edited here. The name shown in the preview is the name Meta has verified for the number; change it through **Change in Meta** as described above. ## Troubleshooting * **Couldn't save the profile**: Meta rejected the update. Check that the photo is a JPEG or PNG, then save again. If the notification includes a reason from Meta, fix that first. A photo that fails to upload shows **Couldn't upload the photo**. * **Couldn't load this number's profile**: Popcorn reads the profile from Meta each time you open the tab or switch numbers. Click **Try again**. If it keeps failing, connect the number again from the **Account** tab so Popcorn refreshes its access. ## Related > **[Connect a WhatsApp number](/channels/whatsapp)** > > Connected numbers, default number and message limits. > **[Channel troubleshooting](/channels/troubleshooting)** > > Display name rejected, number not connecting, messages not delivering. # Customers Source: https://docs.trypopcorn.ai/customers/overview Find every contact, edit details and tags, import or delete in bulk, and understand subscription and paused-campaign states. **Customers** is the list of everyone who has talked to your agent, been imported, or been synced from your store. Use it to look up a person before replying, tag people for campaign audiences, fix a phone number or email, and see what a customer has bought. ## Where customers come from * **Conversations**: a WhatsApp contact is created the first time they message you; a Website chat visitor is created when they start chatting. * **Your store**: when you connect Shopify, Zid or Salla, Popcorn imports the store's customers in the background and keeps them updated as the store reports new and changed customers. * **Import customers** from a file, or **Add customer** for one person. ## The list Three filters sit above the table: **All**, **Customers** and **Guests**, with a count beside **Customers** and **Guests**. A contact with a phone number or an email address is a customer. **Guests** are mostly Website chat visitors who gave neither: the tab lists contacts missing a phone number or an email address, but the count beside it includes only contacts missing both. **Search** takes a name, phone number or email. A phone number pasted the way WhatsApp shows it, such as one with a plus sign and spaces, still matches. The list is newest first, 10 customers a page. | Column | What it shows | | - | - | | **Customer** | The name, with the phone number under it. Contacts without a name show as **Guest**. Click to open the profile. | | **Email** | | | **Last seen** | When the customer's most recent conversation started: a relative time within the last week, a date after that. | | **Tags** | The first two tags, plus a count of any others. | Narrow windows show fewer columns. The **⋯** menu (**More actions**) on a row offers **Edit** and **Delete**. ## Add or edit a customer **1. Open the form** Click **Add customer**, or **Edit** in a row's menu. **Edit customer** in the Inbox customer details opens the same form. **2. Fill in the details** **First name**, **Last name**, **Phone number** with its country code, and **Email**. The **Marketing subscription** switch controls whether the customer can receive your WhatsApp campaigns; it is on for new customers. **3. Save** Click **Add customer** or **Save**. You see "Customer saved". * A phone number is required when you add someone, and for anyone who already has one. A Website chat visitor who never gave a number can be saved without one. * Adding a number that already belongs to a customer updates that customer instead of creating a duplicate. Only the fields you filled in are changed: blank fields and tags stay as they were, and the subscription changes only if you switched it. * Changing a customer's number to one that belongs to someone else fails with "Another customer already has this phone number." * Changing the number of a customer whose campaigns were paused re-enables them, because the delivery failures may have been about the old number. ### Tags Tags describe the person and are how you build campaign audiences. They are not the [conversation tags](/inbox/tags-and-macros#conversation-tags) you use to triage the Inbox. A new customer's form says "You can add tags after the customer is saved." On a saved customer, click **Add tags** (or **Edit tags** when there are some) to open the **Edit tags** dialog. It lists the customer's tags with a **New tag** field and an **Add** button; a tag you type that does not exist yet joins your workspace's list. Click **Save tags**. You see "Tags saved". ## Subscribed and unsubscribed Campaigns go only to subscribed customers unless you explicitly choose to send to unsubscribed ones: a one-time campaign's audience starts with the **Marketing subscription** **Is** **Subscribed** condition and warns you if your conditions let unsubscribed customers in, and automated campaigns skip them unless **Send to unsubscribed customers** is on. See [Send a campaign](/campaigns/send-a-campaign#unsubscribed-customers-in-the-audience). Conversations in the Inbox are not affected. A customer becomes unsubscribed when: * you switch off **Marketing subscription** on their form, * they tell your agent they no longer want messages and the agent's **Let customers opt out** switch is on; new agents start with it on ([Agent capabilities](/agents/capabilities)), * they tap Stop on your marketing messages in WhatsApp (Popcorn also learns this when WhatsApp refuses a marketing message because the customer had tapped Stop), * your Shopify store reports them as opted out of marketing (Salla and Zid do not sync a marketing opt-out). When a customer opts out themselves, by asking your agent or tapping Stop, the opt-out is counted on the **Unsubscribed** figure of the last campaign that reached them in the week before; see [Unsubscribes](/campaigns/delivery-and-reachability#unsubscribes). To subscribe someone again, switch **Marketing subscription** back on in their form. A customer who tapped Stop and later turns your marketing messages back on in WhatsApp is subscribed again automatically, unless they also asked your agent to stop or were unsubscribed another way. If you subscribe a customer who tapped Stop, WhatsApp keeps refusing your marketing messages to them until they turn them back on, and the first refused message marks them unsubscribed again. Store sync never subscribes an unsubscribed customer again. ## Campaigns paused for a customer When two consecutive marketing campaign messages to a contact fail with WhatsApp's "message undeliverable" error, Popcorn stops including them in campaigns. Their profile shows a banner, **Campaigns are paused for this customer**, saying when it happened and how many messages in a row failed. They are left out of campaign audiences, audience previews and credit estimates until the pause is lifted. It lifts automatically when the customer sends you a message or you change their phone number. To lift it yourself, click **Re-enable campaigns** in the banner; you see "Campaigns re-enabled". Only marketing templates count towards the pause, and a delivered message resets the failure count. See [Delivery and reachability](/campaigns/delivery-and-reachability). ## The customer profile Click a name to open the profile. The **Customers** link at the top takes you back to the list you came from, with its page and search kept. * **Header**: the name (or the phone number, or **Guest**), a line such as "Customer since Mar 3, 2026 · From your Shopify store" (the store part only for customers a store sync created), and badges: **Subscribed** or **Unsubscribed**, **Verified** (when your store marks the customer or their email as verified) and **Blocked**. * **Store spend**, **Store orders** (with the date of the last order), **Average order** and **Conversations**: lifetime figures synced from your store. Without store figures, **Conversations** moves into **Details**. * **Contact**: **Phone** (beside a named customer), **Email** and **Address** when synced. * **Details**: **Customer number**, **Platform ID**, **Business**, **Loyalty points**, **Last seen**, **Last order** and **Block reason**, each only when the customer has one. * **Tags**: shown as badges. Change them with **Edit** from the list. * **Orders through Popcorn AI**: the orders placed in conversations, with **Order**, **Date**, **Total** and **Status**. Click one to open it; see [Orders](/orders/overview). A customer with none sees "No orders through Popcorn AI yet". The store figures above cover every order in your store, so they can be higher than this list. The profile has no edit or block buttons. Edit from the list, and block or unblock from the conversation in the Inbox; see [Work a conversation](/inbox/working-conversations#block-a-customer). ## Store sync rules Synced customers keep a link to the store record (**Platform ID**). When the store sends an update: * a name you edited in Popcorn is not replaced by an empty value from the store; * a store opt-out sets the customer to **Unsubscribed**, but the store never reverses an unsubscribe, however it happened; * **Blocked** is never changed by the store. Shopify, Zid and Salla all report new and updated customers as they happen. If customer sync is not working for a store connected some time ago, use **Reconnect** on the **Integrations** page so Popcorn gets the customer permission; see [Integrations](/integrations/overview). ## Import customers **1. Start the import** Click **Import customers**. The dialog says "Upload a CSV or Excel file. Each row needs a phone number." Choose a file or drag it in. **Download a sample file to get started** gives you the right columns. **2. Match columns** Tick **First row has column names** if your file has a header row, then match your columns to **First name**, **Last name**, **Email**, **Phone number** (required), **Tags** and **Subscribed**. Choose **Don't import** for any column you do not need, then click **Continue**. Separate tags with commas, for example `tag1, tag2`. **Subscribed** accepts true or false, 1 or 0, yes or no, y or n; an empty cell means subscribed. Phone numbers must be valid and include the country code. **3. Fix errors and import** Rows with problems are flagged so you can correct them in place: names up to 80 characters, tags up to 120 characters in total, and an email that is valid and appears once in the file. When every row is clean, continue to start the import. The import runs in the background whatever its size. An **Importing customers** dialog shows the progress; you can close it and the import keeps running. When it ends, **Import finished** reports how many customers were imported and how many existing ones were updated, and how many rows were skipped, with the reasons under **Rows with errors**. A file can hold up to 150,000 rows. Longer lists stop with "List too large" and the size to split them into. Existing customers are matched by phone number, and their name, email, tags and subscription are replaced by the file's values, so a blank cell clears the old value. Tags that do not exist yet are created in the workspace. > [!WARNING] > > An empty **Subscribed** cell counts as subscribed. If a customer who had unsubscribed is in your file with that cell empty, importing subscribes them again. Fill in `no` for anyone who must stay out of campaigns. ## Delete customers * **One customer**: choose **Delete** in the row's menu. The dialog **Delete Sara?** (with the customer's name) says "This can't be undone." Under **If a customer has conversations**, choose **Keep them** (the default) or **Delete them anyway**. Click **Delete customer**. With **Keep them**, a customer who has conversations is not deleted and you see "Sara has conversations, so they were kept." * **Several customers**: tick the rows, or tick the header box for the page. The bar above the list shows "N selected" with **Delete**. When no search or tab narrows the list and you have ticked a whole page, **Select all N customers** appears and selects every customer in your workspace; **Select only this page** takes it back. Click **Delete**, make the same choice, and click **Delete customers**. The result reads, for example, "40 customers deleted", with "3 customers were kept because they have conversations". * Deleting all customers, or more than 5,000 at once, runs as a background job. The **Deleting customers** dialog shows the progress and says "You can close this window. The deletion keeps running." Deleting cannot be undone. **Delete them anyway** removes the customer but not their conversations and orders: "Their conversations and orders stay in Popcorn AI, without a customer profile." Each conversation stays in the Inbox with its messages, shown as **WhatsApp contact** (or **Guest** for Website chat) instead of the customer's name. ## Related * [Send a campaign](/campaigns/send-a-campaign) to target customers by tag and subscription. * [Orders](/orders/overview) * [What AI assistants can do](/ai-assistants/what-you-can-do) to look up and import customers from ChatGPT, Claude or Codex. # How Popcorn works Source: https://docs.trypopcorn.ai/how-popcorn-works Understand the pieces of Popcorn: workspace, agents, channels, Knowledge, Inbox, campaigns, credits, and roles. Popcorn connects three things: your store, a channel your customers write on, and an AI agent that answers there. Everything else in the app either feeds the agent (Knowledge, tools, store data) or works with the conversations it creates (Inbox, campaigns, reports). This page defines each piece the way the app names it and points to the detailed guide. > [!NOTE] > > **Home** shows a notice that its insights are in beta, and **Spotlight** is free during its beta. Their numbers and behaviour may still change. ## Workspace Your workspace is your business's account in Popcorn: its store connection, channels, agents, Knowledge, team, and credits. Setup creates one; teammates you invite join it, and one account can create more workspaces for other stores or brands. Workspace-wide options live under **Settings**, grouped into **Personal**, **Workspace**, **Automation**, **Commerce** and **Developer**. **Settings → General** holds the default currency, product options, and **Working hours**, which can hold campaigns until your business hours. The workspace menu at the top of the sidebar switches workspaces and holds **Settings**, **Team members**, **Plan and billing**, **Language** (English, Arabic and Spanish) and **Sign out**. See [Workspace settings](/settings/workspace). ## AI agents An agent answers your customers from your Knowledge, with the capabilities you switch on for it. Most agents run on **Popcorn's rules**: Popcorn writes and tests how the agent sells, answers and hands over, and you choose how it sounds with its **Voice**. An agent of type **Custom instructions** runs on instructions you write instead. The type is chosen when the agent is created and cannot be changed. Your workspace gets its first agent from setup, built from your website; you can create more with **New agent**. Each agent has five tabs: | Tab | What it controls | | - | - | | **Instructions** | **Name**, then **Voice** (Popcorn's rules) or **Instructions** with **Draft with agent** (custom instructions), then **How it replies**, including **Check replies before sending** | | **Knowledge** | Which knowledge bases the agent answers from, and what the nightly Knowledge check found | | **Actions** | **Recommend products**, **Take orders in chat**, **Track orders**, **Send images in chat**, follow-ups, safety switches, and your custom **Tools** | | **Handoff** | **Hand over to your team**, with **Handover topics** (kinds of chats your team always takes), your own rules and **Alerts** by Slack or email | | **Channels** | Which WhatsApp numbers this agent answers, sandbox numbers, and the **Website chat widget** code | **Default agent.** One agent carries the **Default** badge. It answers every connected number that is not assigned to another agent, Website chat that does not name an agent, and the sandbox. Use **Set as default** in the agents list to change it; the agent must be published first (**Publish to set as default**). **Draft, publish, versions.** Edits are saved as a draft that customers do not see. **Publish changes** makes it live for new chats; in the same dialog you choose **New chats only** or **New chats and chats in progress**, and can add a note. **Version history** lists every version and lets you roll back. **Test agent** opens a chat with the published version in your browser. See [Agents overview](/agents/overview), [Popcorn's rules and Voice](/agents/popcorns-rules) and [Test and publish](/agents/test-and-publish). ## Channels A channel is where customers reach the agent. Open **Integrations** to set up either: * **WhatsApp.** Connect a WhatsApp Business number through Meta's sign-up window. The number's page lists **Connected numbers** (one is the default, with **Make default**), the business **Profile** customers see, and a **Website button** that opens a chat from your site. **Products in WhatsApp** connects your Meta catalog so the agent can send product cards. See [Channels overview](/channels/overview) and [Connect a WhatsApp number](/channels/whatsapp). * **Website chat.** A chat window for your website, configured on the **Chat** and **Design** tabs. Copy the embed code and paste it into your pages. See [Set up Website chat](/channels/website-chat). **Sandbox.** Popcorn's shared test number, +1 938 400 5252, answers messages from phone numbers registered in your workspace with your default agent, before you connect a number of your own. Register numbers with **Manage sandbox numbers** on an agent's **Channels** tab. See [Test and publish](/agents/test-and-publish#try-the-agent-on-whatsapp-with-the-sandbox). ## Knowledge **Knowledge**, under **Your agent** in the sidebar, is what your agents read before they answer. It is organized in **folders**, and each agent is given access folder by folder. Inside a folder, **articles** are written from scratch, imported with a link, or created from a document. | Article state | Meaning | | - | - | | **Draft** | The version you are editing. The agent never uses it. | | **Published version** | The version the agent answers from. Each publish keeps the previous version in **History**. | The **Used by agent** column shows which articles the agent matched and cited in conversations. Setup fills a **Business Knowledge Base** folder with the website pages it picked, or with the description you wrote. See [Knowledge overview](/knowledge/overview). ## Tools A tool is an action the agent can take during a conversation beyond answering from knowledge: looking something up in another system or sending data to it. Store capabilities such as product recommendations, orders and order tracking are built in and switched on under **Actions**. Anything else is a custom tool you build, or add from the **Tools showcase**, then switch on in the **Tools** panel of the agent's **Actions** tab. See [Custom tools](/tools/overview). ## Conversations and the Inbox Every exchange with a customer is a conversation, on **WhatsApp**, **Website widget**, **Template** (one your team started with a template), **API** or **Sandbox**. The **Inbox** folders show who is replying: | Folder | What it means | | - | - | | **Agent** | The agent is replying to every customer message. **Take over** pauses it for that conversation. | | **Needs you** | Every open conversation a person owns or nobody has picked up, across the whole team. The Inbox opens here. **Unassigned** is the part nobody has taken yet. | | **Mine** | Conversations you took over or were assigned. | | **Later** | Your conversations that are snoozed or waiting on the customer. | | **Closed** | Resolved conversations, closed by your team or by the agent's **Close resolved chats**. A customer who writes again starts a new conversation. | | **Test conversations** | Chats you start to try your agent. They are left out of **Reports**. | A handover is the move from the agent to your team. It happens when the agent decides to hand over (the customer asks for a person, or a chat matches one of your handover topics or rules), when **Check replies before sending** gives up after its last retry, when spam or off-topic messages repeat, when the workspace has no credits left or its plan through Zid has ended, or when no agent is set up for the number. A template sent to one customer, outside a campaign, that failed for good also lands in **Needs you**. On handover the conversation goes to **Unassigned**, the agent pauses, and Popcorn alerts the people you chose in **Settings → Notifications**, plus Slack or email if the agent's **Alerts** are on. Your team can give a conversation back with **Hand back to agent**. **The 24-hour window.** WhatsApp lets a business send free-form messages only within 24 hours of the customer's last message. In a conversation your team is handling, a line above the message box shows a countdown. When it expires the only way to write is an approved template through **Send template**. Website chat and API conversations have no window. See [Inbox overview](/inbox/overview) and [Work a conversation](/inbox/working-conversations). ## Campaigns and templates **Campaigns** holds three tabs: **One-time**, **Automated** and **Templates**. * **Templates** are WhatsApp message formats that Meta must approve before you can send them outside the 24-hour window. See [Templates](/campaigns/templates). * **One-time campaigns** send an approved template to an audience you build, now or at a time you schedule. Customers whose last two marketing messages WhatsApp reported as undeliverable are left out automatically. See [Send a campaign](/campaigns/send-a-campaign). * **Automated campaigns** send a template when something happens in your store, such as an abandoned cart or an order event. See [Automated campaigns](/campaigns/automated-campaigns). ## Credits Credits are the unit Popcorn bills by. Your plan adds a monthly allowance, and **Plan and billing** shows what remains. The sidebar shows the credits left under your agent. | Action | Credits | | - | - | | One reply from your agent, however many messages it contains | 1 | | One-time campaign messages | 1 per 10 messages | | Automated campaign messages | 1 per 5 messages | Messages your team types in the Inbox are not charged, and neither are test chats from setup and **Home**. A new workspace starts with 100 free credits that expire after a month. When credits reach zero, the agent stops replying, the agent card in the sidebar reads **Stopped, out of credits**, and every new customer message goes to your team until you top up. You can buy extra credits in blocks of 1,000, turn on automatic top-up, or renew early; **Credit usage** breaks spending down by source and can be exported as CSV. See [Plans and credits](/billing/plans-and-credits) and [Credit usage](/billing/credit-usage). ## Connected store Connecting Shopify, Salla or Zid under **Integrations** syncs products and inventory, customers and orders, cart and checkout, and order tracking. That is what lets the agent recommend real products, complete an order in the chat, and answer "where is my order". **Meta Business** syncs the same catalog to Meta so WhatsApp can show product cards. **Store health** on **Integrations** rates the connection **Healthy**, **Partly working**, **Not working**, **No recent activity** or **Not configured**. See [Connect your store](/integrations/overview). ## Team and roles Invite colleagues under **Settings → Team members**; **Roles and permissions** shows what each role can do. The sidebar hides sections a role cannot view. | Role | Access | | - | - | | **Owner** | Full access to everything; cannot be removed | | **Admin** | Full access to all app resources | | **Manager** | Manages daily work (Inbox, campaigns, templates, Knowledge, products, customers, orders); views and edits agents; read-only on analytics, team, settings, billing, API keys and integrations | | **Agent** | Handles conversations: works the Inbox, edits customers, creates templates, macros and tags; read-only elsewhere | | **Viewer** | Read-only access to view data | See [Team and roles](/settings/team-and-roles). ## Where things are in the app | Sidebar item | What it holds | | - | - | | **Home** | Your agent's setup until it is live, then results for a date range | | **Inbox** | All conversations and their folders | | **Customers** | Everyone who has messaged you, plus customers synced from your store | | **Orders** | Orders placed through conversations | | **Products** | The catalog synced from your store | | **Campaigns** | **One-time**, **Automated** and **Templates** | | **Reports** | Conversation and response-time analytics | | **Agent**, **Knowledge**, **Spotlight** | Under **Your agent**: your agents, their folders and articles, and quality scores for closed conversations | | The agent card | The default agent's status (**Live on WhatsApp**, **Not on WhatsApp yet**, **Not published yet**, **Stopped, out of credits** or **Stopped, plan ended**), or a WhatsApp problem (**WhatsApp needs a reconnect**, **WhatsApp messages go to another app** or **Meta is checking WhatsApp**), and the credits left | | **Integrations** | Stores, WhatsApp, Website chat and the Meta catalog | | **Help** | **Ask Nour** (in-app help chat), **Docs** and **Keyboard shortcuts** | **Settings → AI assistants** connects ChatGPT, Claude or Codex to your workspace so you can run it by chatting with them; they ask before anything irreversible and stay within your role. **Settings → API keys and webhooks** is for developers. See [AI assistants](/ai-assistants/overview) and the [API reference](/api-reference/introduction). # Popcorn mobile app Source: https://docs.trypopcorn.ai/inbox/mobile-app Handle your Inbox from your phone: sign in, work conversations, start template chats, look up customers, and get push notifications. The **Popcorn** app for iPhone and Android is the Inbox in your pocket. It is built for the moments a conversation needs a person while you are away from your desk: you get a push notification, open the conversation, and reply. Everything else, from campaigns to agent settings, stays in the web dashboard. ## What the app covers | Tab | What you can do | | - | - | | **Inbox** | Browse folders, search, open conversations, reply, take over from the AI, assign, snooze, resolve, and start new template conversations. | | **Customers** | Search your contacts, switch between **All**, **Customers**, and **Guests**, and open a customer to see their details and conversations. | | **Settings** | See your account (name, email, role and workspace), turn **Push Notifications** on or off, check whether **Biometric Authentication** is enabled, and **Logout**. | Not in the app: campaigns, templates, automated campaigns, AI agent settings, Knowledge, products and orders, billing, macros, and conversation tags. Use the web dashboard for those. ## Sign in **1. Open the app and enter your email and password** Use the same login as the web dashboard. The screen reads **Welcome back**; enter your **Email** and **Password** and tap **Sign In**. **2. Allow notifications** Shortly after signing in, the app asks for permission to send notifications. Allow it if you want to be alerted when the app is closed. Forgot your password? Tap **Forgot password?**, enter your email on the **Reset password** screen, and tap **Send Reset Link**. The link in the email stops working after 30 minutes. If the app tells you your session has expired, sign in again. If your phone supports it, the app can also unlock with Face ID, Touch ID, or a fingerprint; the **Settings** tab shows whether **Biometric Authentication** is **Enabled** or **Disabled**. ## Work conversations ### Folders The **Inbox** tab has the main folders of the web Inbox, under names that differ in places: | In the app | In the web Inbox | | - | - | | **Needs Attention** | **Needs you** | | **My Inbox** | **Mine** | | **New** | **Unassigned** | | **Later** | **Later** | | **All Messages** | **All** | | **AI** | **Agent** | | **Closed** | **Closed** | **All Messages** shows every conversation, closed ones and test conversations included, the same as **All** on the web. The app has no tab for the web's **Outreach and alerts** and **Test conversations** folders. Search matches the customer's name, phone number and email, and words in their messages. Pull down to refresh; scroll down to load more. See [Inbox overview](/inbox/overview) for what each folder means. ### Reply and take over Open a conversation. The composer has a **Message** tab and a **Comment** tab; comments are internal notes your customer never sees. * If the agent is replying to the conversation, the composer shows **Autopilot is on**. Tap **Disable Autopilot** to take over; the conversation moves to **My Inbox**. The app still uses the word Autopilot for what the web Inbox calls the agent replying, with **Take over** and **Hand back to agent**. * Outside the WhatsApp 24-hour window, the composer shows **24-hour window expired** or **Waiting for customer reply**. Tap **Send Template** and pick an approved template. See [The WhatsApp 24-hour window](/inbox/overview#the-whatsapp-24-hour-window). * A photo, video or file from the customer shows with the text they sent alongside it. * A voice note plays in the conversation with its **Transcription** under it. When it had no speech or could not be transcribed, it says "No speech in this voice note" or "Couldn't transcribe this voice note" instead. If the audio itself is unavailable, the app says "Audio unavailable" and still shows the transcription. * Swipe a message to reply to it with a quote. * Tap the attachment button to **Take Photo**, **Choose Photo/Video** (up to 10 at a time), or **Choose Document**. Add a caption if you like, then send. Messages are limited to 1,000 characters. * Tap the copy icon next to the phone number to copy it. ### Conversation actions Tap the **⋮** menu in the conversation header: | Action | What it does | | - | - | | **View Customer Details** | Opens **Customer Information**: **Conversation Summary** (tap **Generate Summary**; the app writes it in the customer's language), **Conversation Details**, **Customer Profile** with **Tags**, **Edit Customer**, and block or unblock the customer. | | **Assign** | Hand the conversation to a teammate under **Team Members**, or to the **AI Assistant**. Assigning to the AI from the app makes it reply to the customer right away. | | **Mark as Waiting** | Moves the conversation to **Later** until the customer replies. | | **Snooze** | Moves it to **Later** for **1 Hour**, **3 Hours**, until **Tomorrow at 9 AM**, or for **Next Week**. It returns to **My Inbox** when the customer replies or the time arrives. | | **Resolve Conversation** / **Reopen Conversation** | Closes the conversation, or reopens a closed one. | ### Start a new conversation Tap **+** on the **Inbox** tab to open **New Conversation**: **1. Search Customer** Enter a phone number or name. If nobody matches, tap **Create New Contact**, choose the country, and enter the phone number; the name is optional. **2. Select Sender Number** Pick which of your WhatsApp numbers sends the message, then tap **Continue to Templates**. **3. Select Template** Choose an approved template. Turn on **Continue by AI** if the agent should handle the customer's reply. **4. Start Chat** The template is sent and the conversation opens. ## Push notifications Push notifications are off until you switch on **Push Notifications** in the **Settings** tab. Switching it on turns on three notification types for you and adds your phone to them: **Unassigned messages**, **Customer replies**, and **Conversation assignments**. **Handovers** are not sent to the phone. Tapping a notification opens the conversation, and the app icon badge shows your unread count. If you later turn one of those events off in the web dashboard under **Settings → Notifications**, the phone stays quiet for it. See [Profile and notifications](/settings/profile-and-notifications). ## Related * [Work a conversation](/inbox/working-conversations) for the full set of actions in the web Inbox. * [Troubleshooting](/inbox/troubleshooting) for notifications that do not arrive. # Inbox overview Source: https://docs.trypopcorn.ai/inbox/overview How the Inbox is organised: folders, who is replying, what sends a conversation to Needs you, and the WhatsApp 24-hour reply window. The **Inbox** is where every customer conversation lives, on WhatsApp and on your website, whether your agent is replying or a teammate is. Use it to watch what the agent does, pick up the conversations it hands over, and reply yourself. ## How the Inbox is laid out Click **Inbox** in the sidebar, or press **⌘ I** on a Mac (**Ctrl I** on Windows). On a wide window you see three panes: * **The list**, on the left. Its head holds the title **Inbox** and four buttons: **Search**, **Filters**, **New conversation** and **More folders**. Under the head are the four everyday folders, any filters you applied, and the conversations. * **The conversation**, in the middle: a header with the customer, **Snooze conversation**, **Close** and **More actions**; the messages; and the composer, with a bar on top that says who is replying. * **Customer details**, on the right. On a narrower window it opens as a side panel when you click the customer's name in the header. See [Customer details and summary](/inbox/working-conversations#customer-details-and-summary). On a phone the list and the conversation are separate screens, and **Snooze conversation** and **Close** move into **More actions**. With no conversation open, the middle pane reads **Select a conversation**. ## Reading a row Each row in the list shows: * The customer's name, or their number or WhatsApp username when you have no name, and the time of the last message: the time today, **Yesterday**, a weekday, or a date. * The last message. When it came from your side it starts with the agent's mark or the teammate's first name, followed by delivery ticks. A message that failed shows **Not delivered** in red. * A status badge, the conversation tag, and for WhatsApp the last four digits of your business number the customer wrote to. * A blue dot and bold text while there are unread messages. The small mark on the avatar is the channel: **WhatsApp**, **Website widget**, **Template** (a conversation that started with a template you sent) or **API**. Conversations on your test number show a **Sandbox** badge instead. Click the avatar to select a row for [bulk assignment](/inbox/working-conversations#assign-to-a-teammate). | Badge | What it means | | - | - | | **Closed** | The conversation is closed. | | A clock and a time, such as **Tomorrow 9:00 AM** | Snoozed until then. | | **Waiting on customer** | Set aside until the customer writes back. | | **Needs you** | The agent is not replying and the conversation had activity in the last 24 hours. | | **Agent** | The agent is replying. | | **You**, or a teammate's name | A person owns the conversation and it has been quiet for more than 24 hours. | ## Folders The Inbox opens on **Needs you**. The four everyday folders sit under the list's head, and every other folder is under **More folders**. A folder you open from **More folders** shows as a chip under the everyday folders; click its **×** to go back to **Needs you**. Counts update as conversations move. | Folder | What it contains | | - | - | | **Needs you** | Every open conversation a person owns or nobody has picked up, across the whole team: **Unassigned**, assigned to any teammate, waiting on a customer, or snoozed. Its count is amber. | | **Agent** | Conversations your agent is replying to. | | **Mine** | Conversations you took over or were assigned. | | **All** | Every conversation, closed ones and test conversations included. | | **Unassigned** | Conversations the agent stopped handling that nobody has picked up. See [what sends a conversation here](#what-sends-a-conversation-to-needs-you). | | **Later** | Your conversations that are snoozed or waiting on the customer. | | **Outreach and alerts** | Conversations that began with a template you sent and that the agent is not handling. A campaign conversation appears here only once the customer replies. | | **Test conversations** | Chats you start to try your agent, such as **Try your agent** on Home. They are left out of **Reports**. | | **Closed** | Closed conversations. | **More folders** also lists your teammates under **Teammates**, each with the number of conversations they own. Pick one to see all their conversations; the list shows a **Teammate** chip you can remove. The list shows one row per customer: their most recent conversation. If the same customer also wrote to a second WhatsApp number of yours, that conversation gets its own row while it has had a message in the last 7 days. A search in **All** lists every matching conversation, older ones included. ## Who is replying The bar above the composer says who is replying and offers the one action that changes it. | The bar says | What it means | Button | | - | - | - | | The agent's name followed by **is replying**, with "Taking over pauses the agent for this conversation only" | The agent answers each customer message. The message box is greyed out until you take over. | **Take over** | | **Needs you**, with a reason: why the agent handed over (see [How the Inbox names the reason](#how-the-inbox-names-the-reason)), "Your agent is out of credits, so it isn't replying", "Your plan has ended, so your agent isn't replying", or "No one is replying and the agent is paused" | Nobody is replying. When the customer wrote last, the line adds "Customer waiting since" and the time. | **Take over** | | **You're replying**, or a teammate's name followed by **is replying**, with "The agent is paused for this conversation", "Waiting on the customer" or "Snoozed until" and a date | A person owns the conversation and the agent stays out of it. | **Hand back to agent** | | **Closed**, or **Closed by** and a name | The conversation is closed. | **Reopen** | Conversations start with the agent replying whenever an agent is connected to the number. Taking over, assigning the conversation, snoozing it, or setting it aside until the customer replies pauses the agent for that conversation only, and it moves to **Mine** for the person who did it. See [Work a conversation](/inbox/working-conversations). Every hand-off is also written into the conversation as a line, such as *Sales agent decided to hand this to your team*, *Yousef assigned this conversation to Sara*, *Yousef handed this conversation to Sales agent*, *Yousef closed this conversation* or *Yousef reopened this conversation*. When the agent hands over, the line says why, and when the agent chose to, its own reason follows under the line in quotes. Messages your team sends from the WhatsApp Business app on the same number are marked **via WhatsApp app** (see [coexistence](/channels/whatsapp-coexistence)). ## What sends a conversation to Needs you Whenever the agent stops handling a conversation, it lands in **Unassigned**, and so in **Needs you**, with the agent paused. This happens when: | Trigger | What happens | | - | - | | The agent hands over | The agent's **Hand over to your team** switch lets it pass the chat to a person, for example when the customer asks for one. It tells the customer that someone from your team will help, and that message goes out even if the customer writes again in the meantime. It can apply a conversation tag at the same time, and Slack or email alerts go out if the agent has them on. | | Spam or off-topic messages repeat | With **Block spam and off-topic chats** on, the third flagged message in a conversation hands it over. | | **Check replies before sending** gives up | With **Hand over to your team after the last retry** on, a conversation is handed over after the last failed retry. See [Check replies before sending](/agents/ai-manager). | | The customer sends media the agent is not set up to handle | If **Let the agent handle media messages** is off in **Settings → General**, an image, video or file pauses the agent for that conversation, and your **Reply to media messages** text is sent to the customer. Voice notes, locations, button replies, catalog orders and address-form answers are always handled by the agent. | | The workspace has no credits | The agent stops silently: nothing is sent to the customer. The bar says "Your agent is out of credits, so it isn't replying". | | Your plan through the Zid App Market ended | The agent stops replying, even with credits left, and nothing is sent to the customer. The bar says "Your plan has ended, so your agent isn't replying". Renewing the plan turns the agent back on. See [Top-ups, plan changes and renewal](/billing/top-ups-and-renewal). | | No agent is set up for the number | The conversation is handed to your team without a message to the customer. | | The agent's reply failed | The conversation is handed to your team, and the customer is told "One moment — let me get a team member to help you with this." (in Arabic when they write in Arabic), unless someone on your team has already written to them. | | A template could not be delivered | A template sent to one customer, outside a campaign, failed for good. The agent pauses so a person can follow up, and the conversation moves up the list. Popcorn does not resend it. | ### How the Inbox names the reason When the agent stops, the bar above the composer says why after **Needs you**, and a line in the conversation records it. "Sales agent" stands for your agent's name. | The bar says | The line in the conversation says | Trigger | | - | - | - | | "Sales agent decided to hand this to your team" | The same, with the agent's own reason under it in quotes when it gave one | The agent handed over | | "Sales agent stopped after attempts to change its instructions" | "Sales agent handed this to your team after attempts to change its instructions" | Spam or off-topic messages repeated | | "Sales agent couldn't read an attachment" | "Sales agent couldn't read an attachment and handed this to your team" | Media the agent is not set up to handle | | "Sales agent ran out of credits" | "Sales agent ran out of credits and handed this to your team" | No credits | | "Sales agent stopped because your plan ended" | "Your plan ended, so Sales agent handed this to your team" | Your plan ended | | "No agent was set to reply" | "No agent was set to reply, so this came to your team" | No agent for the number | | "Sales agent couldn't write a reply" | "Sales agent couldn't write a reply and handed this to your team" | The agent's reply failed | Hand-overs written before the Inbox recorded the reason read "Sales agent needed help from your team", and the bar says "Sales agent handed this to your team". Choose who gets told in **Settings → Notifications** (**Unassigned messages** and **Handovers**). See [Profile and notifications](/settings/profile-and-notifications). The agent's handover, spam and retry switches are covered in [Capabilities](/agents/capabilities) and [Check replies before sending](/agents/ai-manager). ## The WhatsApp 24-hour window WhatsApp only lets a business send free-form messages within 24 hours of the customer's last message. Popcorn shows where you stand in a line above the message box: * **WhatsApp reply window:** a countdown such as "3h 20m left". It turns amber when less than an hour is left. * "It's been more than 24 hours since the customer's last message. WhatsApp only allows templates until they write again." * "The customer hasn't replied yet. WhatsApp only allows templates until they write." This shows on a conversation your business started, until the customer writes. When the window is closed the message box is greyed out and **Send template** replaces **Send**. Pick one of your approved templates; when the customer replies, the window opens again. Notes still work. See [Send a template outside the window](/inbox/working-conversations#send-a-template-outside-the-window). Website chat and API conversations have no 24-hour window. You can reply to them at any time after the customer's first message, and until then the line reads "The customer hasn't written yet. You can reply after their first message." If the conversation's WhatsApp number is disconnected, the line says "WhatsApp is disconnected, so replies can't reach customers" and a **Reconnect** button opens the number's connection. Without permission to reconnect, it tells you to ask your account owner or an admin. While Meta is checking a number, it reads "Meta is checking this WhatsApp number, so replies are paused for a few minutes." If customers' messages to the number go to another app, such as a previous provider still connected to it, the line reads "Customers' messages to this number go to another app, so a reply from here may not reach them. Choose Popcorn AI in Conversation routing in Meta Business Suite." You can still send. See [Channel troubleshooting](/channels/troubleshooting). ## Closed and reopened * **Close**, in the conversation header, moves the conversation to **Closed**, shows "Conversation closed", and opens the next conversation in the list. Agents with **Close resolved chats** also close their own idle conversations; see [Capabilities](/agents/capabilities). * **Reopen**, in the bar above the composer, brings it back to **Unassigned**, or to **Agent** if the agent was replying when it closed. * A customer who writes after a conversation was closed starts a new conversation, which the agent answers. The closed one stays in **Closed** until you reopen it. ## Next > **[Work a conversation](/inbox/working-conversations)** > > Take over, reply, send templates and products, snooze, close, and block. > **[Tags and macros](/inbox/tags-and-macros)** > > Prioritise handovers with tags and reuse your best replies. > **[Mobile app](/inbox/mobile-app)** > > Handle the Inbox from your phone with push notifications. > **[Troubleshooting](/inbox/troubleshooting)** > > Replies that cannot be sent, the agent not replying, missing notifications. # Conversation tags and macros Source: https://docs.trypopcorn.ai/inbox/tags-and-macros Create conversation tags with priorities, let the agent tag handovers, filter and sort by tag, and reuse replies with macros. Conversation tags tell your team what a conversation is about and how urgent it is. Your agent applies one when it hands a conversation over, and you can filter and sort the Inbox by tag. Macros are saved replies that anyone on your team can insert by typing a shortcut. Both are set up under **Settings** and used in **Inbox**. Who can create, edit and delete them depends on the role; see [Team and roles](/settings/team-and-roles). ## Conversation tags ### Create a tag **1. Open Settings → Conversation tags** Tags are listed with their **Priority** and a **Created** time, with the description under the name. **2. Click New tag** In the **New tag** dialog, enter a **Name** (up to 50 characters, no commas, unique in your workspace). Choose a **Priority**: **High**, **Medium** or **Low**. Pick a **Color** (blue, green, yellow, red, purple, cyan, pink or orange) and, if you like, add a **Description (optional)**. The **Preview** shows how the tag will look. **3. Click Create tag** You see "Tag created". The tag is available in the Inbox, and offered to your agents' handover, straight away. To change a tag, click its row, edit it and click **Save tag**. To remove one, open the **⋯** menu on its row, choose **Delete** and confirm with **Delete tag**. Conversations keep their messages but lose the tag, and this can't be undone. > [!TIP] > > The agent chooses between your tag names, so name each tag for the reason a customer needs a person, such as "Refund request" or "Payment problem". The **Description** is there for your team. ### How the agent tags handovers When an agent with **Hand over to your team** switched on hands a conversation over, it picks the most relevant of your tags and applies it. If the agent has **Handover topics** on its **Handoff** tab, each topic can name its **Conversation tag**, and the agent applies that tag to chats about the topic. The tag shows on the conversation's row in the list and beside the customer's name in the header, and its name goes into the agent's Slack alert if it sends one. You do nothing else: tags you create, rename or delete are updated in every agent's handover automatically. See [Hand over to your team](/agents/capabilities#hand-over-to-your-team). ### Tag a conversation yourself In the conversation header, open **More actions** and choose **Conversation tag…**. It appears once you have at least one tag. Pick a tag, or **Remove tag** to clear it. A conversation has one tag at a time. If the change fails you see "Couldn't update the tag" or "Couldn't remove the tag". On a wide window the header shows the current tag beside the customer's name. In the list it is a coloured badge on the row, with a flag on **High** priority tags. ### Filter and sort by tag Click **Filters** in the list's head, then: * **Tag** limits the list to one tag. **All tags** clears it. * **Sort by** → **Priority** lists **High** tags first, then **Medium**, then **Low**, then conversations without a tag, most recent first within each group. **Recent** puts the latest activity first. Click **Apply**. Both settings are kept in the page address, so a shared link opens the same list. In **Reports**, **By tag** and **Resolved by the agent, by tag** break the numbers down by tag; see [Reports](/analytics/reports). ## Macros ### Create a macro **1. Open Settings → Macros** Macros are listed with their **Macro** name, **Shortcut** and **Last updated** time. **Search macros** filters the list. **2. Click New macro** In **Create macro**, enter a **Name**, a **Shortcut** and the **Message**. **3. Add smart variables** Under **Smart variables**, click **Customer name** or **Sender name** to put `{{customer_name}}` or `{{agent_name}}` at the cursor. They are filled in when someone uses the macro. **4. Click Create macro** You see "Macro created". It is available to everyone on your team straight away. The **Shortcut** takes letters, numbers, hyphens and underscores, and must be unique in your workspace; case does not matter. You trigger it with a leading **/**, so `welcome` becomes `/welcome`. Otherwise you see "Use only letters, numbers, hyphens or underscores." or "That shortcut is already in use. Choose something different." Under **Need inspiration?** the dialog offers two ready-made replies, **Warm welcome** (`/welcome`) and **Friendly follow-up** (`/followup`). Click **Use this example** to start from one. To change a macro, click its row, edit it and click **Save macro**. To remove one, open the **⋯** menu on its row, choose **Delete** and confirm with **Delete macro**; it disappears for everyone on your team. ### Use a macro in a conversation 1. On the **Reply** tab, click **Insert macro**, or type **/** at the start of the message or after a space. 2. The panel opens with **Search macros**, your **Recent** macros first (the last six you used in this browser), then **All macros**. Keep typing to search by name, shortcut or message. 3. Use ↑ and ↓ to move and press **Enter** to insert. The macro lands at the cursor. 4. Edit the text if you need to, then send. `{{customer_name}}` becomes the customer's name, first and last, and `{{agent_name}}` becomes yours, or the part of your email before the @ if you have no name set. When a name is missing the variable becomes "there" for the customer or "our team" for you. Macros work on **Reply**, not on **Note**. With none saved the panel reads **No macros yet**, and when nothing matches your search it reads **No matches**; both offer **Manage macros**, which opens **Settings → Macros**. ## Related * [Work a conversation](/inbox/working-conversations) * [Capabilities](/agents/capabilities) for the handover settings * [Team and roles](/settings/team-and-roles) for who can change tags and macros # Inbox troubleshooting Source: https://docs.trypopcorn.ai/inbox/troubleshooting Fixes for replies that cannot be sent, the agent not replying, missing conversations, media the agent cannot handle, and notifications. Most Inbox problems come down to one of four things: the WhatsApp 24-hour window, who is replying, a filter you forgot about, or a notification setting. Find your symptom below. ## I cannot type a reply > **The box says Take over to reply** > > The agent is replying, and the bar above the composer says so. Click **Take over**. You see "You're replying now. The agent is paused for this conversation." and the box unlocks. See [Take over from the agent](/inbox/working-conversations#take-over-from-the-agent). > **The box says Reopen to reply** > > The conversation is closed. Click **Reopen** in the bar above the composer. If the customer writes after a conversation was closed, they start a new conversation instead. > **The line above the box says it has been more than 24 hours** > > More than 24 hours have passed since the customer's last message, so WhatsApp no longer accepts free-form replies. Click **Send template** and send an approved template. When the customer answers, the window opens again and you can type normally. See [The WhatsApp 24-hour window](/inbox/overview#the-whatsapp-24-hour-window) and [Send a template outside the window](/inbox/working-conversations#send-a-template-outside-the-window). > **The line says the customer hasn't replied or written yet** > > Until the customer's first message, the box stays closed on every channel. On a WhatsApp conversation your business started with a template, you can send another template with **Send template**, but not a plain message. On Website chat and API conversations, wait for the customer's first message. > **The line says WhatsApp is disconnected** > > The number this conversation runs on cannot send, so nobody's reply would reach the customer, whether the agent or a teammate is replying. Click **Reconnect** to open the number's connection. If there is no button, the line tells you to ask your account owner or an admin. While it reads "Meta is checking this WhatsApp number, so replies are paused for a few minutes", wait and check again. See [Channel troubleshooting](/channels/troubleshooting). > **The line says customers' messages go to another app** > > Another app, such as a previous provider, is still connected to the number and receives its customers' messages, so your agent does not see them and a reply from the Inbox may not reach the customer. You can still type and send. If a send fails with "Another app connected to this number handles this customer's chat, so Popcorn AI can't reply in it.", your text stays in the box, but sending again won't work until you choose Popcorn AI under Conversation routing in Meta Business Suite. Templates and campaigns still go out meanwhile. See [Channel troubleshooting](/channels/troubleshooting). > **I cannot attach a picture or file** > > Attachments, product cards and templates work only in WhatsApp conversations. In Website chat and API conversations those tools are dimmed and show "Only in WhatsApp conversations". They are also off while the box is locked, so take over first, or send a template if the window has closed. ## A message shows Not delivered A message that did not go out shows **Not delivered** in red beside its time, and a red note under it says why and what to do. The note ends with the Meta error code, such as "Meta error #131047", and some have a **Learn more** or **Open Meta billing** button. For a code Popcorn does not explain itself, the note shows Meta's own title and explanation. The ones it explains: | The note says | What to do | | - | - | | 131047: "The 24-hour reply window has closed" | The customer last wrote over 24 hours ago. Send an approved template. | | 131026: "This number can't be reached" | They may not have WhatsApp, or the number is wrong. | | 131049: "Meta limited this marketing message" | Meta does not deliver marketing templates to customers who have not engaged lately. Send order updates and reminders as a utility template instead. | | 131050: "The customer opted out of marketing" | You cannot send them marketing templates unless they opt back in. | | 131048: "Your account was flagged for spam" | Too many customers reported your messages, so Meta is limiting your sending. Send less often. | | 131053: "The media couldn't be uploaded" | Check the file's format (JPEG, PNG, MP4, PDF) and size, then send again. | | 131037: "WhatsApp won't send from this number until its display name is approved" | Sending again won't help until it is. Open **Integrations**, then **WhatsApp**, then **Profile**, to see where it stands. | | 131031: "Your WhatsApp account is locked" | Meta locked it, usually over a policy issue. Review it in Business Manager and appeal if needed. | | 131042: "A payment issue on your WhatsApp account" | Add a payment method or pay the balance in Meta billing, then send again. **Open Meta billing** takes you there. | | 131000: "A temporary error on Meta's side" | Try sending it again in a few minutes. | | 130472: "This customer is in a Meta test" | Meta is limiting delivery to this number for now. Try again later. | A product send that fails reads "No products to send" (the agent had no product to show, so nothing went out) or "The product cards weren't delivered" (send them again, or share them yourself; the note says whether the customer got the products as a text list instead). A send where only some products reached the customer is not a failure: the message reads, for example, "9 of 10 delivered to the customer", with a badge on each product that did not go as a card. The mark updates as WhatsApp reports, without a reload: if WhatsApp later reports the message as sent, **Not delivered** and the note go away. Popcorn does not resend a failed message on its own. When a template sent to one customer, outside a campaign, fails for good, the agent pauses for that conversation and it moves up the list; if the agent was handling it, or it was in **Outreach and alerts**, it moves to **Unassigned**, so someone can follow up. Send the message again yourself once the cause is fixed. For campaign messages, see [Delivery and reachability](/campaigns/delivery-and-reachability). ## The agent is not replying > **A person owns the conversation** > > Once a person takes over, assigns the conversation, snoozes it, or sets it aside until the customer replies, the agent stays out of it. To hand it back, click **Hand back to agent** in the bar above the composer, or open **More actions** and choose **Hand to agent**, then pick **Reply now** or **Wait for the customer**. See [Hand back to the agent](/inbox/working-conversations#hand-back-to-the-agent). > **Conversations keep landing in Unassigned** > > Open the conversation and read the bar above the composer and the last line between the messages: they say why the agent stopped, such as "Sales agent decided to hand this to your team" (with the agent's own reason in quotes) or "Sales agent couldn't read an attachment", or who assigned it. Every reason is listed in [How the Inbox names the reason](/inbox/overview#how-the-inbox-names-the-reason). If the agent hands over too often, review its **Hand over to your team** and **Block spam and off-topic chats** settings in [Agent capabilities](/agents/capabilities) and **Check replies before sending** in [Check replies before sending](/agents/ai-manager). > **The agent went quiet and the customer got no answer** > > When the workspace runs out of credits, the agent stops without sending anything to the customer, and the bar reads "Your agent is out of credits, so it isn't replying". Check your balance under [Plans and credits](/billing/plans-and-credits). When your plan through the Zid App Market has ended, the agent stops the same way, even with credits left, and the bar reads "Your plan has ended, so your agent isn't replying"; renew the plan to turn it back on. A conversation is also handed to your team without a message to the customer when no agent is set up for the number ("No agent was set to reply"); check the agent's **Channels** tab under [Connect knowledge, tools, channels and notifications](/agents/connect-knowledge-tools-channels). When the agent's reply fails ("Sales agent couldn't write a reply"), the customer is told a team member will help, so reply to them yourself. > **The customer sent a photo, video or file and the agent stopped** > > If **Let the agent handle media messages** is off in **Settings → General**, an image, video or file pauses the agent for that conversation and moves it to **Unassigned**. If you filled in **Reply to media messages**, the customer receives that text first. Turn the setting on to let the agent handle media. Voice notes, locations, button replies, catalog orders and address-form answers are always handled by the agent. See [Workspace settings](/settings/workspace). ## I cannot find a conversation > **It is not in the folder I expect** > > Check the chips under the folders: a **Teammate**, **Tag** or date filter, or **Priority** sorting, may still be on. Remove a chip, or open **Filters** and click **Clear**. **Search** switches the list to **All**, so clear it to go back to your folder. > **I see only one conversation for a customer** > > The list shows one row per customer: their most recent conversation. A second conversation on another of your WhatsApp numbers gets its own row while it has had a message in the last 7 days. A search in **All** lists every matching conversation, older ones included. > **The order looks wrong** > > With **Sort by** → **Priority**, tagged conversations come first by priority and untagged ones last. Switch back to **Recent** to sort by the latest activity. > **A snoozed conversation came back early** > > A customer reply ends the snooze and returns the conversation to **Mine**. The same happens to conversations you set aside until the customer replies. > **I reopened a conversation and it went to Unassigned** > > Reopening sends a conversation to **Unassigned**, or to **Agent** if the agent was replying when it was closed. Click **Take over** to move it to **Mine**. > **A campaign recipient is not in the Inbox** > > Campaign conversations appear in the Inbox only once the customer replies. Until then, follow the campaign from **Campaigns**. See [Send a campaign](/campaigns/send-a-campaign). > **I cannot see a teammate's conversations** > > **Mine** and **Later** show only your own. Open **More folders** and pick the teammate under **Teammates**, or use **Filters** → **Teammate**. > **The customer was deleted** > > Deleting a customer under **Customers** (including a bulk delete that includes customers with conversations) does not delete their conversations. Each one stays in the Inbox with its messages, listed as **WhatsApp contact** (or **Guest** for Website chat) instead of the customer's name. See [Delete customers](/customers/overview#delete-customers). ## The customer shows as @username or "Phone number not shared" The customer contacted you through a WhatsApp username without sharing their phone number. You can chat normally, but authentication templates cannot be sent to them. In the template picker, click **Ask the customer for their number**, or choose a marketing or utility template. ## A voice note has no transcription "No speech in this voice note" means Popcorn heard no words in the recording; "Couldn't transcribe this voice note" means the transcription failed. Play the voice note to hear it yourself. The agent is told the same, so it can ask the customer to send it again or type the message. A transcription that is still being written appears on its own when ready, without a reload. ## Notifications do not arrive > **Check the event and channels** > > Go to **Settings → Notifications**. Each event (**Unassigned messages**, **Customer replies**, **Conversation assignments**, **Handovers**) has its own switch and channels: **In-app**, **Browser** and **Sound**. By default, workspace admins get all four events and other teammates get only **Customer replies** and **Conversation assignments**; **Sound** starts on only for those two. See [Profile and notifications](/settings/profile-and-notifications). > **Browser notifications and sound never fire** > > Your browser must allow notifications for Popcorn: click **Allow** on the **Notifications** page, or allow them in your browser's site settings if it says your browser blocks them. Browser notifications and the sound only fire while the Popcorn tab is hidden or its window is not focused, and nothing fires while you are on the Inbox page or reading that conversation. > **Nothing arrives on my phone** > > In the mobile app, switch on **Push Notifications** under **Settings** and allow notifications for Popcorn in your phone's settings. Push covers **Unassigned messages**, **Customer replies** and **Conversation assignments**; an event switched off under **Settings → Notifications** in the web dashboard stays off on the phone. See [Popcorn mobile app](/inbox/mobile-app). > **I want Slack or email alerts for handovers** > > Those are set per agent, not per person, in the **Alerts** panel on the agent's **Handoff** tab. See [Connect knowledge, tools, channels and notifications](/agents/connect-knowledge-tools-channels). ## Related * [Inbox overview](/inbox/overview) * [Work a conversation](/inbox/working-conversations) * [Channel troubleshooting](/channels/troubleshooting) for a number that will not connect or deliver. # Work a conversation Source: https://docs.trypopcorn.ai/inbox/working-conversations Take over from the agent, reply, send templates and products, add notes, snooze, close, block, read customer details, and use keyboard shortcuts. Most conversations are handled end to end by your agent. This page covers what you do when one needs a person: taking it over, replying, and moving it through your day. Everything here happens in **Inbox**. ## Before you start * A connected WhatsApp number or Website chat. See [Channels](/channels/overview). * For messages outside the 24-hour window and for new WhatsApp conversations, at least one approved template. See [Templates](/campaigns/templates). ## Find a conversation * **Search**, the magnifier in the list's head, opens a field in place of the title. It switches the list to **All** and matches the customer's name, phone number and email, and words in the messages, in closed and older conversations too. The results stay in the list while you assign, move or reply to them. Clear the search to return to the folder you came from. * **Filters** opens a panel with **Teammate**, **Tag** (shown once you have conversation tags), **Sort by** (**Recent** or **Priority**) and **Date range** (**From**, **To**, **Include time**, and **Filter dates by** **Last updated** or **Created date**). Click **Apply**. The button shows how many filters are on, and each shows as a chip under the folders that you can remove; **Clear** removes them all. * **Priority** sorts by tag priority first (**High**, **Medium**, **Low**, then untagged). See [Tags and macros](/inbox/tags-and-macros). The folder, search, tag, teammate and sort are kept in the page address, so a reload or a shared link opens the same list. ## Take over from the agent **1. Open the conversation** Conversations the agent is replying to are in **Agent**. The bar above the composer reads "Sales agent is replying" (your agent's name) and the message box says **Take over to reply**. **2. Click Take over** You see "You're replying now. The agent is paused for this conversation." The conversation moves to **Mine** and the box unlocks. **3. Reply** Type in the box and click **Send**. Taking over pauses the agent for this conversation only. If the customer has not written yet, **Take over** assigns the conversation to you instead. ## Assign to a teammate In the conversation header, open **More actions**, choose **Assign to…** and pick a teammate. The agent pauses, the conversation moves to that teammate's **Mine**, a line in the conversation records who assigned it, and they get a **Conversation assignments** notification if it is on. To assign several at once, click the avatars of the rows you want. The list's head turns into a bar showing how many are selected, with **Assign to** and **Clear**. Choose a teammate to assign at once, or **Agent** to [hand them to the agent](#hand-back-to-the-agent). If some fail you see "Couldn't assign" with a count, and those rows stay selected so you can try again. ## Hand back to the agent Use **Hand back to agent** in the bar above the composer while a teammate is replying. When nobody is replying, or the conversation is closed, use **More actions** → **Hand to agent**. The **Hand to agent** dialog asks **When should the agent reply?** | Choice | What happens | | - | - | | **Reply now** | "The agent answers the customer's last message now." Use it on WhatsApp conversations. | | **Wait for the customer** | "The agent replies when the customer writes next." Use it on Website chat conversations. | Click **Hand to agent**. You see "Handed to the agent" and the conversation moves to **Agent**. For several conversations, choose **Assign to** → **Agent** in the bulk bar: it asks "Hand 3 conversations to the agent?" with the choices **Reply now** and **Wait for the customer's next message**. ## Reply The composer has two tabs, **Reply** and **Note**. Type in the box and click **Send**, or press **⌘ Enter** (**Ctrl Enter** on Windows). **Enter** alone adds a new line. Text you have typed but not sent stays in the box for that conversation while the browser tab is open. If a send fails you see "Couldn't send message" with the reason, and your text is still in the box; see [Inbox troubleshooting](/inbox/troubleshooting). Hover a message to **Copy message** or **Reply to message**. A bar above the box shows what you are answering, with **Cancel reply**. The tools under the box, shown on the **Reply** tab: | Tool | What it does | | - | - | | **Templates** | Opens the template picker; see [Send a template outside the window](#send-a-template-outside-the-window). | | **Send a product** | Opens **Choose products**: search, pick, click **Add** with a count. The products appear as chips under the box; click **Send** to send them as product cards. | | **Attach a file** | Pictures (JPEG, PNG), video (MP4), documents (PDF, Word, plain text) and audio (MP3, OGG, M4A). Pick several at once; each shows as a chip you can remove before sending. | | **Insert macro** | Opens your saved replies; see [Tags and macros](/inbox/tags-and-macros#macros). | | **Emoji** | Opens the emoji picker. It is hidden on phones, which have their own keyboard. | Templates, attachments and product cards work only in WhatsApp conversations; elsewhere the tools are dimmed with "Only in WhatsApp conversations". Product cards need your catalog synced to WhatsApp, and one card carries at most 30 products; see [Products in WhatsApp](/channels/whatsapp-catalog). A product that cannot go in a catalog card, for example because WhatsApp hasn't reviewed it yet, can go as an image card instead, and two or more products sent that way with a photo and a link go together as one carousel the customer swipes through. After sending, the message says how many products reached the customer, and a product that did not go as a catalog card shows a badge (**Not in catalog**, **Failed to send**, **Sent as image**, **Sent in a carousel**, **Sent as text** or **Not confirmed**) with a line saying why, such as "WhatsApp hasn't reviewed this product yet" or "WhatsApp didn't approve this product". Messages from your side show a delivery state: a clock while **Sending**, one tick for **Sent**, two for **Delivered**, two in blue for **Read**, and **Not delivered** in red. The marks change as WhatsApp reports them, without a reload, and if WhatsApp reports a message as sent after all, **Not delivered** and its note go away. Website chat conversations show no ticks, and API conversations show only **Sent**. A failed message carries a note under it that says why and what to do; see [Troubleshooting](/inbox/troubleshooting). ## Send a template outside the window When the message box is greyed out because the 24-hour window is closed, click **Send template**. **Templates** in the tools row opens the same picker. **1. Pick a template** In **Choose a template**, search under **Search templates** and choose one under **Approved templates**. **Send from** shows the WhatsApp number the conversation runs on and cannot be changed. **Message preview** shows what the customer will see. **2. Decide who continues** Switch on **Agent replies when the customer answers** if the agent should handle the reply. Leave it off to keep the conversation with your team. **3. Send it** Click **Send template**. If the template has variables the button reads **Next**: fill in the values under **Fill in the template**, then click **Send template**. You see "Template sent". The template starts a new conversation with the customer, marked **Template**, and Popcorn opens it. With the switch off it is in **Unassigned** and **Outreach and alerts**. With it on, the conversation moves to **Agent** once the agent has answered the customer's reply. The customer's reply opens a fresh 24-hour window. A blocked customer, or one who has unsubscribed, cannot be sent a template from the Inbox. Authentication templates cannot go to a customer who has not shared their phone number on WhatsApp (they show as an @username). The picker says **This template needs a phone number**; click **Ask the customer for their number**, or choose a marketing or utility template. ## Start a new conversation Click **New conversation** in the list's head. In the dialog, choose **Existing contact** and pick one from **Matching contacts**, or **New contact** and enter **First name**, **Last name** and **Phone number** with its country code. A number you already have selects that contact instead. Click **Select template**, then follow the steps above; the last button reads **Start chat**. A new contact is saved to [Customers](/customers/overview) as soon as you click **Select template**. ## Add an internal note Switch to the **Note** tab, write under "Write a note. Only your team sees it." and click **Add note**. Notes appear in the conversation, marked **Note**, are never sent to the customer, and work on any conversation, including ones the agent is replying to. ## Snooze or set aside Click **Snooze conversation** (the clock in the header). Under **Snooze until**, choose **The customer replies** (it shows as **Waiting on customer**) or a time: **1 minute**, **1 hour**, **4 hours**, **Tomorrow at 9:00 AM**, **3 days**, **1 week** or **1 month**. Click **Snooze**. The conversation moves to **Later** and the agent stays out of it. The bar above the composer says "Snoozed until" and the time, or "Waiting on the customer". It returns to **Mine** when the customer replies, or when the time you picked arrives. ## Close and reopen Click **Close** in the header. You see "Conversation closed", the conversation moves to **Closed**, and the next one opens. On a closed conversation the box says **Reopen to reply** and the bar above it offers **Reopen**, which brings the conversation back to **Unassigned**, or to **Agent** if the agent was replying when it closed. A customer who writes after you closed it starts a new conversation. ## Block a customer In the customer details, open **Customer actions** and choose **Block customer**. The dialog **Block this customer?** says "They will no longer be able to message you. You can unblock them later." Add a **Reason (optional)** and click **Block customer**. A **Blocked** badge appears by their name. Use **Unblock customer** in the same menu to reverse it. ## Customer details and summary Click the customer's name in the header (or find the panel docked on the right) to see: * The name, **Customer since**, and **Customer actions**: **Edit customer**, **Open customer profile** and **Block customer**. Under them, the phone number, WhatsApp username, email and place. * **Spent**, **Orders** and **Avg. order**, when your store sync has them. * A **Quality score** card with **Details**, on closed conversations the agent's replies scored below 3.5 out of 5. It lists **Understanding**, **Resolution**, **Accuracy**, **Communication**, **Instructions** and **Helpfulness**, plus the customer's sentiment and how the conversation ended. See [Check replies before sending](/agents/ai-manager). * **Conversation summary**. Click **Summarize conversation** to have the agent write a recap in two or three sentences: what the customer wanted, what they were told or what was done, and anything still open. Popcorn writes one only when you ask. It is written in the language your dashboard shows (**Language** in the workspace menu), whatever language the conversation is in. It then shows above the messages as **Summary**, with **Summarize again** to write it afresh and **Hide summary**. * **Orders through Popcorn AI**: the latest five, with **View all**. * **Customer tags**: **Add tag** opens **Edit tags**, and each tag has a **×** to remove it. These describe the person, unlike the [conversation tag](/inbox/tags-and-macros#conversation-tags). * **Store note**, when your store has one. * **Conversation**: **Status**, **Started from**, **Started on**, **Last seen**, **Assignee** (**Agent**, a teammate, or **Unassigned**), **WhatsApp line**, and **Customer ID** for API conversations. ## See what the agent did Under an agent reply, **Used** followed by a tool's name, or **Searched the knowledge base**, shows what it relied on. Click **Sources** with a count, or **Details**, to open **Message source**. **Tool used** names the tool behind the reply. When the agent drew on your knowledge, **Knowledge used** links each article it cited, or the folder it searched. When it used a built-in action, **What the agent did** says so in a sentence, such as looking up the customer's orders, searching your catalog to recommend products, or handing the conversation to your team. The lines between messages record every hand-off, close and reopen, and why the agent handed over, so you can trace how the conversation reached you; see [How the Inbox names the reason](/inbox/overview#how-the-inbox-names-the-reason). Voice notes from the customer show their **Transcription** under the player as soon as it is ready, without a reload. When a voice note had no speech, or could not be transcribed, it says "No speech in this voice note" or "Couldn't transcribe this voice note" instead. The agent is told the same, so it can ask the customer to send it again or type it. When a follow-up was due but the agent decided the conversation needed none, a line says why: "Follow-up skipped: the conversation had ended", "Follow-up skipped: the customer said no", "Follow-up skipped: the sender isn't a customer", "Follow-up skipped: the chat was handed to your team" or "Follow-up skipped: nothing left to follow up on". These lines are for your team only. See [Follow-ups](/agents/capabilities#follow-ups). ## Keyboard shortcuts Open the list with **?**, or from **Keyboard shortcuts** under **Help** in the sidebar. Shortcuts work anywhere except while you type in a field, and **G** sequences are ignored while a dialog or menu is open. | Shortcut | Action | | - | - | | **⌘ I** or **Ctrl I** | **Go to inbox** | | **⌘ B** or **Ctrl B** | **Collapse or expand the sidebar** | | **/** | **Jump to the chat box**, in the Inbox and in the agent's test chat | | **G** then **S**, **O**, **A** or **T** | **Go to settings**, **Go to orders**, **Go to agents**, **Go to tools**. Press the second key within a second. | | **?** | **Show keyboard shortcuts** | | **⌘ Enter** or **Ctrl Enter** | Send, in the composer | | **/** at the start of a word, in the composer | Opens **Insert macro** | ## Related * [Inbox overview](/inbox/overview) for folders and what sends a conversation to **Needs you**. * [Tags and macros](/inbox/tags-and-macros) for triage and saved replies. * [Customers](/customers/overview) for the full customer profile and order history. # Store health Source: https://docs.trypopcorn.ai/integrations/commerce-health Read the Store health panel on Integrations: overall score, the five categories, statuses, problems and what to do about each. **Store health** tells you whether your connected store is actually working for the agent: can Popcorn reach the store, is the catalog syncing, are orders being created, are store updates and campaign triggers arriving, and are order lookups succeeding. It sits beside your stores on **Integrations** and appears once a store is connected. Check it when customers report checkout problems, when products look stale, or after reconnecting a store. ## The panel The title carries the overall status as a badge: **Healthy**, **Partly working**, **Not working**, **No recent activity** or **Not configured**. Under it, a line names the platform and the period, for example "Shopify · start to end". Pick the period with **Period**: **1 hour**, **24 hours**, **7 days** or **30 days** (the default is **24 hours**), and click **Refresh** to reload. If the panel can't load you see "Couldn't load store health" with **Try again**. * **Overall score** is the average success rate across the categories that had attempts in the period, shown as "N / 100". The badge is the worst status among the five categories. * When nothing happened in the period, the panel says "No store activity in this period. Try a longer period." If something still needs you, such as the connection, it says "No store activity in this period, but something below needs your attention." ## Categories | Category | What it measures | | - | - | | **Connection** | Whether Popcorn can resolve exactly one active store from your credentials. | | **Catalog** | Product imports from the store (full syncs and product notifications). | | **Checkout and order creation** | Orders the agent tried to create, split by path: **Payment link**, **Cash on delivery** or **Default** (bank transfer and anything else). An attempt whose outcome the store did not confirm either way is recorded as **Skipped** and does not count against the success rate. | | **Store updates and automations** | Store notifications Popcorn received and processed, including the triggers behind automated campaigns. | | **Order status and tracking** | Order lookups the agent performed for customers. | Each category is a row with a status badge, "Success" and its percentage, and **View details**. The rows that need attention come first. A row that is **Not working** or **Partly working** also says what it means for customers and what to do next. ## Statuses | Status | Meaning | | - | - | | **Healthy** | No failures among the counted attempts in the period (**Skipped** attempts are not counted). | | **Partly working** | At least one failure, or success below 95%. Commerce continues with reduced reliability. | | **Not working** | Success below 50%. Customers or workflows are likely blocked. | | **No recent activity** | Nothing happened in this category during the period. Change the period, run a sync, create a test order, or wait for store activity. | | **Not configured** | No store is connected. Connect one from **Integrations**. | **Connection** is special: it is **Not configured** without a store, **Partly working** with **More than one store connected** when credentials exist for more than one platform, and **Healthy** otherwise. ## What it means for customers Under a row that needs attention, one line explains the effect of the worst recent failure. **View details** names the same thing under **Impact**. | Impact | What the row says | | - | - | | **None** | No effect on selling. | | **Customers need to add details** | "Some customers are missing details they need to finish their order." For example, a required product option. | | **Some customers affected** | "Some attempts are failing, so some customers may not finish." | | **Customers can't finish** | "Customers can't finish this step until it's fixed." | ## Problems and what to do **Most common problem** names the most frequent problem in the period, and the line under the row says what to do. | Problem | Where it appears | What to do | | - | - | - | | **Store access failed** | Catalog, Checkout | "Reconnect your store above." Click **Reconnect** on the store's row. | | **Store account lacks permission** | Catalog, Order status and tracking | "The account that connected your store is missing a permission. Reconnect your store above with the store owner's account." Zid checks the permissions of the person who connected the store, so products can sync while order lookups are refused. Click **Reconnect** and approve with the store owner's account, or give that person the permission in your store. See [Connect Zid](/integrations/zid#ongoing-updates). | | **Store limited requests** | Catalog | "Your store is limiting requests. Wait a few minutes, then resync." The store's API refused requests; this can also delay a resync. | | **No shipping option** | Checkout | "Check that your store ships to the customer's area." Sync the store's shipping methods or add delivery coverage; see [shipping and payment](/settings/shipping-and-payment). | | **Missing a required product option** | Checkout | "Review required product options and the questions your agent asks at checkout." The order needs an option the agent did not collect. | | **Store couldn't create the order** | Checkout | The store rejected the order or returned no order reference. Open **View details** for the message and check the order in [Orders](/orders/overview). If you need more help: "Contact Popcorn AI support and share the details." | | **Store update wasn't processed** | Store updates and automations | "Contact Popcorn AI support and share the details." A store notification or campaign trigger could not be processed. | | **Couldn't get tracking** | Order status and tracking | "Contact Popcorn AI support and share the details." The lookup needs an order number or phone number that exists in the store. | | **More than one store connected** | Connection | "More than one store is connected. Contact Popcorn AI support to remove the one you don't use." See [one active store](/integrations/overview#one-active-store). | | **Unknown problem** | Any | The problem did not match a known one. Open **View details** for the message. "A transient dependency interrupted product sync." means a temporary problem stopped a full sync; click **Resync products** to run it again. | ## View details Click **View details** on a category to open a dialog titled with the category and described as "Details to share with Popcorn AI support". It shows: * **Success**, **Attempts** and **Failures** for the period. * **Last success**, **Last failure**, **Most common problem** and **Impact**. A value that doesn't exist reads **None**. * **Recent events**. Each event shows the operation and path, for example "Sync products, Product sync" or "Create order, Cash on delivery"; a short message, or **No message recorded**; and a badge: **Success**, **Failure** or **Skipped** (an attempt that was not carried out, or whose outcome was not confirmed). Below it are **Event ID**, **Popcorn AI ID** (the Popcorn order or sync request), **Store ID** (the store's order or product reference), **Problem** and **Created**. Events never contain customer names, phone numbers, emails or addresses, so you can share them with support as they are. If a category has no events, the dialog says "Nothing recorded in this period". ## Working with the panel * After **Reconnect** or **Resync products**, choose **1 hour** under **Period** and **Refresh** to confirm the new attempts succeed. * A **Healthy** catalog with **Not working** checkout usually points to shipping or payment settings, not the connection. * **No recent activity** across every category on a connected store usually means nobody used the agent in that period; widen the period before assuming a problem. * The Meta catalog (products in WhatsApp) has its own health card on the WhatsApp **Account** tab. See [Read the catalog health card](/channels/whatsapp-catalog#read-the-catalog-health-card). ## Related * [Troubleshooting](/integrations/troubleshooting): step-by-step fixes for each problem. * [Connect your store](/integrations/overview) # Meta Business catalog Source: https://docs.trypopcorn.ai/integrations/meta-business How the Meta Business row on Integrations leads to Products in WhatsApp, and what Popcorn keeps in sync once a Meta catalog is connected. **Meta Business** on **Integrations** is not a store. It stands for the Meta catalog that mirrors the products already in Popcorn, so your agent can send WhatsApp product cards and customers can build a cart. Products still come from your connected Shopify, Salla or Zid store (or from Popcorn); the catalog only copies them to Meta. ## Where to set it up The **Meta Business** row sits under **Stores & catalogs** ("Send your products to your Meta catalog so your agent can share them on WhatsApp."). Its badge reads **Connected** once a catalog is linked and **Available** before. Its button, **Connect** or **Manage**, opens **Integrations → WhatsApp**, because the catalog is set up beside your number: * It reuses your WhatsApp connection, so there is no second Meta login. Connect a number first; see [Connect a WhatsApp number](/channels/whatsapp). * On the **Account** tab, the **Products in WhatsApp** panel has **Set up products**. The steps, the catalog choices and every message you can see are in [Products in WhatsApp](/channels/whatsapp-catalog). * A role that can manage products is needed. Without it, the panel says "Ask an admin to finish setting up your products." > [!NOTE] > > One catalog is shared by every number in the same WhatsApp account, because Meta allows one catalog per account. See [Products in WhatsApp](/channels/whatsapp-catalog#before-you-start). ## What Popcorn keeps in sync * After you connect, every active product in Popcorn is pushed to the catalog. Large catalogs take a while; the health card shows progress. * From then on, every product change in Popcorn, whether from your store sync or an edit in **Products**, is queued to the catalog. Products and variants you delete in Popcorn are removed from it. * Every night Popcorn compares your products with what is actually in the Meta catalog, re-pushes products that are missing and records products Meta rejected. It never deletes catalog items it cannot match to a Popcorn product, so items added by other tools are left alone. * **Resync products** on your store's row pulls the catalog from the store and then pushes it on to Meta in one go. See [Connect your store](/integrations/overview). ## Check it and reconnect The catalog health card on the WhatsApp **Account** tab shows how many products are live, which ones Meta rejected and why, and which are still syncing. If the panel says **Needs reconnect**, Meta no longer accepts Popcorn's connection: click **Reconnect WhatsApp** and share the catalog again when Meta asks. Until you do, products go out as image cards, and two or more with a photo and a link can go together as one carousel. Each line of the card is explained in [Read the catalog health card](/channels/whatsapp-catalog#read-the-catalog-health-card). A product that is live in the catalog still needs WhatsApp's own approval before it can go out as a catalog card, which can take hours for a new product. Until then it goes out as an image card, and the Inbox says why. See [WhatsApp's review of each product](/channels/whatsapp-catalog#whatsapps-review-of-each-product). Product cards and carts in conversations are controlled by the **Product sharing** and **Cart checkout** switches in the same panel. ## Related * [Products in WhatsApp](/channels/whatsapp-catalog): setup, health card, **Product sharing**, **Cart checkout**. * [Connect your store](/integrations/overview): where the products come from. * [Troubleshooting](/integrations/troubleshooting) # Connect your store Source: https://docs.trypopcorn.ai/integrations/overview What connecting Shopify, Salla or Zid to Popcorn unlocks, the one-active-store rule, and the Connect, Reconnect, Settings and Resync actions. Connecting your store gives your AI agent live products, stock and prices to recommend, lets it create orders and track them, syncs your customers, and lets you trigger automated campaigns from store events. You connect once from **Integrations**; Popcorn keeps everything current afterwards through store notifications. ## What a connected store unlocks | Area | What happens once a store is connected | | - | - | | Products | Your catalog is pulled into **Products** and kept current when products change in the store. The agent recommends and searches these products. See [the synced catalog](/products/catalog). | | Customers | Existing customers are imported into **Customers** and new or edited customers arrive automatically. A customer's profile shows which store it came from. See [customers](/customers/overview). | | Checkout and orders | The agent creates orders in your store using the payment methods you turn on under **Settings → Payment**. See [orders](/orders/overview) and [shipping and payment](/settings/shipping-and-payment). | | Order tracking | The agent looks up an order by order number (your store's, or Popcorn's own) or by the customer's phone number and answers status questions. | | Shipping | For Zid and Salla, **Settings → Shipping → Sync from store** imports the store's shipping methods. Shopify keeps shipping inside Shopify checkout. | | Automated campaigns | Store events such as new orders, paid orders and abandoned carts can trigger WhatsApp messages. See [automated campaigns](/campaigns/automated-campaigns). | | Products in WhatsApp | With a catalog connected under **Integrations → WhatsApp**, the same products are pushed to a Meta catalog so WhatsApp can show product cards and carts. See [Meta Business](/integrations/meta-business). | ## What the Integrations page shows **Integrations** ("Connect where customers message you and where your products come from.") sits at the foot of the sidebar. It has two panels: * **Channels** ("Where your customers talk to your agent"): **WhatsApp** and **Website chat**. See [Channels overview](/channels/overview). * **Stores & catalogs** ("Sync products and orders so your agent can sell"): **Shopify**, **Meta Business**, **Zid** and **Salla**. Each row shows a **Connected** or **Available** badge, or **Status unavailable** when Popcorn can't tell. A badge at the top of the page counts how many rows are connected, for example "2 connected"; a WhatsApp number that needs a reconnect is not counted. Once a store is connected, the **Store health** panel appears beside the rows. See [Store health](/integrations/commerce-health). * **Shopify**, **Salla** and **Zid** are stores. Connect one of them. See [Shopify](/integrations/shopify), [Salla](/integrations/salla) and [Zid](/integrations/zid). * **Meta Business** is not a store. Its button opens the **WhatsApp** page, where the catalog is set up next to your number. See [Meta Business](/integrations/meta-business). ## Before you start * You need a role with permission to manage integrations. The built-in **Owner** and **Admin** roles have it; **Manager** can view the page but not connect, and **Agent** and **Viewer** cannot open it. See [team and roles](/settings/team-and-roles). * Connecting opens a pop-up window for the store's authorization screen. Allow pop-ups for Popcorn and keep the **Integrations** page open until the pop-up closes. * The product count under a row needs permission to view products. **Resync products** needs permission to manage products (**Owner**, **Admin**, **Manager**). > [!NOTE] > > The first step of setup also offers to connect Salla, Zid or Shopify. Skipping it there is fine; the **Integrations** page does the same thing later. ## Connect a store **1. Open Integrations** Go to **Integrations** and find the row for your platform under **Stores & catalogs**. **2. Click Connect** Click **Connect**. A pop-up opens on the platform's authorization page. Sign in to your store if asked and approve the access request. **3. Wait for the pop-up to close** When authorization succeeds the pop-up closes on its own and Popcorn shows **Shopify connected. Your products are syncing.** (or **Zid connected** or **Salla connected**). If it closes without connecting, you see **Couldn't connect to Shopify. Try again.** (or the Zid or Salla version). If your browser blocks the pop-up, you see **Allow pop-ups for this site, then try again.** **4. Let the first sync finish** The row now reads **Connected** and its status line shows **Resyncing products…** until the first import completes, then the product count and when it last synced. ## Actions on a connected row | Action | What it does | | - | - | | **Reconnect** | Runs the authorization again with the store. Use it when the store's credentials expired or were revoked. Reconnecting also re-registers the store notifications Popcorn relies on, including those used by active automated campaigns, and starts a fresh product and customer sync. If you close the pop-up without finishing, Popcorn says "Your Shopify store is still connected". | | **Settings** (gear icon) | **Shopify** opens **Shopify settings**: phone-only checkout and custom checkout fields. **Zid** opens **Zid settings**: how VAT applies to your prices. It shows only to roles that can edit settings. **Salla** has none. See [Shopify](/integrations/shopify) and [Zid](/integrations/zid). | | **Resync products** | Pulls the latest products from your store, then pushes them on to your Meta catalog if one is connected. Popcorn confirms with **Resync started** and "Pulling your latest products from your store. This usually takes a few minutes." | The status line under the connected store reads, for example, **120 products · last synced 3h ago**. If the most recent run failed it reads **last resync failed** with the time, and a store that has never completed a sync shows **never synced**. ### Resync limits * Only one sync runs at a time. Clicking again while one is running shows **A resync is already running**. * After a resync you must wait 15 minutes before starting another. Popcorn tells you how long: "Products were just resynced. You can resync again in N min." * **Resync products** appears only on the row of the store Popcorn is actively using (see below) and only for roles that can manage products. * If Popcorn finds no connected store, you see "Connect your store before resyncing products". If the resync can't start, you see "Couldn't start the resync. Please try again." ## One active store Popcorn uses one store at a time for products, checkout, tracking and campaigns. While exactly one store is connected, the other store rows warn "Your agent already sells from Shopify. Connecting a second store can make it use the wrong catalog." (naming the connected store). If credentials exist for more than one platform, Popcorn uses them in this order: **Shopify**, then **Salla**, then **Zid**. **Store health** flags this under **Connection** as **More than one store connected** with the advice to contact Popcorn AI support to remove the one you don't use. The **Integrations** page has no disconnect action. If you need to remove a store from your workspace, contact Popcorn support. ## What syncs, per platform | | Shopify | Salla | Zid | | - | - | - | - | | Products and variants | Yes | Yes | Yes | | Stock | Online Store quantity | Yes | Stock at locations that sell on your website | | Product custom options | No | No | Yes | | Customers | Yes | Yes | Yes | | Shipping methods into Popcorn | No (add delivery coverage manually) | Yes, with fees and delivery times | Yes, per zone with fees and cash on delivery terms; you set delivery times | | Order created by the agent | Shopify checkout link | Order in Salla | Order in Zid | | Order tracking | By order number or phone | By order number or phone | By order number or phone | | Billing through the platform's app store | No | Yes | Yes | Details, including the store events that can trigger automated campaigns, are on each platform's page. ## Related * [Store health](/integrations/commerce-health): read the panel and act on failures. * [Troubleshooting](/integrations/troubleshooting): reconnect problems, stale catalogs, checkout and tracking errors. * [Quickstart](/quickstart): from sign-up to the first live conversation. # Connect Salla Source: https://docs.trypopcorn.ai/integrations/salla Connect your Salla store, see what syncs, sync shipping methods, which events trigger campaigns, and how the Salla App Store subscription applies. Connect Salla so your AI agent sells from your live Salla catalog, creates orders in Salla with your store's payment methods, tracks orders, and keeps your customer list current. If you subscribe to Popcorn through the Salla App Store, the subscription is applied to this workspace through the same connection. ## Before you start * A Salla store you can sign in to. * A Popcorn role that can manage integrations (**Owner** or **Admin**). * Allow pop-ups for Popcorn: the authorization opens in a pop-up window. ## Connect **1. Open Integrations** Go to **Integrations** and click **Connect** on the **Salla** row. **2. Approve access** A pop-up opens on Salla. Sign in and approve the access Salla lists for Popcorn (products, orders, customers and store notifications). **3. Wait for confirmation** The pop-up closes on its own. Popcorn shows **Salla connected** and the row reads **Connected**. If the pop-up closes without connecting, you see **Couldn't connect to Salla. Try again.** Click **Connect** again. ## What happens when you connect * Popcorn saves your merchant account and store domain. * Popcorn subscribes to Salla notifications for product creation, updates and deletion, order updates, and customer creation and updates. * A full product import and a full customer import start in the background. The row shows **Resyncing products…** until the product import finishes. * Active [automated campaigns](/campaigns/automated-campaigns) get their Salla triggers re-registered, so **Reconnect** also repairs campaigns that stopped firing. > [!NOTE] > > If you connected Salla before customer sync existed, click **Reconnect** once. The customer permission is only granted during authorization, and customer import starts after it. ## What syncs **Products** * Name, description (formatting removed), images, product link and tags (used as search keywords). * Prices. When your store applies tax to a product, Popcorn stores the price including tax; the discounted price is the taxed sale price. Otherwise the regular price and sale price are used as they are. * A product is active in Popcorn when it is on sale in Salla. * Quantity. A product with unlimited quantity in Salla is treated as always available. * Variants. Popcorn creates, updates and removes variants to match Salla. * Salla product custom options are not imported. **Customers** * First and last name, mobile number with country code, and email. * Salla customer groups and tags become customer tags in Popcorn. * Each imported customer shows **Salla** as its source on the customer profile. See [customers](/customers/overview). ## Ongoing updates | Change in Salla | Effect in Popcorn | | - | - | | Product created or updated | Added or updated in **Products**, and pushed to your Meta catalog if one is connected. | | Product deleted | Removed from **Products**. | | Order updated with payment confirmed | An order the agent created in Salla is marked paid. | | Customer created or updated | Added or updated in **Customers**. | To force a fresh import at any time, click **Resync products** on the Salla row. See [Connect your store](/integrations/overview) for the resync limits. ## Checkout and payment When the agent completes a sale, Popcorn creates the order in Salla. The confirmation message gives the customer Salla's own order number and the total Salla reports, and the order in Popcorn shows that total and Salla's shipping cost. For a payment link, the customer receives Salla's checkout link for that order. The payment methods offered on the order are the ones your Salla store has active among credit card, mada, bank transfer and cash on delivery. A new workspace starts with **Cash on delivery** on. Manage the options under **Settings → Payment**; if none is on, the agent doesn't create the order and hands the conversation over. See [shipping and payment](/settings/shipping-and-payment) and [orders](/orders/overview). ## Shipping methods Under **Settings → Shipping**, click **Sync from store** to open **Sync shipping from your store** and import your Salla shipping companies: * Each company arrives with its fee and its expected delivery time (minimum and maximum days) taken from your Salla shipping zones. * Coverage is built from your zones: specific cities, whole countries, or every country when a zone covers all countries. * Choose the methods to sync, adjust each one's fee and delivery time if needed, and click **Sync methods**. Methods already in Popcorn are marked **Already synced**; the others are marked **New**. Methods active in Popcorn but turned off or missing in Salla are listed under "These methods are active in Popcorn AI but turned off or missing in your store." Select them and click **Deactivate** so your agent stops offering them. ## Order tracking When a customer asks about an order, the agent looks it up in Salla by order number and checks that the customer's phone number matches the order; a mismatch is refused. If the customer quotes Popcorn's own order number (as on **Orders**, "P" and six digits), Popcorn finds the Salla order behind it. With only a phone number, the agent finds the customer in Salla and returns their five most recent orders. Switch on **Track orders** on the agent's **Actions** tab to use this; see [agent capabilities](/agents/capabilities). ## Events for automated campaigns These Salla events are available as triggers when you create an [automated campaign](/campaigns/automated-campaigns): | Group | Events | | - | - | | Orders | **Order Created**, **Order Updated**, **Order Status Updated**, **Order Payment Updated**, **Order Products Updated**, **Order Coupon Updated**, **Order Total Price Updated**, **Order Shipping Address Updated**, **Order Customer Updated**, **Order Cancelled**, **Order Refunded**, **Order Deleted**, **Invoice Created**, **Review Added** | | Carts | **Abandoned Cart**, **Abandoned Cart Updated**, **Coupon Applied** | | Customers | **Customer Created**, **Customer Updated** | | Order shipments | **Order Shipment Creating**, **Order Shipment Created**, **Order Shipment Cancelled**, **Order Return Shipment Creating**, **Order Return Shipment Created**, **Order Return Shipment Cancelled** | | Shipments | **Shipment Creating**, **Shipment Created**, **Shipment Updated**, **Shipment Cancelled** | For abandoned-cart messages, Popcorn checks whether that customer has placed an order since the cart was abandoned and skips the message if they have. ## Subscription through the Salla App Store If you subscribe to a Popcorn plan inside the Salla App Store, Salla notifies Popcorn and the plan is applied to the workspace whose connected Salla store matches: * Subscription started, renewed, or trial started: the plan becomes active until the end date Salla reports. Popcorn recognises the **Salt** and **Cheese** plans by name; a plan name it does not recognise is treated as the free plan. * Subscription canceled or expired, trial canceled or expired: the plan ends at the end date Salla reports. Connect your store in Popcorn before subscribing. Popcorn matches the subscription to your workspace through the connected store, so a subscription event that arrives before the store is connected cannot be applied. See [plans and credits](/billing/plans-and-credits). ## Related * [Connect your store](/integrations/overview) * [Store health](/integrations/commerce-health) * [Troubleshooting](/integrations/troubleshooting) # Connect Shopify Source: https://docs.trypopcorn.ai/integrations/shopify Connect your Shopify store, understand what syncs, set phone-only checkout and custom checkout fields, and see which events drive campaigns. Connect Shopify so your AI agent sells from your live catalog, sends customers a Shopify checkout link, answers order-status questions from real order data, and keeps your customer list current. Connection takes one authorization; Popcorn then stays in sync through Shopify's own notifications. ## Before you start * A Shopify store you can sign in to as a staff member with permission to install apps. * A Popcorn role that can manage integrations (**Owner** or **Admin**). * Allow pop-ups for Popcorn: the authorization opens in a pop-up window. ## Connect **1. Open Integrations** Go to **Integrations** and click **Connect** on the **Shopify** row. **2. Choose the store** A pop-up opens on Shopify. If you are signed in to several stores, Shopify asks which one to use. **3. Approve the app** Review the access the **Popcorn AI** app requests (products, orders, checkouts, draft orders, returns and customers) and approve it. **4. Wait for confirmation** The pop-up shows **Connecting Shopify** and then "Shopify is connected. This window closes by itself." Back on **Integrations**, the row reads **Connected** and Popcorn shows **Shopify connected. Your products are syncing.** If the pop-up closes without connecting, Popcorn shows **Couldn't connect to Shopify. Try again.** Click **Connect** once more. If the pop-up itself says "This connection link was already used. Close this window and connect again.", close it and start again from **Connect**. If you install the app from Shopify's side instead, Popcorn starts the same authorization automatically once you are signed in to Popcorn. ## What happens when you connect * Popcorn records your store's primary domain so campaign link buttons open on the domain your customers know. * Popcorn creates the storefront access it needs to build checkouts. * Popcorn subscribes to Shopify notifications for product creation, updates and deletion, paid orders, and customer creation and updates. * A full product import and a full customer import start in the background. The Shopify row shows **Resyncing products…** until the product import finishes. * Active [automated campaigns](/campaigns/automated-campaigns) get their Shopify triggers re-registered, so **Reconnect** also repairs campaigns that stopped firing. ## What syncs **Products** * Title, description, images, tags, product link and status. A product is active in Popcorn only when its Shopify status is **Active**. * Price and compare-at price. A variant is on sale only when its compare-at price is higher than its price: Popcorn then shows the compare-at price struck through beside the price, on **Products** and in what the agent sends. A compare-at price equal to or lower than the price is ignored. * Variants, up to the first 100 variants per product. * Stock is the quantity sellable on the **Online Store** sales channel. Point-of-sale and wholesale inventory are not counted. With **Product quantities** on, a product that syncs with 0 is marked inactive, as on any store. Otherwise Popcorn doesn't hold back an active Shopify product because its stock reads 0; see [Products the agent can't sell](/products/catalog#products-the-agent-cant-sell). **Customers** * Name, phone number, email, tags and marketing consent. A customer who opted out of marketing is marked unsubscribed; a sync never re-subscribes anyone. * Customers without a phone number are imported too. * Each imported customer shows **Shopify** as its source on the customer profile. See [customers](/customers/overview). ## Ongoing updates | Change in Shopify | Effect in Popcorn | | - | - | | Product created or updated | The product is added or updated in **Products**, and pushed to your Meta catalog if one is connected. | | Product deleted | The product is removed from **Products**. | | Order paid | An order the agent created for that checkout is marked paid. | | Customer created or updated | The customer is added or updated in **Customers**. | | Customer data deletion request from Shopify | Popcorn deletes the data it synced for that customer. After you uninstall the app, Shopify's shop deletion request makes Popcorn delete all customer data synced from that store. | To force a fresh import at any time, click **Resync products** on the Shopify row. See [Connect your store](/integrations/overview) for the resync limits. ## Shopify settings Click the gear icon on the connected **Shopify** row to open **Shopify settings** ("Choose how your agent places Shopify orders."). Change what you need and click **Save**; you see **Shopify settings saved**. **Cancel** closes the dialog without saving. ### Allow phone-only checkout On by default. "Turn on if your Shopify store accepts orders with only a phone number. When off, your agent asks customers for an email before it creates the order." ### Custom checkout fields Turn on **Custom checkout fields** ("Collect extra details at checkout, like a gift message or sender name.") to ask customers for more than the standard details. The answers are attached to the Shopify checkout the agent creates. > [!WARNING] > > The dialog shows **Re-add Create order to your agents**: "New checkout fields apply to Create order added from now on. If your agents already have Create order, remove it and add it again." See [agent capabilities](/agents/capabilities). **1. Find fields** Click **Find fields from abandoned checkouts**. Popcorn reports "Found 2 new checkout fields" (with the number it found), **No new checkout fields found** or **No checkout fields found in recent abandoned checkouts**. If it can't search, you see "Couldn't find checkout fields. Try again." **2. Review the list** Under **Checkout fields**, each field has a **Required** checkbox, an **Enabled** checkbox, **What the agent asks the customer** (a text field; Popcorn starts it with "Ask the customer for" followed by the field's name), and an **Answer type**: **Text**, **Number**, **Phone**, **Email**, **Yes or no**, **Date**, **Time** or **Date and time**. **3. Save** Click **Save**. If the checkout fields don't save but phone-only checkout did, you see "Phone-only checkout was saved, but checkout fields weren't. Try again."; if nothing saved, "Couldn't save Shopify settings. Try again." ## Checkout on Shopify When the agent completes a sale, Popcorn builds a Shopify cart with the customer's details and the collected attributes, and sends the customer a Shopify checkout link. The order appears in **Orders** and waits for payment until Shopify reports the order as paid. See [orders](/orders/overview). * **Payment**: the customer pays in Shopify checkout. The payment methods your agent can offer follow what you turn on under **Settings → Payment**; a new workspace starts with **Cash on delivery** on. If no method is on, the agent doesn't create the order and hands the conversation over. * **Shipping**: rates and delivery windows are handled inside Shopify checkout, so the order summary in the chat has no delivery line and **Settings → Shipping** offers no **Sync from store**. Use **Add delivery coverage** to list the countries and cities your agent can accept before sending a Shopify checkout. See [shipping and payment](/settings/shipping-and-payment). ## Order tracking When a customer asks about an order, the agent looks it up in Shopify by order number and checks that the customer's phone number (or the email address on the order) matches; a mismatch is refused. If the customer gives only a phone number, or quotes Popcorn's own order number (as on **Orders**, "P" and six digits), Popcorn finds the customer in Shopify by phone and returns their five most recent orders. Switch on **Track orders** on the agent's **Actions** tab to use this; see [agent capabilities](/agents/capabilities). ## Events for automated campaigns These Shopify events are available as triggers when you create an [automated campaign](/campaigns/automated-campaigns): | Event | Sent when | | - | - | | **Order Created** | A new order is created | | **Order Paid** | An order is paid | | **Order Updated** | An order is updated | | **Order Edited** | An order is edited | | **Order Fulfilled** | An order is fulfilled | | **Order Partially Fulfilled** | Part of an order is fulfilled | | **Order Cancelled** | An order is cancelled | | **Checkout Created** | A checkout is started | | **Checkout Updated** | A checkout is updated | For abandoned-checkout messages, Popcorn checks whether that customer has placed an order since the checkout and skips the message if they have. ## Related * [Connect your store](/integrations/overview): actions on the row, resync limits, one active store. * [Store health](/integrations/commerce-health): see whether sync, checkout and tracking are healthy. * [Troubleshooting](/integrations/troubleshooting) # Integration troubleshooting Source: https://docs.trypopcorn.ai/integrations/troubleshooting Fix store connection problems: reconnecting, stale catalogs, no shipping option, required options, duplicate stores, rate limits and tracking. Most integration problems show up in one of three places: the store's row on **Integrations** (status and last sync), the **Store health** panel beside it, or a message the agent gives a customer during checkout or tracking. Find your symptom below. ## The connection > **Store health says Store access failed, or the store row went back to Available** > > The store no longer accepts Popcorn's credentials. Zid clears the stored credentials when Zid reports them invalid; for every platform the row keeps its badge, but syncs, orders and tracking fail until you reconnect. > > 1. On **Integrations**, click **Reconnect** (or **Connect**) on the store's row and approve access again. > 2. Wait for the confirmation message and for the status line to move from **Resyncing products…** to a product count. > 3. Open **Store health**, choose **1 hour** under **Period** and click **Refresh**. **Connection** should be **Healthy**. > > Reconnecting also re-registers store notifications and the triggers of active automated campaigns. > **Store health says Store account lacks permission (Zid)** > > Zid refused a request because the Zid user who connected your store lacks a permission there, such as permission to view orders. Zid checks that user's permissions whatever the app was approved for, so products can keep syncing while the agent can't look up orders. > > 1. On **Integrations**, click **Reconnect** on the Zid row and approve with the store owner's Zid account. Or, in Zid, give the user who connected the store the missing permission; **View details** on the failing row says what Zid refused. > 2. After the next order lookup, or after **Resync products**, open **Store health**, choose **1 hour** under **Period** and click **Refresh** to confirm the new attempts succeed. > **The pop-up closed and Popcorn says Couldn't connect** > > The authorization did not complete inside the pop-up, and you see **Couldn't connect to Shopify. Try again.** (or the Zid or Salla version). If you see **Allow pop-ups for this site, then try again.**, your browser blocked the pop-up. Allow pop-ups for Popcorn, keep the **Integrations** page open while the pop-up is up, and click **Connect** again. If you close the pop-up on a store that is already connected, Popcorn says "Your Shopify store is still connected" and nothing changes. > **More than one store connected** > > Popcorn uses one store at a time. With credentials for several platforms it uses **Shopify** first, then **Salla**, then **Zid**, and **Store health** shows **Connection** as **Partly working** with **More than one store connected**. Products, checkout and tracking all go to the winning store, and **Resync products** only appears on that row. > > There is no disconnect button on **Integrations**. To remove the store you do not want, contact Popcorn support. > **I subscribed in the Zid App Market but Popcorn still shows the free plan** > > Popcorn applies Zid subscription events to the workspace whose connected Zid store matches. If you subscribed before connecting, the event is held and applied when you connect the store from **Integrations** or the **Connect your Zid store** page. If the store is connected and the plan is still missing, contact support. See [Connect Zid](/integrations/zid). ## Products and catalog > **Products are missing, outdated, or the wrong price** > > 1. Check the status line under the store row. **last resync failed** means the last import did not finish; **never synced** means no import has completed yet. > 2. Click **Resync products**. Popcorn pulls everything from the store again and, if a Meta catalog is connected, pushes it on to Meta. You can resync again after 15 minutes. > 3. Products that are not active in the store stay inactive in Popcorn: Shopify products must have status **Active**, Salla products must be on sale, Zid products must be published and listed at a location that sells on your website (stock only at Zid Cashier or marketplace locations doesn't count). After you move stock or change where a Zid location sells, click **Resync products**. > 4. Zid products without a SKU are skipped entirely. Add a SKU in Zid and resync. > 5. Zid prices that look wrong by the VAT amount: open **Zid settings** (the gear on the Zid row) and check how VAT applies. See [Connect Zid](/integrations/zid#vat-for-zid-prices). > 6. Open **Store health → Catalog** and read **Most common problem**: **Store access failed** means reconnect; **Store limited requests** means the store's API throttled the import, so wait a few minutes and resync. > **Resync products is greyed out or missing** > > The button shows only on the row of the store Popcorn is actively using and only for roles that can manage products (**Owner**, **Admin**, **Manager**). While a sync runs the button is disabled and the status line reads **Resyncing products…**. If you click too soon after a run you see "Products were just resynced. You can resync again in N min." > **Products do not appear in WhatsApp** > > That is the Meta catalog, not the store. Check the health card on **Integrations → WhatsApp → Account**: **Needs reconnect** means click **Reconnect WhatsApp**; **Not accepted** lists the products Meta rejected and its reasons. See [Products in WhatsApp](/channels/whatsapp-catalog) and [Channel troubleshooting](/channels/troubleshooting#product-cards-or-the-catalog-are-not-working). ## Checkout > **No shipping option** > > The agent could not find a shipping option that covers the customer. **Store health → Checkout and order creation** shows **No shipping option** with the impact **Customers can't finish**. > > * Zid or Salla: go to **Settings → Shipping**, click **Sync from store**, choose the methods to sync and set fee and delivery time where required, then click **Sync methods**. Make sure at least one option is **Active** and covers the customer's country and city. > * Shopify: shipping is handled in Shopify checkout, so use **Add delivery coverage** in **Settings → Shipping** for the countries and cities you deliver to. > > See [shipping and payment](/settings/shipping-and-payment). > **The agent won't take cash on delivery to some cities (Zid)** > > Zid sets cash on delivery per delivery zone. A delivery option synced from a zone that doesn't take it shows **No cash on delivery** under its fee in **Settings → Shipping**, and the agent offers the delivery options to that city that do take it, or another payment method. Change the zone in Zid, then click **Sync from store** and sync it again. > **The fee the agent quoted differs from Zid's checkout** > > The agent quotes the delivery option's fee from **Settings → Shipping** and the cash on delivery fee (the zone's own, or the one under **Settings → Payment**), plus any VAT Zid adds on top at checkout once Popcorn knows about it. For a fee you typed yourself, Popcorn learns that VAT from the first Zid order that uses it, so the first quote after you add or change a fee can be short of it. Check the fee against Zid, or click **Sync from store** to take Zid's own fees for its zones. The order in **Orders** shows the fees Zid charged. > **Missing a required product option** > > The order needs a product option the agent did not collect, so **Store health** shows **Missing a required product option** with the impact **Customers need to add details**. Review the product's options in **Products** (Zid custom fields sync automatically), then ask the customer for the missing choice. See [the synced catalog](/products/catalog). > **The agent asks for an email address before ordering (Shopify)** > > **Allow phone-only checkout** is turned off in **Shopify settings**. Turn it on if your Shopify store accepts checkout with only a phone number. See [Connect Shopify](/integrations/shopify). > **The agent doesn't create orders and hands the chat over** > > If no payment method is turned on, the agent doesn't create the order: it tells the customer your team will confirm how they can pay and hands the conversation over. Turn on at least one method under **Settings → Payment**. On Zid, the agent offers only the methods your Zid store has on, so also check the payment methods in Zid. See [Connect Zid](/integrations/zid#checkout-and-payment). > **Store couldn't create the order** > > The store rejected the order or returned no order reference. When Zid turns an order down, the customer is told the store couldn't take the order with those details (or that an item is out of stock, when that is Zid's reason) and is offered a change or your team; the same order isn't sent again. Open **View details** on the **Checkout and order creation** row for the message, and check the order in **Orders**. If the message mentions credentials, tokens or authorization, click **Reconnect** on the store row. For Zid payment links, remember they expire 24 hours after creation. ## Store notifications and campaigns > **Store update wasn't processed** > > A notification from the store (product, order or customer change) or an automated-campaign trigger could not be processed. **Store health → Store updates and automations** records it with the operation and, in **View details**, the store's reference. > > * A single failure usually resolves on the next notification for the same product or order. Click **Resync products** to catch up on products. > * If failures keep coming, click **Reconnect** on the store row. This re-subscribes every notification Popcorn needs. For Zid, Popcorn also re-checks the order and stock subscriptions once a day. > **Automated campaigns stopped triggering after I reconnected** > > Reconnecting re-registers the triggers of every active automated campaign automatically. Confirm the campaign is still active and that the event you chose is one the platform sends; the lists are on the [Shopify](/integrations/shopify), [Salla](/integrations/salla) and [Zid](/integrations/zid) pages. For messages that were not sent, open the campaign's results; see [campaign troubleshooting](/campaigns/troubleshooting). > **Customers are not appearing in Customers** > > Customer import starts when you connect and stays current through the store's customer notifications. Imported customers show their source (**Shopify**, **Salla** or **Zid**) on the profile. If you connected Salla before customer sync existed, click **Reconnect** once to grant the customer permission. See [customers](/customers/overview). ## Order tracking > **Couldn't get tracking** > > The agent could not retrieve the order. **Store health → Order status and tracking** records it with the order reference under **View details**. > > * The lookup needs an order number or the customer's phone number. Without either, the agent tells the customer: **Please provide your order number or phone number to track your order.** > * The order number must exist in the store, and a phone lookup only finds orders placed under that phone number. > * If every lookup fails, the store credentials are usually the cause: click **Reconnect** on the store row. On Zid, **Store account lacks permission** means the account that connected the store can't view orders; see the accordion of that name under **The connection**. > * Make sure **Track orders** is switched on in the agent's **Actions** tab. See [agent capabilities](/agents/capabilities). ## Still stuck Open **Store health**, click **View details** on the failing category and share the **Event ID** with Popcorn support. The details never include customer names, phone numbers or addresses. ## Related * [Store health](/integrations/commerce-health) * [Connect your store](/integrations/overview) * [Channel troubleshooting](/channels/troubleshooting) for WhatsApp and Website chat problems. # Connect Zid Source: https://docs.trypopcorn.ai/integrations/zid Connect your Zid store from Popcorn or the Zid App Market, see what syncs, set VAT, payments and shipping, and how the Zid subscription works. Connect Zid so your AI agent sells from your live Zid catalog, creates orders in Zid with cash on delivery, bank transfer or a payment link, tracks orders with shipping details, and keeps your customer list current. If you buy Popcorn through the Zid App Market, the subscription is applied to this workspace through the same connection. ## Before you start * A Zid store you can sign in to. * A Popcorn role that can manage integrations (**Owner** or **Admin**). * Allow pop-ups for Popcorn: the authorization opens in a pop-up window. ## Connect from Popcorn **1. Open Integrations** Go to **Integrations** and click **Connect** on the **Zid** row. **2. Approve access** A pop-up opens on Zid. Sign in and approve the access request. **3. Wait for confirmation** The pop-up closes on its own. Popcorn shows **Zid connected** and the row reads **Connected**. If the pop-up closes without connecting, you see **Couldn't connect to Zid. Try again.** Click **Connect** again. ## Connect from the Zid App Market Installing Popcorn from the Zid App Market brings you to a Popcorn page titled **Connect your Zid store** ("Link your Zid store so your agent can answer questions about your products and orders."). If you are not signed in, Popcorn asks you to sign in first. **1. Click Connect Zid** A pop-up opens on Zid and the page reads **Waiting for Zid** ("Finish signing in to Zid in the window that opened."). Approve the connection in Zid, and the pop-up closes by itself. Keep the page open until you're done. **2. Wait for confirmation** On success the page shows **Zid connected** and takes you to **Integrations** ("After connecting, we'll take you to Integrations."). If it shows **Zid isn't connected yet**, read the reason under it, such as "The window closed before Zid finished connecting. Try again and approve the connection in Zid.", and click **Connect Zid** again, or use **Go to integrations** and connect from the **Zid** row. If your browser blocks the pop-up, the page says "Your browser blocked the Zid window. Allow pop-ups for this site and try again." The page also lists what to try under **If nothing happens**, and **Contact support** under **Need help?** ## What happens when you connect * Popcorn saves your store ID and store URL. * Popcorn asks Zid whether your prices include VAT and which payment methods the store accepts, and starts from those answers. A choice you made yourself is never overwritten by a later read. * Popcorn subscribes to Zid notifications for product creation, updates, publishing and deletion, for new orders and order status and payment changes, and for customer creation and updates. Once a day Popcorn re-checks the order notifications it uses to keep stock current and restores any that are missing. * A full product import and a full customer import start in the background. The row shows **Resyncing products…** until the product import finishes. * If you have no delivery options in Popcorn yet, Popcorn adds your active Zid delivery options for you, with the fee Zid sets for each zone when Zid shares it. See [Shipping methods](#shipping-methods). * Any Zid App Market subscription events received before the store was connected are applied now. * Active [automated campaigns](/campaigns/automated-campaigns) get their Zid triggers re-registered, so **Reconnect** also repairs campaigns that stopped firing. ## What syncs **Products** * Name, description, images, product link, keywords, price and sale price. A sale price is used only while its sale period is active. * Every product needs a SKU. Products without a SKU are skipped and do not appear in Popcorn. * A published product is active in Popcorn only when Zid lists it at a location that sells on your website, whatever the quantity there. This doesn't depend on **Product quantities**. A product listed only at locations that sell through Zid Cashier (your branch tills) or on marketplaces stays inactive, because shoppers can't buy it on your website. A variant is judged by its own locations. If Popcorn can't read where your locations sell, products are saved as Zid lists them. * A parent product with variants is not sellable itself; its variants are the sellable products, and they inherit the parent's images and link when they have none of their own. * Stock is the quantity at locations that sell on your website. Stock marked as infinite is treated as always available. * Zid custom option fields and custom user input fields become product custom options, so the agent asks for them during checkout. See [the synced catalog](/products/catalog). **Customers** * Name, mobile number, email, city and country, and tags. * Each imported customer shows **Zid** as its source on the customer profile. See [customers](/customers/overview). ### VAT for Zid prices Popcorn stores final customer prices, so it needs to know whether the prices in Zid already include VAT. Zid tells it, and you can say otherwise. Click the gear icon on the **Zid** row to open **Zid settings** ("Zid tells your agent whether your prices include VAT."). The gear shows only to roles that can edit settings. Popcorn asks Zid every time the dialog opens ("Checking with Zid"), then shows one of these: | What the dialog says | What it means | | - | - | | **Checked with Zid just now**: "Your prices include 15% VAT, so your agent quotes them as they are." (or "Your prices don't include VAT, so your agent adds 15% when it quotes them." or "VAT is off for your store, so your agent quotes prices as they are.") | Your agent follows what Zid says. Click **Check again** to ask Zid again. | | **Zid says prices include VAT**, **Zid says prices don't include VAT** or **Zid says VAT is off for your store**, with "You chose to add 15%, so your agent follows your choice and a price it quotes may not match your Zid checkout." | You chose something different from Zid. Your agent follows your choice. Click **Use Zid's answer** to follow Zid instead; you see "Your agent now follows Zid". | | **Zid says prices don't include VAT** with "Zid didn't say how much to add, so tell your agent below." | Zid gave no rate. Enter it below. | | **Zid didn't share your tax settings** ("Reconnect Zid so it can share them, or choose below.") | Click **Reconnect Zid** or **Try again**, or choose yourself. If you're not sure, the dialog suggests adding one product to your Zid cart: if VAT is added on top of its price (delivery doesn't count), choose **Don't include VAT**; if not, choose **Include VAT**. | To choose yourself, click **Not right? Choose it yourself**. Under **Prices in Zid**, choose **Include VAT** (your agent quotes each price as it is in Zid) or **Don't include VAT** (your agent adds the VAT rate when it quotes a price), and for the second enter the **VAT rate (%)**, for example 15 ("A number, like 15."). Click **Save**. You see **VAT saved**, or **VAT saved. Prices in your catalog are being updated.** when the change affects prices; Popcorn reprices your catalog in the background. Settings → General also has a **VAT** panel. With Zid connected it says "VAT is set in your Zid settings" and **Open Zid settings** takes you to this dialog. ## Ongoing updates | Change in Zid | Effect in Popcorn | | - | - | | Product created, updated or published | Added or updated in **Products**, and pushed to your Meta catalog if one is connected. | | Product deleted | Removed from **Products**. | | Order created, or its status or payment status changes | Stock for the products in that order is refreshed. When Zid reports the order as paid, an order the agent created is marked paid. | | Customer created or updated | Added or updated in **Customers**. | | A stock location starts or stops selling on your website | Product notifications don't report this. Click **Resync products** to update your catalog straight away. Popcorn also checks your locations once a day while your plan is active and reads your catalog again when they changed. | Zid access tokens are refreshed automatically. If Zid reports that the stored credentials are no longer valid, Popcorn clears them and syncs, orders and tracking stop working until you click **Reconnect** (or **Connect**) on the Zid row and authorize again. Zid also checks the permissions of the Zid user who connected the store, whatever the app was approved for. If that user lacks one, such as permission to view orders, Zid refuses those requests: for example, products sync but the agent can't look up orders. **Store health** then shows **Store account lacks permission**, and **View details** says what Zid refused (for a sync, which permission is missing). Click **Reconnect** on the Zid row and approve with the store owner's Zid account, or give the user that connected the store the permission in Zid. See [Store health](/integrations/commerce-health). ## Checkout and payment When the agent completes a sale, Popcorn creates the order in Zid using the payment method the customer chose: **Cash on delivery**, **Bank transfer** or **Payment link** (Zid Pay). Each is matched to the corresponding payment method in your Zid store, and a method counts only when Zid has it turned on. A Zid payment link created by Popcorn expires 24 hours after it is created. * **Popcorn starts from what Zid accepts.** When you connect, Popcorn reads which of the three your store takes and offers only those. It also reads the cash on delivery fee Zid adds, when Zid names a single amount, and includes it in quotes. * **Your own choice wins.** Once you change payment methods under **Settings → Payment**, a later read of Zid never overwrites them, and an order for a method you have turned off is refused. A method your Zid store has turned off is never used on an order, even when Zid still lists it. * **No method on means no order.** If Zid has every payment method off, or you turn them all off, the agent doesn't create the order: it tells the customer your team will confirm how they can pay, and hands the conversation over. * **Fees as Zid charges them.** When your Zid checkout adds VAT on top of a delivery fee or a cash on delivery fee, the agent quotes the fee with that VAT, so the summary matches what the customer pays. Delivery options synced from Zid's zones, at the fee Zid sets, take this from your Zid tax settings. For any other fee, Popcorn learns it from the first Zid order that uses the fee, and learns again after you change the fee; until then the fee is quoted as you entered it. When the customer taps **Confirm order**, Popcorn checks each product in Zid again, including that it still has stock for your website. If one is no longer for sale, the order isn't created and the customer is told their cart changed and gets a fresh summary. Zid prices the order when it is created: any automatic (store-wide) discount that the cart qualifies for is applied, and a discount code the customer gave is applied on top. The confirmation message gives the customer Zid's own order number and the total Zid reports. The order in Popcorn shows that total, with the delivery and cash on delivery fees as Zid charged them, so it can be lower than the summary the customer confirmed; a fully discounted order shows a total of 0. If no payment option has been set yet and Zid can't be read, a new workspace starts with **Cash on delivery** on. See [shipping and payment](/settings/shipping-and-payment) and [orders](/orders/overview). ## Shipping methods Under **Settings → Shipping**, click **Sync from store** to open **Sync shipping from your store** and import your Zid delivery options. Zid prices each delivery option by zone, so a delivery option with several zones is listed once per zone, each with: * the cities the zone covers, * the fee Zid sets for the zone (a zone priced by weight has none: enter one), * the zone's cash on delivery terms: **Cash on delivery fee** with the amount, **Cash on delivery, no fee**, or **No cash on delivery**. Zid doesn't share delivery times, so enter **Fastest delivery (days)** for each one you choose, then click **Sync methods**. Each zone becomes its own option under **Shipping options**, showing its cash on delivery terms under the fee. If Popcorn can't read Zid's zones, it lists each delivery option once with its cities and no fee, and you enter the fee yourself. At checkout the agent charges the zone's own fees, and won't take a cash on delivery order for a zone that doesn't accept it: it offers the delivery options to that city that do, or another payment method. See [how the agent uses shipping](/settings/shipping-and-payment#how-the-agent-uses-shipping-at-checkout). ## Order tracking When a customer asks about an order, the agent looks it up in Zid by order number (Zid's, or Popcorn's own "P" number from **Orders**) and checks that the customer's phone number matches the order; a mismatch is refused. With only a phone number, it finds the customer's five most recent orders. Either way, each order's answer can include the order status, shipping method, estimated delivery, tracking number and tracking link, delivery status and the order's history. Switch on **Track orders** on the agent's **Actions** tab to use this; see [agent capabilities](/agents/capabilities). ## Events for automated campaigns These Zid events are available as triggers when you create an [automated campaign](/campaigns/automated-campaigns): | Event | Sent when | | - | - | | **Order Created** | A new order is created | | **Order Status Updated** | An order's status changes | | **Order Payment Status Updated** | An order's payment status changes to paid or unpaid | | **Abandoned Cart Created** | A shopping cart is abandoned | | **Abandoned Cart Completed** | An abandoned cart is completed | For abandoned-cart messages, Popcorn checks whether that customer has placed an order since the cart was abandoned and skips the message if they have. ## Subscription through the Zid App Market If you buy a Popcorn plan in the Zid App Market, Zid notifies Popcorn and the plan is applied to the workspace whose connected Zid store matches. Popcorn recognises the **Cheese** plan (monthly and yearly) and plans named **Salt** or **Cheese**; a plan it does not recognise is treated as the free plan. | Zid event | What Popcorn does | | - | - | | Subscription activated, renewed or upgraded | The plan becomes active until the end date Zid reports. | | Renewal reminder (sent three days before the end date) | Nothing changes. | | Subscription suspended (Zid ends the paid period, usually within a day of the end date) | The plan ends, with its credits. **Plan and billing** shows **Ended on** with the date, and your agent stops replying to customers and hands their conversations to your team until you renew. If the suspension never arrives, the plan ends two days after the end date. | | Subscription expired (when Zid removes the app, five days after the end date) or refunded | Access under that plan ends; a refund ends it at once. | | App uninstalled from Zid | Nothing changes in Popcorn. The store stays connected until you contact support. | If you subscribe before connecting the store in Popcorn, the subscription is held and applied as soon as you connect. See [plans and credits](/billing/plans-and-credits) and [top-ups and renewal](/billing/top-ups-and-renewal). ## Related * [Connect your store](/integrations/overview) * [Store health](/integrations/commerce-health) * [Troubleshooting](/integrations/troubleshooting) # Popcorn Documentation Source: https://docs.trypopcorn.ai/introduction Learn what Popcorn does for your store and find the guide for each part of the app, from setup to campaigns and billing. Popcorn is an AI agent for e-commerce merchants. It answers customers on WhatsApp and in your website chat, recommends products from your connected Shopify, Salla, or Zid store, completes orders and tracks them inside the conversation, and hands over to your team when a person is needed. Your team works the same conversations from the **Inbox**, and you reach customers at scale with WhatsApp campaigns from **Campaigns**. These docs are written for the merchants and the support and marketing teams who run the workspace. Nothing outside the **API Reference** tab requires code. ## Start here > **[Quickstart](/quickstart)** > > From sign-up to your agent's first WhatsApp conversation, step by step. > **[How Popcorn works](/how-popcorn-works)** > > Workspace, agents, channels, the Inbox, credits, and the words the app uses. ## Set up your workspace > **[Connect your store](/integrations/overview)** > > Shopify, Salla, Zid, and the Meta catalog: what syncs and what it unlocks. > **[Connect WhatsApp](/channels/whatsapp)** > > Give your agent a WhatsApp number through Meta's sign-up window. > **[Set up your AI agent](/agents/overview)** > > Instructions, capabilities, testing, and publishing changes. > **[Knowledge](/knowledge/overview)** > > The folders and articles your agent answers from. ## Run it every day > **[Inbox](/inbox/overview)** > > Conversations, **Needs you**, handovers, and the WhatsApp 24-hour window. > **[Campaigns](/campaigns/overview)** > > WhatsApp templates, one-off campaigns, and automated campaigns. > **[Plans and credits](/billing/plans-and-credits)** > > What uses credits, plans, top-ups, and the usage report. > **[AI assistants](/ai-assistants/overview)** > > Run your workspace from ChatGPT, Claude, or Codex. ## For developers > **[API Reference](/api-reference/introduction)** > > Send template messages with an API key and receive message status webhooks. Need help? Click **Help** in the app sidebar and choose **Ask Nour** for in-app help, or email [wecare@trypopcorn.ai](mailto:wecare@trypopcorn.ai). New releases are listed in the [changelog](/changelog). # Connect knowledge to an agent Source: https://docs.trypopcorn.ai/knowledge/connect-to-agents Give an agent access to knowledge folders, publish the change, test it, and confirm which articles the agent actually uses. An agent only answers from the folders it has been given access to. Use this page after you have published articles and want an agent to start using them, or when you want to check whether an agent is really reading a folder. ## Before you start * The articles you want the agent to use are published. Drafts are never used, whatever folders are connected. * You know which agent handles the conversations in question. Each agent has its own folder access; see [Agents overview](/agents/overview). ## Connect folders to an agent **1. Open the agent** Click **Agent** in the sidebar and open the agent. **2. Turn folders on** Open the **Knowledge** tab. The **Knowledge base** panel ("The agent answers from the knowledge bases you turn on.") lists every folder with its description and a switch. Turn on each folder the agent should search. If you have none yet, **New knowledge base** takes you to **Knowledge** to create one; once you have some, **Manage knowledge** does the same. **3. Save and publish** Click **Save and review**, then **Publish changes** in the dialog. Connecting a folder is part of the agent's draft: until you publish, live conversations keep the previous setup. See [Test and publish](/agents/test-and-publish) for what publishing offers. > [!NOTE] > > The same thing has two names in the app. On **Knowledge** it is a **folder**; on the agent's **Knowledge** tab it is a **knowledge base**. Both mean one group of articles. At the top of the same tab, **What it knows** says whether Popcorn's nightly check has questions for you about this agent's Knowledge (***N* questions** or **Up to date**), with **Review** or **Open Knowledge**. See [Review what your agent learned](/knowledge/knowledge-check). Turn a folder off and publish again to stop the agent using it. Deleting a folder on **Knowledge** deletes its articles, so any agent still connected to it finds nothing there. ## How the agent uses connected folders * The agent gets one search per connected folder. The folder's description is what tells it which folder fits a question, so a folder called *Policies* with the description *Return, exchange, refund and warranty rules* is far more useful than one called *Misc* with no description. * The agent takes a folder's name and description when you save the agent. If you rename a folder or rewrite its description later, the agent picks up the new wording the next time you save the agent with **Save and review** and publish it. * A search returns the best-matching passages from that folder's published articles, and the agent writes its reply from them. * The agent decides on every message whether to search at all. An agent on Popcorn's rules is told to search Knowledge before it answers a question about your store, and to offer your team when nothing covers a point instead of guessing. On an agent with custom instructions, your instructions decide; see [Writing custom instructions](/agents/writing-instructions). ## Test it **1. Publish first** The test chat talks to the published version of the agent, so publish the connection before you test it. **2. Ask a question** In the **Test your agent** panel (from 1280 pixels wide) or the **Test agent** dialog, ask a question an article answers, in the words a customer would use. Under the reply, **Searched the knowledge base** shows that the agent looked in your folders. **3. Check the reply** The reply should match the published text. If it does not, work through [Troubleshooting](/knowledge/troubleshooting). **4. Look at the sources** Chats from the agent page are real conversations, so open yours in the Inbox. Under the AI reply, **Searched the knowledge base** has a **Sources (*N*)** button when specific articles were cited. It opens **Message source**: **Tool used** names the search the agent ran, and **Knowledge used** links each **Article** it cited, with the version that was live (for example **v3**). If the agent searched but cited no specific article, the button reads **Details** and **Knowledge used** links to the folder that was searched. ## Confirm articles are being used On **Knowledge**, the **Used by agent** column shows a badge for every article the agent matched in the last 30 days. Open an article and look at **Details** for the figures: | You see | What it tells you | | - | - | | **Not used yet** | No search has returned this article in the last 30 days. Either no customer asked about it, its folder is not connected to the agent handling those chats, or the article is still a draft. | | **Matched *N* times** | Searches returned the article, but the agent has not yet written a reply from it. | | **Cited *N* times · last used *time*** | The agent used it in replies. | Click either figure to open **Recent conversations**. Each entry has an **Open conversation** link to read how the article was used, and conversations where it was cited carry a **Cited** tag. The same **Sources (*N*)** button appears on live customer conversations in the Inbox, for WhatsApp and Website chat alike, so you can audit real answers the same way. See [Working with conversations](/inbox/working-conversations). ## Several agents, different knowledge Folders are the way to give agents different knowledge. A sales agent on Website chat can have *Products and sizing* and *Delivery*; a support agent on WhatsApp can add *Returns* and *Warranty*. Each agent searches only its own folders, and an article is used by every agent whose folders include it. ## Related > **[Create folders and articles](/knowledge/writing-articles)** > > Write, import and publish the articles the agent will use. > **[Knowledge, tools, channels and notifications](/agents/connect-knowledge-tools-channels)** > > Everything else you connect on the agent page. > **[Test and publish](/agents/test-and-publish)** > > Drafts, publishing scope and version history for agents. > **[Custom tools](/tools/overview)** > > For answers that need a live lookup in another system. # Review what your agent learned Source: https://docs.trypopcorn.ai/knowledge/knowledge-check Answer the questions your agent has after reading your team's WhatsApp replies, and see or undo what it added to Knowledge. Every night Popcorn reads the WhatsApp chats your team answered and compares what your team told customers with what your agent's Knowledge says. When something is missing, out of date, or contradicted by another article, it drafts the fix and asks you about it on **Knowledge**. Nothing changes until you answer, and the agent uses what you add in its next chats. Popcorn calls this the Knowledge check. It costs no credits. ## Before you start * The check runs for each agent that answers a WhatsApp number. An agent that only answers Website chat is not checked. * It learns from WhatsApp chats of the last 30 days in which someone on your team replied. With no such chats the check skips the agent, unless the agent still has its [old instructions article](#the-old-instructions-article): then it runs anyway, to move those facts to their homes, and can also ask about articles that contradict each other or are out of date. * Anyone who can open **Knowledge** can read the questions. Owners, Admins and Managers can answer them; Agents and Viewers can step through with **Next** and see **Only people who can edit Knowledge can answer.** Adding a fact publishes it, so a custom role needs **Full access** on **Knowledge base**, plus **Edit** on **Products** for a product note and **Edit** on **Agents** for a handover rule. See [Team and roles](/settings/team-and-roles). * There is no switch for the check in your workspace. Popcorn can turn it off for a store; ask support if you need that. While it is off, none of what this page describes appears. ## Where you see it On **Knowledge**, a panel above your articles says where your agent stands: | Panel title | What it means | | - | - | | **Your agent has *N* questions for you** | Fixes are waiting. The line under it says where they come from (**Learned from your team's answers in chats** or **From its old instructions**) and when the last check ran (**Checked** *time*). | | **Your agent is up to date** | Nothing is waiting. The line under it can add the share of your customers' WhatsApp chats in the last 30 days that the agent answered with no reply from your team: ***N*% answered without your team**. | | **Your agent starts learning from your team's chats tonight** | No check has finished yet. | **Review** starts the questions. **Recently added**, when there is anything in it, opens what was added in the last week, what you left for later and what the check looked at and left alone. Your articles follow under **Articles** ("Everything your agent can answer from"), and their **Status** column shows what the check found in each one; see [Knowledge overview](/knowledge/overview). On the agent page, the **Knowledge** tab opens with **What it knows**: the same count for that agent (***N* questions** or **Up to date**), when it was last **Checked against your chats**, and **Review** or **Open Knowledge**. ## Answer the questions **1. Open the review** On **Knowledge**, click **Review**. Questions open one at a time, with ***N* of *M*** and a progress bar at the top. On a phone they open as a sheet from the bottom of the screen. **2. Read the question** Above the question is what it is about: **Customers asked "…"** with the customer's own question, **From your old instructions**, or the kind of problem, such as **Out of date** or **Conflicting**. With more than one agent, the agent's name comes first. Under the question is the fact in the words the agent will read, then where it goes (**Goes to** …) and every line it replaces (**replaces "…"**). **3. Answer** Click the yes button, **Edit**, **No** or **Skip** (see [Your answers](#your-answers)). The next question shows by itself. **4. Finish** The last screen says what the agent learned (**Your agent learned *N* new things**, or **Nothing added this time**). If you skipped some, it reads **Done for now** and offers **Review the *N* skipped**; otherwise **All done**. Facts learned from chats come first, the most asked first, then contradictions between articles that no customer has asked about. Facts from old instructions follow, then the removal of an old instructions article once nothing in it is waiting. ## The questions | Question | What it is about | Yes button | | - | - | - | | **Is this right?** | A fact your team gives customers that Knowledge lacks, a correction to what Knowledge says, or content that is out of date, such as a past season's delivery times. | **Yes, add it** | | **Which answer is right?** | Your articles, or your team and an article, give different answers. Each answer is listed with where it comes from. The one marked **Matches what your team does** is selected to start; when none is marked, pick one first. | **Yes, add it** | | **Should your team take these chats?** | A kind of chat your team takes over. Shows what the agent will say (**The agent says**) and, if there is one, the tag the chat gets. | **Yes, hand them over** | | **Keep this?** | A fact that was only in the agent's old instructions, which an agent on Popcorn's rules doesn't read. | **Keep it** | | **Remove the old instructions?** | Everything in an old instructions article has a home now. See [The old instructions article](#the-old-instructions-article). | **Remove** | ## Your answers * The yes button (**Yes, add it**, **Keep it**, **Yes, hand them over** or **Remove**) applies the fix straight away (see [Where a fact goes](#where-a-fact-goes)). A message confirms it (**Added to Knowledge**, **Added to the product note**, **Hand-over rule added** or **Old instructions removed**), and **Added** with **Undo** shows over the next question so you can take it back at once. After an Undo the same question comes up next. * **Edit** swaps the fact for a **Wording** box so you can change it first; **Use the suggestion** goes back to Popcorn's wording. It is offered when the fix adds one piece of text. The wording can't be empty, and in a fact about a product it can't state a price: the agent reads prices from your catalog. * **No** (**None is right** on a choice) asks **What's not right?**: **It isn't right**, **It changes too often to write down**, **My team answers this, not the agent**, **It belongs somewhere else** or **Something else**. Pick one, add a note under **What's right instead (optional)** if you like, and click **Don't add**. The same problem is not raised again for this agent for 90 days. * **Ask me later**, next to **Don't add**, sets the fix aside for 14 days. After that it comes back if the check still finds it. * **Skip** moves on and leaves the question waiting for next time. * **Keep all *N* from the old instructions**, under a **Keep this?** question, keeps every remaining fact from the old instructions in one go, skipped ones included, each with the answer you picked and any wording you edited. It shows **Adding *N* of *M*…**, then lists any that couldn't be added and why (***N* couldn't be added**). One **Undo** takes back all it kept. Popcorn takes your answers into account when it drafts the next fixes for that agent: what you turned down and why, and how you reworded facts. ## How we know Under each question, **How we know** sums up where the fix comes from in one line (**From *N* chats**, **From your old instructions** or **Your articles disagree**). Where it can, Popcorn tries a fix on some of the past chats it came from before it reaches you; when answers got better, the line adds **Right in *X* of *Y* replays, up from *Z***. A fix that made answers worse in that test is held back. Click **How we know** to open: * **Chat 1**, **Chat 2**, **Chat 3**: the chats the fact came from, opened in place on the messages where the customer asked and your team answered, with **Open in Inbox** to read the whole chat. * **A customer asked**, **Your agent says today** and **With this**: one question from those chats, what the agent answers now, and what it answered with the suggested fix in Popcorn's test. * What your articles say now, with a link to each article, or **Your old instructions said**. ## Where a fact goes Each fact goes to one home: facts about your store (delivery, payment, returns, fees) to an article, facts about one product to that product's note, and the chats your team should take to a handover topic. Fixes never write a product's price or stock level; the agent reads those from your catalog. | Goes to | What adding it does | | - | - | | An article, by its title | Adds the line to the article, or puts it in place of the lines shown after **replaces**, in every article that has them, and publishes the article. | | **New article:** *title* | Creates and publishes a new article in a folder the agent uses. | | **Note on** *product* | Adds the line to the product's **Tell the agent why (optional)** note, and to its variants' empty notes. A note holds 500 characters in all. See [Products](/products/catalog). | | **Actions › Hand over** | Adds a handover topic to the agent, under **Handover topics** on its **Handoff** tab, and publishes the agent. The agent needs **Hand over to your team** switched on and no unpublished changes. See [Capabilities](/agents/capabilities). | An article a fix changes is published under the name of the person who answered and shows up in its **History** like any other version. For a week, its status in the article list reads **New this week** or **Updated this week**. ## Recently added and Undo **Recently added** lists three kinds of line: * Fixes added in the last 7 days, each with **Added** *time* and, once the agent has used an article fix in chats, **Answered *N* chats since, your team stepped into *M***. **Undo** takes the fix back: an edited article is published again with its earlier text, a new article is deleted, a product note gets its old text, a handover topic is removed, and a removed old instructions article comes back. The question returns to your list. Once someone has edited what the fix changed, Undo is refused and you change it in place instead. * Fixes you left for later, each with the date it comes back (**Back** *date*) and **Review** to answer it now. * Topics customers asked about that Knowledge already answers right, with why the check left them alone. Click an added or postponed fix to see how the check knew. ## The old instructions article When Popcorn moved existing agents onto Popcorn's rules, agents that were answering customers with their own instructions had them saved word for word as a published article named **Previous instructions of *agent name***. It sits in the folder that holds most of that agent's articles and shows as published by your workspace Owner. An agent on Popcorn's rules doesn't read instructions, so the article keeps everything they said where the agent searches. For agent types, see [Popcorn's rules and Voice](/agents/popcorns-rules). The article mixes facts with rules about how to behave, so its status on **Knowledge** reads **Old instructions**. The review sorts it out: 1. Each fact found only in it comes up as **Keep this?**. Keep it and it moves to its home: an article, a product's note or a handover topic. Say no and it goes with the article. 2. Once nothing in it is waiting, **Remove the old instructions?** explains that everything in the article has a home now and lists each rule with where it went: **Moved**, **Popcorn's rules**, **Voice**, or **Goes with the article** for anything that was not moved. Rules about how to behave are already covered by Popcorn's rules or the agent's Voice; check the **Goes with the article** lines and add anything you still need yourself. 3. **Remove** deletes the article. **Undo** in **Recently added** brings it back. You can edit or delete the article yourself like any other, but deleting it before its facts have moved takes those facts away from the agent. If another agent also answers from its folder, the article stays: its facts still move out for this agent, but the review doesn't offer to remove it. ## Related > **[Knowledge troubleshooting](/knowledge/troubleshooting)** > > An answer couldn't be applied, or no questions show. > **[Knowledge overview](/knowledge/overview)** > > Folders, articles, and what each status means. > **[Products](/products/catalog)** > > Where a product's note lives. > **[Capabilities](/agents/capabilities)** > > Hand over to your team and the Handoff tab. # Knowledge overview Source: https://docs.trypopcorn.ai/knowledge/overview How folders and articles give your agent its answers, what Draft and Published mean, and how to see which articles the agent uses. Knowledge holds everything your agent should know that is not in your product catalog: shipping and delivery rules, returns and exchanges, payment options, store policies, opening hours, and the questions your team answers every day. When a customer asks, the agent searches the folders connected to it and writes its reply from the articles it finds. Open it with **Knowledge** in the sidebar, under **Your agent**. Every night Popcorn also compares your Knowledge with what your team tells customers in WhatsApp chats, and asks you before it adds or corrects anything. See [Review what your agent learned](/knowledge/knowledge-check). ## How it is organized | Term | What it is | | - | - | | Folder | A group of articles. Agents are given access folder by folder, so a folder is also the unit you connect to an agent. Each folder has a **Name** and a **Description** that helps the agent pick the right folder to answer from. On the agent's **Knowledge** tab the same folders are listed as knowledge bases. | | Article | One page of knowledge with a title and a formatted body. An article belongs to exactly one folder. | | Draft | The version you are editing. The agent never uses a draft. | | Published version | The version the agent answers from. Every time you publish, Popcorn keeps the previous version in the article's **History**. | Onboarding creates your first folder, **Business Knowledge Base**, and connects it to the agent it created. Popcorn fills it with up to 8 pages it picked from your website, or with the description you wrote if you had no website. Those pages are live for the agent from the start; until you open one for the first time, its **Used by agent** and **Last updated** cells stay empty. See [Create folders and articles](/knowledge/writing-articles) for what to do with them next. You may also find an article named **Previous instructions of *agent name*** that nobody on your team wrote. Popcorn saved an agent's instructions there when it moved the agent onto Popcorn's rules, so nothing they said was lost; see [The old instructions article](/knowledge/knowledge-check#the-old-instructions-article). ## What the agent does with your articles 1. You connect one or more folders to an agent and publish the agent. See [Connect knowledge to an agent](/knowledge/connect-to-agents). 2. When a customer message needs store knowledge, the agent searches the connected folders. Each folder is searched separately, and the folder's description tells the agent what kind of question that folder answers. 3. The search returns the best-matching passages from the published articles in that folder. The agent writes its reply from those passages. 4. Popcorn records which articles were matched and which were cited in the reply. This powers **Used by agent** on the Knowledge page and **Sources** in the Inbox. Only published content takes part in step 3. A draft, an unsaved edit, or a restored but unpublished version never reaches the agent. > [!TIP] > > Articles are matched passage by passage, not as a whole. Open an article and click **See what your agent reads** to see exactly which passages the agent can find. A fact buried in a long passage about something else is easy to miss; a short article with one clear topic is easy to find. ## The Knowledge page The header has **New folder** and **New article**. Above the articles, a panel says whether your agent has questions for you (**Your agent has *N* questions for you**, with **Review**) or **Your agent is up to date**; the articles follow under **Articles**. See [Review what your agent learned](/knowledge/knowledge-check). Above the table, the folder picker reads **All folders** or **Folder · name**. When you pick one folder, a **⋯** menu next to the picker offers **Rename folder** and **Delete folder**. **Search articles** looks at article titles only, not their content, and the table shows 10 articles per page. The table shows one row per article: | Column | Meaning | | - | - | | **Title** | The article title, with where the content came from underneath: **Written** (typed in Popcorn), **Web page** (imported from a link) or **Document** (uploaded file). Untitled drafts show as **Untitled article**. | | **Folder** | The folder the article lives in. Shown only when you have more than one folder and the picker is on **All folders**. | | **Status** | **Published** once the article has a published version, otherwise **Draft**. An article with newer unpublished edits still reads **Published** here; open it to see **Unpublished changes**. A published article can show what the nightly check found instead: **Old instructions** (it gives the agent rules rather than facts), **Conflicts** or **Out of date** (a question about it is waiting in **Review**), or **New this week** / **Updated this week** (a fact you added from **Review** wrote it). | | **Used by agent** | A **Used by agent** badge when the agent has matched the article in a conversation during the last 30 days, otherwise **Not used yet**. | | **Last updated** | When the article was last saved. | Click a row to open the article. The **⋯** menu at the end of a row offers **Delete**. On a phone, the status and date sit under the title instead of in their own columns. When you have no articles yet, the page shows **No articles yet** with **New article** in the middle of the page instead of the header. **New article** opens three choices: **Write from scratch**, **Import from a link** and **Upload a document**. ## Draft and published Every article page shows a badge next to the title and a line under it that says whether the agent uses what is on screen. | Badge | Line under the title | What it means | | - | - | - | | **Draft** | **Draft. Your agent can't use this article until you publish it.** | The article has never been published. | | **Published** | **Last published by *name* on *date*** | A published version is live for the agent. | | **Unpublished changes** | **Unpublished changes. Your agent still uses the version published on *date*.** | You have edits, saved or not, that the agent does not use yet. | | **Publishing…** | | A new version is being prepared. The agent keeps using the previous one until it is ready. | | **Publish failed** | | The new version could not be prepared. A banner explains and offers **Publish again**. | Publishing is the only action that changes what the agent answers; adding a fact from **Review** publishes too. Saving a draft, restoring an old version or previewing never does. Deleting an article removes it from the agent immediately. ## Used by agent Open an article and look at **Details** to see the numbers behind the badge: * **Matched *N* times**: a search returned the article in the last 30 days, but the agent did not necessarily use it in a reply. * **Cited *N* times · last used *time***: the agent used the article when writing a reply. * **Not used yet**: no search has returned it in the last 30 days. Click the figure to open **Recent conversations**, a list of the conversations that used the article, each with an **Open conversation** link. Conversations where the article was cited carry a **Cited** tag. In the Inbox, an AI reply that searched your knowledge has a line under it, **Searched the knowledge base**, with a **Sources (*N*)** button when specific articles were cited. It opens **Message source**, which lists the **Tool used** and, under **Knowledge used**, each article the agent cited with the version that was live at the time. See [Inbox overview](/inbox/overview). ## Who can do what Permissions are set per role on **Knowledge base** under **Settings → Roles and permissions**: * **Owner**, **Admin** and **Manager** have full access: create, edit, publish, restore and delete. * **Agent** and **Viewer** can read articles but not change them. Answering the questions in **Review** publishes to your articles, so it needs the same access as publishing; see [Review what your agent learned](/knowledge/knowledge-check). Publishing needs permission to publish; without it the **Publish** button is disabled and shows **You don't have permission to publish**. Restoring an earlier version needs permission to edit (**You don't have permission to restore versions**). The role editor has no separate **Publish** column: for a custom role, publishing comes with **Full access** on **Knowledge base**. See [Team and roles](/settings/team-and-roles). ## Knowledge or a tool? Knowledge is for facts that stay the same from one conversation to the next: policies, procedures, prices you write down, FAQs. For anything the agent has to look up live in another system, such as a booking, a loyalty balance or a repair status, create a [custom tool](/tools/overview) instead. ## Next steps > **[Create folders and articles](/knowledge/writing-articles)** > > Write, import, preview, publish and manage versions. > **[Connect knowledge to an agent](/knowledge/connect-to-agents)** > > Give an agent access to folders and check that articles are used. > **[Review what your agent learned](/knowledge/knowledge-check)** > > Answer the questions from the nightly check and undo what it added. > **[Troubleshooting](/knowledge/troubleshooting)** > > The agent ignores an article, answers are stale, an import fails. > **[Popcorn's rules and Voice](/agents/popcorns-rules)** > > Agent types, and what an agent follows besides its Knowledge. # Knowledge troubleshooting Source: https://docs.trypopcorn.ai/knowledge/troubleshooting Fix an agent that ignores articles, outdated answers, failed imports, rejected folder names, publishing problems and answers Review can't apply. Most knowledge problems come down to one of four things: the article is not published, its folder is not connected to the agent, the agent's change was never published, or the fact is not in a passage the search can find. Work through the checks below in order. ## The agent ignores an article > **Is the article published?** > > Open it from **Knowledge**. If the badge reads **Draft** ("Draft. Your agent can't use this article until you publish it."), click **Publish**. If it reads **Unpublished changes**, the agent still uses the version published on the date shown; only the published version counts, so click **Publish** to send your edits. > **Is its folder connected to the right agent?** > > Click **Agent** in the sidebar, open the agent and check the **Knowledge** tab. The folder that contains the article must be switched on. If several agents handle your channels, check the one connected to the channel the conversation came in on. > **Did you publish the agent after connecting the folder?** > > Connecting a folder is a draft change on the agent. If the header still shows **Publish changes**, live conversations are using the previous setup. Click it and publish. See [Test and publish](/agents/test-and-publish). > **Can the search find the fact?** > > Click **See what your agent reads** on the article. The agent matches passages, not whole articles. If the sentence you expect it to use sits in a passage full of other topics, give it its own heading or its own article, publish, and test again in **Test your agent**. > **Does the folder description point the agent there?** > > The agent reads each folder's description to decide which folder to search. Pick the folder on **Knowledge**, open the **⋯** menu next to the picker, choose **Rename folder** and write a description that names the topics inside it. The agent takes a folder's name and description when you save the agent, so save and publish the agent afterwards, for example together with your next change on it. > **Do the instructions get in the way?** > > An agent on Popcorn's rules is told to search Knowledge before answering questions about your store, so this applies only to an agent with custom instructions. Instructions that tell it to keep answers short, stay on products, or never discuss a topic can stop it from searching. Review them with [Writing custom instructions](/agents/writing-instructions). To see what really happened, open the conversation in the Inbox and look under the AI reply. **Searched the knowledge base** with a **Sources (*N*)** or **Details** button means the agent searched; the button opens **Message source**, where **Knowledge used** lists the articles the agent cited, or links to the folder it searched when it cited none. No such line means the agent did not search knowledge for that reply. ## The agent gives outdated answers * The agent uses the **last published version**. Open the article and click **History** to see which version is live and when it was published. If your correction is sitting in a draft, click **Publish**. * Right after publishing, the previous version stays live while the new one is prepared (the badge reads **Publishing…**). Give it a moment and test again. If a **Still publishing** banner appears, click **Check again** in a few minutes. * Imported pages and documents are a copy taken at import time. When your website changes, the article does not update itself: edit the article and publish, or import the page again and delete the old one. * Pages captured during onboarding are live from the start with the text your website had at that time. If that page is now wrong, delete the article and import the page again from its link, or write the correct version as a new article and delete the old one. * Two articles that contradict each other can both be matched. Search **Knowledge** for the topic and delete or merge duplicates. * Check **Review** on **Knowledge**. When your team has been answering a question differently from your articles, the nightly check asks about it, and the article's status reads **Out of date** or **Conflicts** until you answer. See [Review what your agent learned](/knowledge/knowledge-check). ## Import from a link fails A failed import shows **Couldn't import this page** with a reason underneath. When Popcorn has no readable reason, the line reads "Check that the link opens in your browser, then try again." | Message | What to do | | - | - | | **Enter a link to import.** | The address field was empty. | | **Enter a full URL, starting with https\://** | The address is not a full web address. Paste it from the browser's address bar. | | *Importing that link is taking too long — please try again* | The page took more than 25 seconds to fetch. Try again; if it keeps happening, copy the text and use **Write from scratch**. | | **Check that the link opens in your browser, then try again.** | The address could not be opened. Check that it opens in a private browser window without logging in. | | *The page appears to have no readable content.* | The page loaded but has no text Popcorn can extract, for example a page that is only images or is built entirely after login. Paste the text instead. | | *URL import is not available right now…* | Importing is unavailable at the moment. Try later or paste the text. | Popcorn fetches one page per import; links inside the page are not followed. Import each page separately. ## Uploading a document fails A failed upload shows **Couldn't import this document** with a reason underneath, or "Check that the file opens and isn't password protected, then try again." * Supported types are PDF, Word (`.doc`, `.docx`), plain text, CSV, JSON and HTML, up to 20 MB. The file picker only offers these types; any other type is refused. * *The file appears to have no readable text.* means no text could be extracted. Scanned PDFs are images, not text; export the document with text or paste the content. * *Reading that document is taking too long — please try again* means extraction passed 25 seconds. Split the document or try again. * A password-protected file cannot be read. Remove the password and upload it again. ## A folder name is rejected The **Name** field shows **Use English letters and numbers, starting with a letter.** when the name uses non-Latin letters (such as Arabic), is too long once Popcorn converts it, is only a reserved word, or has no letters or numbers. **A folder with this name already exists.** means another folder has the same name, and **Enter a folder name.** means the field was empty. The dialog stays open so you can change the name and try again. The full rules are in [Create folders and articles](/knowledge/writing-articles). Descriptions have no such rules and can be in any language, including Arabic. ## I cannot publish * **Publish** is disabled and shows **You don't have permission to publish** when your role cannot publish knowledge. Owners, Admins and Managers can; Agents and Viewers cannot. Ask an Owner or Admin to publish, or to change your role under **Settings → Roles and permissions**; a custom role needs **Full access** on **Knowledge base**. See [Team and roles](/settings/team-and-roles). * **Publish** is disabled and shows **Nothing new to publish** when the article is already published and you have not edited it. * **Restore** is disabled and shows **You don't have permission to restore versions** when your role cannot edit knowledge. * **Couldn't publish this article** with no further detail: the dialog stays open so you can retry. If it keeps failing, click **Save draft**, reload the page and try again. * The badge reads **Publish failed** and a banner says "Your agent is still using the previous version.": click **Publish again**. * **Couldn't save your draft** means the draft was not saved. Keep the page open and click **Save draft** again before you leave. ## Review shows no questions * No panel above the articles: the check is off for your workspace, or it did not load. **Couldn't load suggestions** with **Try again** means it did not load. * **Your agent starts learning from your team's chats tonight** stays for days: the check only reads WhatsApp chats of the last 30 days in which someone on your team replied, and only for agents that answer a WhatsApp number. An agent on Website chat alone, or a WhatsApp number your team never replies on, gives it nothing to learn from, unless the agent still has its old instructions article (see [The old instructions article](/knowledge/knowledge-check#the-old-instructions-article)). * **Your agent is up to date**: nothing is waiting. **Recently added** shows what was added this week, what you left for later and what the check left alone. * A question you answered **No** to is not asked again for 90 days, and one you left with **Ask me later** comes back after 14 days only if the check still finds it. ## An answer in Review couldn't be applied A failed answer shows **Couldn't apply the fix** (or **Couldn't dismiss the fix**, **Couldn't leave it for later**, **Couldn't undo the fix**) with the reason under it. | Reason | What to do | | - | - | | **The article has unpublished edits. Publish or discard them first.** | Adding the fact would publish your draft too. Click **Open article** in the message, publish your edits, then answer again. | | **The agent has unpublished changes. Publish or discard them first.** | A handover rule publishes the agent. Click **Open agent**, publish or discard your changes, then answer again. | | **Turn on the Hand over action for this agent first, then apply this again.** | Switch on **Hand over to your team** on the agent's **Handoff** tab and publish. See [Capabilities](/agents/capabilities). | | **This agent has no Knowledge collection to add the article to. Connect one in the agent's Knowledge tab.** | Turn on a folder on the agent's **Knowledge** tab and publish. See [Connect knowledge to an agent](/knowledge/connect-to-agents). | | **The article changed since this was found. It will be checked again tonight.** | Someone edited the article since, and the lines the fix replaces are gone. The next check works from the new text. | | **The product's note changed since this fix was found. It will be checked again tonight.** | The same, for a product's note. | | **The product is no longer in your catalog.** | The fix was for a product that is gone. | | **Apply or dismiss the fixes that move what this article holds first.** | An old instructions article still has facts waiting. Answer its **Keep this?** questions first. | | **Another agent still answers from this article, so it stays.** | Another agent uses the old instructions article's folder. Its facts still move out; the article stays. | | **Leave the price out: the agent reads prices from your catalog.** | Your edited wording for a product fact states a price. Remove it. | | **Write the wording, within the length allowed.** | The edited wording is empty or too long. | | **This fix was updated since you opened it. Read it again before applying.** | A newer check redrafted the fix. Read it again and answer. | | **This suggestion was already applied or dismissed. Refresh the page.** | It was already answered, for example by a teammate. The list reloads. | | **What this fix changed has been edited since. Change it in place instead.** | **Undo** can't take the fix back once someone edited what it wrote. Edit the article, note or handover topic yourself. | | **This fix can't be undone any more.** | Nothing is left to undo. | ## Restore replaced my draft **Restore** in **Version history** creates a new draft from the chosen version and replaces the draft you had. Popcorn warns before doing so when you have unpublished edits. The published version is untouched, so nothing changed for customers; use **Compare** to see what differed and re-apply your edits. ## An article or folder is gone * Deleting an article or a folder is permanent and removes the content from the agent immediately. There is no trash. If it was imported, import it again; if it was written in Popcorn, rewrite it. * **Article not found** ("It may have been deleted.") on an article page means it was deleted, or the link belongs to a different workspace. * An article named **Previous instructions of *agent name*** that disappeared was removed through **Remove the old instructions?** in **Review**. For a week, **Undo** in **Recently added** brings it back; see [The old instructions article](/knowledge/knowledge-check#the-old-instructions-article). ## Still stuck? Click **Help** in the sidebar and choose **Ask Nour**, or write to support with the article title, the agent name, and a link to the conversation where the answer went wrong. ## Related * [Knowledge overview](/knowledge/overview) * [Create folders and articles](/knowledge/writing-articles) * [Connect knowledge to an agent](/knowledge/connect-to-agents) * [Review what your agent learned](/knowledge/knowledge-check) * [Agent troubleshooting](/agents/troubleshooting) # Create folders and articles Source: https://docs.trypopcorn.ai/knowledge/writing-articles Create folders, write or import articles, preview how the agent reads them, publish, and restore earlier versions. Use this page when you are adding knowledge to Popcorn: a new returns policy, a delivery FAQ, a page from your website, or a PDF from your team. Everything here happens on **Knowledge** in the sidebar. ## Before you start * Articles land in a folder. Onboarding created **Business Knowledge Base**; create more folders if different agents need different knowledge, because agents are given access folder by folder. * Owners, Admins and Managers can create, edit, publish and delete articles. Agents and Viewers can only read them. **Publish** needs permission to publish; see [Team and roles](/settings/team-and-roles). ## Create a folder **1. Click New folder** In the header of **Knowledge**, click **New folder**. **2. Name and describe it** Enter a **Name** (for example, *Shipping and returns*) and a **Description**. The description is shown to the agent so it can decide when to search this folder, so write what kind of questions it answers: *Delivery times, shipping fees, and how to return or exchange an order.* **3. Create it** Click **Create folder**. You see **Folder created** and the page opens inside the new folder, so anything you add next lands there. Each folder becomes a search the agent can run, so the name has to follow a few rules. When one is broken the field shows an error and the dialog stays open so you can fix the name and try again. | Rule | What you see | | - | - | | Use English (Latin) letters, numbers and common symbols. Arabic and other scripts are refused; the description can be in any language. | **Use English letters and numbers, starting with a letter.** Popcorn may add a suggested name: *For example "…"*. | | Keep it short. Popcorn converts the name before using it: spaces become underscores and symbols are spelled out (`&` becomes *and*, `-` becomes *dash*), and the result must fit in 49 characters. A name of up to 49 letters, numbers and spaces always fits. | The same message. | | Do not use a name that is only a reserved word: system, admin, root, api, function, call, execute, eval, class, constructor or prototype. | The same message. | | Include at least one letter or number. | The same message. | | Each name can be used once. | **A folder with this name already exists.** | | Enter a name. | **Enter a folder name.** | To change a folder later, pick it in the folder picker, open the **⋯** menu next to the picker and choose **Rename folder**. You can change the name and the description, then click **Save folder**. Changes to a name or description reach an agent that already uses the folder the next time you save and publish that agent; see [Connect knowledge to an agent](/knowledge/connect-to-agents). > [!WARNING] > > **Delete folder** deletes every article in the folder and your agent stops using them right away. The confirmation reads "This deletes the folder and every article in it. Your agent stops using them right away. This can't be undone." ## Write an article from scratch **1. Pick the folder** Choose the folder in the folder picker so the article is created there. On **All folders**, a written article goes to your oldest folder. **2. Create the article** Click **New article → Write from scratch**. A blank draft opens. **3. Write** Type the title in the **Article title** field (it reads **Untitled article** until you do) and the content below it. The toolbar offers **Bold**, **Italic**, **Strikethrough**, **Heading 1**, **Heading 2**, **Bulleted list**, **Numbered list**, **Quote**, **Code block**, **Link**, **Undo** and **Redo**. You can paste from another document; formatting that Popcorn cannot keep is dropped. **4. Save the draft** Nothing is saved while you type. Once you have edited, a bar across the top reads **Unsaved changes**: click **Save draft** (you see **Draft saved**) or **Discard** to drop your edits. A saved draft is still not used by the agent. If you try to leave with unsaved edits, Popcorn asks **Leave without saving?** with **Leave page** and **Keep editing**. A new article exists as soon as you click **Write from scratch**. If you leave without writing anything, an **Untitled article** draft stays in the list; delete it from the **⋯** menu on its row. For a **Link**, type the address in the field and click **Apply**; a bare `shop.com/faq` gets `https://` added. Only web addresses and email links are accepted, otherwise you see **Use a web address, like [https://yourstore.com/faq](https://yourstore.com/faq)**. **Remove link** takes a link off the selected text. ## Import from a link **1. Open the import dialog** Click **New article → Import from a link**. The dialog explains: "We'll fetch the page and turn it into a draft article you can edit. Your agent won't use it until you publish." **2. Enter the page address** Paste the full address under **Page link**, such as `https://example.com/help/shipping`. With more than one folder, choose where it goes under **Add to folder**. **3. Import** Click **Import**. Popcorn fetches the page and opens it as an editable draft. The page title becomes the article title. The imported page is not used by the agent until you publish it. The original text is kept in the **Attached source (*N*)** panel on the article page, read-only and with a link to the page; click the panel to open it. An empty field shows **Enter a link to import.** and an address that does not start with `http://` or `https://` shows **Enter a full URL, starting with https\://**. If the page takes longer than 25 seconds to fetch, the import stops and you can try again. Pages that need a login, block automated access, or contain no readable text also fail; see [Troubleshooting](/knowledge/troubleshooting). ## Upload a document **1. Choose where it goes** Pick the folder first, then click **New article → Upload a document**. If you have more than one folder and are on **All folders**, a dialog asks you to pick a folder under **Add to folder** and click **Choose file**. Otherwise the file picker opens straight away. **2. Pick the file** Supported: PDF, Word (`.doc`, `.docx`), plain text (`.txt`), CSV, JSON and HTML, up to 20 MB. **3. Review the draft** Popcorn extracts the text and opens it as a draft. The file name is kept in **Attached source (*N*)**. Extraction stops after 25 seconds. Extraction is text only: images, tables laid out as pictures, and scanned pages without a text layer come through empty. Clean up the draft before publishing. ## See what the agent reads Click **See what your agent reads** in the article header to open **How your agent reads this article**. It shows the article split into numbered passages ("Passage 1", "Passage 2"), the pieces the agent matches against when it searches. If the passage that mentions a fact is dominated by other topics, move that fact to its own article or heading so it gets a passage of its own. If you have unsaved edits, Popcorn saves them as a draft first so the preview matches the screen. The preview never changes what the agent uses. ## Publish **1. Click Publish** In the article header, click **Publish**. You do not need to click **Save draft** first; unsaved edits are saved as part of publishing. **2. Confirm** The dialog **Publish this article?** explains: "Your agent starts answering from this version. Later edits stay in a draft until you publish again." Click **Publish**. What happens next: * The draft becomes a numbered version (**Version 1**, **Version 2**, and so on). * The badge reads **Publishing…** and a toast says **Publishing. Your agent will use these changes in a moment.** The agent keeps answering from the previous version until the new one is ready, then switches in one step, so there is no gap. When it is ready you see **Published. Your agent now uses this version.** * If it takes longer than about three minutes, a banner reads **Still publishing** with **Check again**. * If it fails, the badge reads **Publish failed** and a banner says "Couldn't publish this version. Your agent is still using the previous version." Click **Publish again**. * The line under the title changes to **Last published by *you* on *date***. Your next edit starts a new draft and the agent keeps using the version you published until you publish again. **Publish** is disabled when you do not have permission (**You don't have permission to publish**) or when the article is already published and has no new edits (**Nothing new to publish**). There is no separate unpublish action; to stop the agent using an article, delete it. While an article has unpublished edits, **Review** on **Knowledge** can't add a fact to it, because publishing the fact would publish your draft too. Publish your edits first. ## Versions Click **History** to open **Version history**: "Every published version is kept. Compare any version with the latest, or restore one as a new draft." Versions are listed newest first, 10 per page. Each row shows the version number with **Published** or **Draft**, who published or last edited it and when, and **Compare** and **Restore** buttons. The newest version has neither button. * **Compare** shows what changed between that version and the latest, under **Comparing Version *N* with Version *M***; **Back to history** returns to the list. Versions with identical content show **These versions have the same content.** and very long articles show **This article is too long to compare here.** * **Restore** opens **Restore version *N*?**. Confirm with **Restore version** and Popcorn creates a new draft from that version ("Restored as a draft. Review it and publish when ready."). Your live answers do not change until you publish the restored draft. If you already have unpublished edits, the dialog warns that restoring replaces them with a copy of the chosen version. Restoring needs permission to edit (**You don't have permission to restore versions** otherwise). Restored drafts are labelled **Restored from version *N*** in the history. A fact added from **Review** on **Knowledge** also publishes a new version, under the name of the person who answered; taking it back with **Undo** publishes the earlier text again. See [Review what your agent learned](/knowledge/knowledge-check). ## Delete an article Open the **⋯** menu at the end of the article's row, click **Delete**, then confirm with **Delete article**. This permanently deletes the article and the agent stops using it right away. There is no undo. ## What onboarding created During onboarding Popcorn picked up to 8 pages from your website, the ones it recommends, or used the description you wrote if you had no website. It put them in the **Business Knowledge Base** folder, connected that folder to the agent it created, and made them live right away. Until you open a page for the first time, its row has no **Used by agent** value and no date. Open any of them to edit the text; from then on it behaves like any other article: your edits stay in a draft until you click **Publish**, and deleting the article removes the page from the agent. ## Related * [Connect knowledge to an agent](/knowledge/connect-to-agents) * [Review what your agent learned](/knowledge/knowledge-check) * [Troubleshooting](/knowledge/troubleshooting) * [Team and roles](/settings/team-and-roles) # Orders Source: https://docs.trypopcorn.ai/orders/overview Follow the orders your agent takes in conversations: statuses, payment methods, address collection, shipping, tracking and your store. **Orders** lists every order your agent took in a conversation, from the moment a customer starts checkout to the store confirming payment. Use it to see what was ordered, how the customer chose to pay, where it ships, and to jump back to the conversation. ## Before you start * On the agent's **Actions** tab, under **Selling and orders**, switch on **Take orders in chat** so the agent takes orders and **Track orders** so it can answer "where is my order?". See [Agent capabilities](/agents/capabilities#selling-and-orders). * Turn on the payment methods you accept under **Settings → Payment** and set up delivery under **Settings → Shipping**. See [Shipping and payment](/settings/shipping-and-payment). * A connected Shopify, Salla or Zid store is needed to create the order in your store, to send payment links, and for order tracking. Without a store, the agent can still confirm cash-on-delivery and bank-transfer orders, and Popcorn keeps them. ## The orders list The table shows **Order** (Popcorn's order number: a `#`, then "P" and six digits), **Customer**, **Items** (names, with a quantity such as "2 ×"), **Date**, **Total** in your default currency, and **Status**, newest first. Narrow windows show fewer columns. **Search orders** matches the order number (with or without the `#`), your store's order number, the customer's name, phone and email, and the shipping method's name. Click a row to open the order. With no orders yet the page says "No orders yet". ## Order details The title reads **Order #P123456**, with the date and time and, when the order exists in your store, "Store order #" and your store's number. The status badge sits beside it, and **View conversation** opens the conversation in the Inbox. | Section | What it shows | | - | - | | **Items** | Each product with its picture, quantity and unit price, and the line total. Custom options the customer filled in appear under the name, for example "Gifter name: Sara", with their extra price. | | **Payment** | **Payment method**, **Subtotal**, **Shipping**, **Cash on delivery fee** (only when one was charged) and **Total**. A missing method reads **Unknown**. | | **Customer** | The name, **Phone** and **Email**, taken from the conversation and the details the customer gave at checkout. | | **Delivery** | The **Shipping address** collected during checkout, and the name of the **Shipping** method. | A detail that was not collected reads **Not provided**. ## Statuses | Status | Meaning | | - | - | | **Awaiting address** | The customer started checkout and Popcorn created a draft; the delivery address has not been collected yet. Drafts the customer never completes stay in this status. | | **Awaiting payment** | The customer confirmed the order. Shipping and any cash-on-delivery fee have been added and, with a connected store, the order has been created there. | | **Paid** | Your store reported the payment. | ## Payment methods | Method | What the customer receives | | - | - | | **Cash on delivery** | The order is confirmed for payment at the door. If you turned on **Charge a cash on delivery fee** under **Settings → Payment**, or the customer's Zid delivery zone sets its own fee, the fee is added to the order as **Cash on delivery fee** and included in the total. | | **Bank transfer** | The agent sends the bank details you saved under **Settings → Payment**. If there are none, the agent does not offer it: it tells the customer your team will send the details and hands the conversation over. | | **Payment link** | Zid: a ZidPay link that expires after 24 hours. Salla: the Salla checkout link. Shopify: a Shopify checkout pre-filled with the items and the customer's details. Not available without a connected store. | Which methods the agent offers, and what happens if you switch all of them off, is set under **Settings → Payment**; see [Payment methods](/settings/shipping-and-payment#payment-methods). ## How the agent takes an order **1. Cart** The customer picks products from the agent's recommendations. On WhatsApp, customers can also add products from the cards the agent sends: catalog cards use WhatsApp's own cart, and the agent's other product cards carry an **Add to cart** button that adds that product to the order. Custom options on a product (a gift message, a size) are asked for at this point; see [Product catalog](/products/catalog#custom-options). **2. Address** On WhatsApp the agent sends an address form with **Country**, **City**, **Street**, **Area** and **Building/Floor/Apt.**, in Arabic or English to match the conversation. For Salla stores and Zid stores with a store URL, the agent first sends the **National Address** form: the customer enters their Saudi National Address **Short Address Code** (four letters and four digits, for example RRAD3093), Popcorn looks it up and shows a **Confirm Address** screen with street, district, city, building number, postal code and additional number. A customer can also type the short code in the chat. Where a form cannot be sent, for example in Website chat, the agent simply asks for the address in the chat. **3. Shipping check** The agent checks your delivery coverage for the customer's country: countrywide delivery, a list of supported cities, or none configured (the order proceeds with the city as given). City names are matched ignoring case, accents and Arabic marks, and common spellings count as the same city, such as Makkah and Mecca. If the country is not covered, the agent asks for a supported city or country. When several delivery options reach the city, the agent uses the one that costs this order least, and the customer can ask for another of them. The option's fee is added as a **Shipping** line, waived when the merchandise subtotal reaches the option's free-shipping threshold, and the customer is told the expected delivery time in days when you configured one. See [How the agent uses shipping](/settings/shipping-and-payment#how-the-agent-uses-shipping-at-checkout). **4. Summary and confirmation** The agent sends an order summary: up to eight products, **Delivery** (the delivery option and its fee, or "Free"), **Cash on delivery fee** when one applies, **Total**, **Name**, **Phone**, **Address**, **Payment method**, and any **Discount code** or **Notes**, with **Confirm order**, **Edit** and **Cancel** buttons. Shopify summaries have no delivery line, because Shopify's checkout adds delivery. In Website chat and in the agent's test chat the same three buttons appear in the chat. The order is created only when the customer taps **Confirm order**; typing "yes" does not confirm it. If details change, a product becomes unavailable or changes price, or the delivery option is switched off, the customer gets a fresh summary to confirm. **5. Order created** On confirmation the order moves to **Awaiting payment** and the customer receives "Your order has been created." with the order number, total and, for **Payment link**, the link. With Zid or Salla, the order number and total are the ones your store gives the order. Bank-transfer customers get your bank details. If Zid turns the order down, the customer is told the store couldn't take it (or that an item is out of stock) and is offered a change or your team; the refused order is not sent again. > [!NOTE] > > Orders placed in the test chat are real orders. They appear under **Orders** and, with a connected store, are created there too. See [Test and publish](/agents/test-and-publish). Shopify stores that require an email at checkout: if **Allow phone-only checkout** is off in **Shopify settings** on the **Integrations** page, the agent asks the customer for an email address before creating the order. See [Shopify](/integrations/shopify). ## Where the order appears in your store * **Zid** and **Salla**: the order is created in your store when the customer confirms, and its store identifier is shown as the **Store order** number. The **Total** in Popcorn and in the confirmation message is the total your store reports, and **Shipping** is the delivery fee your store charged; on Zid, so is the **Cash on delivery fee**. On Zid, automatic (store-wide) discounts are applied when the order is created, on top of any discount code, so the total can be lower than the summary the customer confirmed and is 0 for a fully discounted order. * **Shopify**: Popcorn creates a checkout with the items and the customer's details (including any custom checkout attributes). The Shopify order exists once the customer completes that checkout. Shopify shipping rates are handled on the checkout page; in Popcorn you only maintain delivery coverage. * **No connected store**: the order exists in Popcorn only. ## Order tracking With **Track orders** switched on, the agent answers status questions using your connected store. The customer's WhatsApp number is passed to the agent automatically, so a customer who asks without an order number gets their five most recent orders. If they give an order number, the store's record is checked against the customer's phone number and a mismatch is refused; on Shopify the email address on the order also works as verification. The order number can be your store's or Popcorn's own (the "P" number in **Orders**). On Zid and Salla, Popcorn finds the store order behind a "P" number, or looks the customer's orders up by phone when there is none yet; on Shopify, where the order only exists once the customer completes checkout, a "P" number always means a lookup by phone. Without an order number or a phone number, the agent asks for one. Replies include the order status and the shipping details your store exposes, such as carrier, estimated delivery, tracking number and tracking link. On Zid, replies also include the delivery status and the order's history, whether the customer gave an order number or only a phone number. Tracking is not available for orders that exist only in Popcorn. ## Troubleshooting * **"No shipping option found for this city"** (Shopify or Zid): you have delivery coverage configured, but none of your active shipping options includes the customer's city. Add the city under **Settings → Shipping** or ask the customer for a covered city. * **The agent asks for an email before ordering**: your Shopify store requires one. Turn on **Allow phone-only checkout** in **Shopify settings** on the **Integrations** page if your store accepts phone-only checkout. * **Payment link not offered**: no store is connected, or **Payment link** is turned off under **Settings → Payment**. * **Bank transfer not offered**: no bank details are saved under **Settings → Payment**. * **The customer was refused cash on delivery** (Zid): the Zid delivery zone for their city doesn't take cash on delivery. The agent offers delivery options that do, or another payment method. See [Shipping and payment](/settings/shipping-and-payment#how-the-agent-uses-shipping-at-checkout). * **Order stuck in Awaiting payment**: the customer has not paid, or the payment link expired (24 hours on Zid). Click **View conversation** to follow up with the customer. * **Customer cannot track an order**: tracking needs a connected store and either the order number (verified against the customer's phone number) or the phone number the order was placed with. * Repeated order or address failures also appear in [Store health](/integrations/commerce-health). ## Related * [Product catalog](/products/catalog) * [Customers](/customers/overview) for each customer's order history. * [Work a conversation](/inbox/working-conversations) for sending products to a customer yourself. # Product catalog Source: https://docs.trypopcorn.ai/products/catalog Manage the products your agent can recommend and sell: synced or manual, variants, custom options, and Boost, Normal or Hide. The **Products** page is the catalog your agent searches when a customer asks for something. Products arrive automatically from your connected Shopify, Salla or Zid store, or you add them yourself. Use this page to check what the agent sees, fix a product's details, decide which products the agent should push or never mention, and collect extra details (a gift message, an engraving) at checkout. ## Before you start * To recommend products, an agent needs **Recommend products** switched on, on its **Actions** tab under **Selling and orders**. See [Agent capabilities](/agents/capabilities#selling-and-orders). * Prices show in the **Default currency** set under **Settings → General → Products**. Two switches on the same card change what this catalog shows: **Product quantities** adds a **Quantity** column and field, and **Custom product options** adds the **Custom options** section to each product. **Show currency to the agent** tells the agent which currency your prices are in. See [Workspace settings](/settings/workspace). * A connected store is required for automatic sync, **Resync products**, and creating orders in your store. Without one, you can still add products by hand or from a CSV file. ## The catalog list **Products** opens on the **Catalog** tab, beside **Recommendation rules**. **Import** and **Add product** are at the top. **Search products** matches the product ID, name, description and link, including variant names and descriptions. | Column | What it shows | | - | - | | **Product** | Picture, name and product ID. Click to open the product. | | **Price** | What checkout charges: the sale price when one is set, otherwise the price. Only when the sale price is lower than the price does the price appear struck through beside it. | | **Status** | **Active** or **Inactive**. | | **Quantity** | Stock on hand. Only shown when **Product quantities** is on. | | **Times recommended** | How many times the agent has recommended this product in conversations. | | **In recommendations** | The recommendation weight: **Boosted**, **Normal** or **Hidden**. Click it to change it; the change saves immediately. | | **Variants** | The number of variants. Click it to show them under the parent. | Narrow windows show fewer columns. The **⋯** menu (**More actions**) on a row offers **Edit**, **Open product page** (your store's page for it) and **Delete**. To delete several products, tick their boxes. The bar shows "N selected" with **Delete products**. The confirmation says it "permanently deletes" the selected products and their variants and that you can't undo it. When there are no products yet, the page offers **Connect your store** and **Add product**. A deleted product, with its variants, disappears from this list and from product counts, is no longer found when the agent searches your products, and is removed from your Meta catalog if one is connected. If the deletion cannot be completed you see "Couldn't delete the products. Try again." (or "Couldn't delete the product. Try again."); delete it again, and Popcorn finishes what the first attempt left undone. Deleting cannot be undone from Popcorn, but it does not delete the product in your store: if the store sends it again, through a product update or **Resync products**, it returns to the catalog. ## Boost, Normal or Hide a product Each product has one recommendation weight, shown in the **In recommendations** column and in **Recommendation behavior** on the product page. | Weight | Effect on the agent | | - | - | | **Boost** | The agent will prefer this product over similar ones. Boosted products that match the customer's request move to the top of the results. | | **Normal** | The agent recommends this based on relevance only. | | **Hide** | The agent will never recommend this product. It stays visible on your storefront. Hidden products are removed from every product search the agent runs. | On the product page you can also fill in **Tell the agent why (optional)**, up to 500 characters, for example "Our bestselling gift for anniversaries." The agent sees this note next to the product when it comes up in a search and can use it in its reply. A variant without a note of its own uses its parent product's note. Popcorn's nightly Knowledge check can also suggest a line for this note when your team keeps telling customers the same fact about one product (shown as **Note on** and the product's name). If you add it, the line goes into this note, on the product and on its variants that have no note of their own, and you can edit it here like any note. Adding it needs permission to edit products. It never writes a price or stock level. See [Review what your agent learned](/knowledge/knowledge-check). Weights are set per product. If you want the agent to react to a kind of request rather than a single product, use [recommendation rules](/products/recommendation-rules). ## Edit a product Click a product to open it. The header shows its name, an **Active** or **Inactive** badge, and when it was added and how many times it was recommended. **Open product page** goes to your store's page for it, and the **⋯** menu has **Delete product**, which asks you to confirm and cannot be undone. When you change anything, a bar appears reading "Unsaved changes" with **Discard** and **Save changes**. Leaving the page with unsaved changes asks you to confirm. **1. Details** Upload up to 10 images (JPEG, PNG, GIF or WebP); a counter such as "3/10 images" shows how many slots are used. Then **Name**, **Product ID**, **Description** and **Product link**. **2. Pricing** **Price** is required. **Sale price** is optional and must be lower than the price. **Discount %** is a whole number from 0 to 100 and fills in the sale price for you; typing a sale price clears the discount. **Quantity**, your stock, appears when **Product quantities** is on and must be a whole number. Amounts accept the way you write them, such as 1,299.50 or 49,99. **3. Variants** Click **Add variant**. In the dialog, **Choose existing** turns another catalog product into a variant of this one, and **Create new** makes a new one. Open a variant's menu for **Edit variant** and **Delete variant**; a variant you added but have not saved shows **Remove** instead. Added and removed variants are applied when you click **Save changes**, and a removed variant is also removed from your Meta catalog. If a variant cannot be removed, the save fails with "Couldn't save the product. Try again."; variants that were already removed stay removed, so you can simply save again. **4. Custom options** Shown only when **Custom product options** is on. See [Custom options](#custom-options) below. In the side column, the **Active** switch ("The agent only offers active products.") controls whether the agent can offer the product, and **Recommendation behavior** holds the weight and the note. A product whose stock is 0 is marked inactive when it syncs from your store, is saved or is imported from a CSV file, provided **Product quantities** is on. ## Products the agent can't sell An inactive product can still come up in the agent's product searches, marked as not for sale, so the agent can answer a customer who asks about it. It never recommends it, sends it as a product card or adds it to an order. The same applies to a product with 0 stock while **Product quantities** is on and at least one of your active products has stock, except Shopify products, whose stock Popcorn doesn't use for this. For a product with variants, the agent also sees which of its options (colours, sizes) are for sale now and which aren't, named from the variants' names. So it doesn't offer a colour your description or tags still mention after it sold out. Variants set to **Hide**, or left out by a **Show only these products** rule, are left out of that list. ## Custom options Custom options collect extra details from customers when they order, such as a gift message. Click **Add custom option** and fill in: * **Option name**, for example "Gift message". * **Type**: **Text**, **Number**, **Date**, **Time**, **Dropdown**, **Multiple choice**, **Image upload** or **File upload**. * **Choices**, for **Dropdown** (the customer picks one) and **Multiple choice** (they can pick more than one). Click **Add choice** for each. * **Extra price**, for every type except the two uploads: a whole number added to the order total when the customer uses the option. * **Required**: when on, the customer must fill it in before they order. The agent asks for required options before it builds the order. The values the customer gave appear on the order under the product; see [Orders](/orders/overview). ## Add products yourself Use this when you have no connected store or want to sell something that is not in it. **1. Add one product** Click **Add product**. The dialog says "The agent uses these details to recommend and sell this product." Add images, then **Name**, **ID**, **Price**, **Description** and **Link**, which are required, and **Sale price**, **Discount %** and **Quantity** as needed. The link must be a full web address, starting with `https://`. To make the new product a variant of an existing one, search for the parent under **Variant of (optional)**. **Active** is on by default. Click **Add product**; you see "Product added". **2. Import a CSV** Click **Import**. The dialog reads "Import products from a CSV file" and says each row needs a product ID, name, link, price and at least one image URL. Upload the file, match your columns to the product fields, fix any rows with errors, then import. Imported products are synced to your connected catalogs and indexed for the agent. Imports of more than 10 products continue in the background, so you can close the tab; you see "Products imported" when it finishes. CSV fields and their limits: | Field | Rule | | - | - | | **ID** | Required, unique within the file, 1–64 characters | | **Product name** | Required, up to 120 characters | | **Product link** | Required, up to 200 characters | | **Description** | Up to 500 characters | | **Price** | Required, a number such as 49.99 | | **Quantity** | A whole number. If **Product quantities** is on and the value is 0, the product is imported as inactive. | | **Discount %** | 0–100 | | **Sale price** | A number. If empty and a discount is given, Popcorn calculates it. | | **Image 1** | Required image URL, up to 400 characters | | **Image 2**, **Image 3**, **Image 4** | Optional image URLs | ## Resync products from your store If the catalog looks stale after changes in Shopify, Salla or Zid, go to **Integrations**. The connected store's card shows the product count and when it was last synced ("never synced" or "last resync failed" if that is the case). Click **Resync products**: Popcorn pulls your latest products from the store and then pushes them on to your Meta catalog, so you do not have to touch either platform. You see **Resync started** with "Pulling your latest products from your store. This usually takes a few minutes." and the card shows **Resyncing products…** until it finishes. * **A resync is already running**: wait for the current one to finish. * **Products were just resynced. You can resync again in N min.**: a resync can be started once every 15 minutes. * **Connect your store before resyncing products**: there is no connected store. * The button is only shown to team members whose role can manage products. See [Team and roles](/settings/team-and-roles). A Zid product published in Zid shows as **Inactive** here when Zid lists it only at locations that don't sell on your website, such as Zid Cashier branches, whatever **Product quantities** is set to; its quantity counts only website stock. See [Zid](/integrations/zid#what-syncs). For what each platform syncs and how to fix sync problems, see [Integrations](/integrations/overview) and [Store health](/integrations/commerce-health). ## How customers search by image When a customer sends a product photo on WhatsApp, the agent searches the catalog by image as well as by text. If the match is uncertain, it shows the closest products and asks the customer to confirm or share the product link; if nothing matches, it asks for the product link or exact name. If the image cannot be analysed at all, the agent searches using any product name or model number the customer typed and says the results are based on that description, or asks for a clearer photo, a product link or the exact product name. ## Related * [Recommendation rules](/products/recommendation-rules) for request-based merchandising. * [Products in WhatsApp](/channels/whatsapp-catalog) for product cards and carts in WhatsApp. * [Orders](/orders/overview) for what happens after the customer decides to buy. * [Workspace settings](/settings/workspace) for currency, quantity and custom-option switches. # Recommendation rules Source: https://docs.trypopcorn.ai/products/recommendation-rules Tell your agent which products to show only, or show first, when a customer asks about a topic, season or occasion. A recommendation rule is one merchandising intent: when a customer asks about something you describe in plain words, the agent recommends only a chosen set of products, or puts them first. Use rules for seasonal pushes ("anyone asking about Valentine's gifts"), bundles, or clearing stock, without editing every product. Rules are set once for the workspace and apply to every agent that has **Recommend products** switched on. See [Agent capabilities](/agents/capabilities#selling-and-orders). ## Before you start * Your catalog must contain the products you want to pick. See [Product catalog](/products/catalog). * A rule affects what the agent's product search returns. It does not change your storefront, and it does not affect products a teammate sends manually from the Inbox. ## Create a rule **1. Open the rules tab** Go to **Products** and open the **Recommendation rules** tab, or click **Manage rules** next to **Recommend products** on an agent's **Actions** tab. Click **Add rule**. **2. Name it** In **New rule**, enter a **Name**, for example "Valentine 2026". Names are kept to 120 characters. **3. Describe when it applies** Under **When the customer asks about**, describe the customer signal in your own words, for example "When the customer is asking about Valentine, a gift for their wife or girlfriend, or romance." Descriptions are kept to 500 characters. The agent reads this description during each conversation to decide whether the rule applies, so write it the way a customer would phrase the request. **4. Choose what the agent should do** Under **What the agent should do**, pick one: * **Show only these products**: when this rule matches, the agent recommends from this list only. * **Show these products first**: when this rule matches, the agent floats these products to the top of the results. **5. Pick the products** Under **Products**, use **Search products** and click the products to select them. Selected products stay at the top of the list, and the count under the list reads, for example, "3 products selected". A rule holds up to 500 products. If your products carry tags, **Add products by tag** opens a panel where you search for tags, pick one or more and click **Add** to select every product with those tags in one go. You see "Added 12 products to the list." You can still remove individual products afterwards. The rule keeps a list of products, not the tag: products that get the tag later are not added. **6. Set an active window (optional)** Under **Active window (optional)**, fill in **Starts** and **Ends** to limit the rule to a date range. Dates are whole days in your local time: the rule starts at the beginning of the start day and stops at the end of the end day. Leave both empty for an always-active rule, or fill in only one for a rule that starts, or ends, on a day. **7. Save** Click **Create rule**. You see "Rule created". The rule is on immediately and applies from the next conversation. ## Manage rules Each rule shows its name, an **Only these** or **These first** badge, the description, the number of products, and either the dates ("Feb 1, 2026 to Feb 14, 2026", "From …", "Until …") or **Always active**. A paused rule shows a **Paused** badge. Open the **⋯** menu (**More actions**) on a rule: * **Edit rule** opens it again; save with **Save changes**. You see "Rule saved". * **Pause rule** turns it off without deleting it ("Rule paused"), and **Resume rule** turns it back on ("Rule resumed"). Pausing works even if some of the rule's products have since been deleted. * **Delete rule** asks you to confirm with **Delete rule**: the agent stops using it from the next conversation onward, and the products themselves are not affected. When some products are boosted or hidden one by one, a strip above the rules reads, for example, "4 products boosted · 2 products hidden", with **Manage in catalog** to open the **Catalog** tab. ## Examples | Goal | When the customer asks about | Action | Products and window | | - | - | - | - | | Push the Valentine collection in February | Valentine, a gift for their wife or girlfriend, or romance | **Show these products first** | The Valentine products, **Starts** 1 Feb, **Ends** 14 Feb | | Answer corporate-gifting enquiries with a curated set only | Corporate gifts, bulk orders for employees or clients | **Show only these products** | The corporate bundles, always active | | Clear last season's stock | A discount, a deal, or the cheapest option | **Show these products first** | Every product tagged "clearance", added with **Add products by tag** | ## Rules or per-product weights? | Use | When you want | | - | - | | **Boost** on a product | A standing preference for that product in every conversation where it is relevant | | **Hide** on a product | The agent to never mention that product, while it stays on your storefront | | **Show these products first** | A set of products to lead the results only for a kind of request, optionally for a period | | **Show only these products** | The agent to recommend nothing outside a set for a kind of request | ## How rules, weights and search combine 1. The customer asks for something and the agent searches the catalog. Products set to **Hide** never appear, whatever the rules say. 2. The agent checks your enabled rules that are inside their active window and decides which ones apply to the current conversation, using your **When the customer asks about** descriptions. 3. If any applicable rule is **Show only these products**, results are limited to the products of those rules. If none of the search results are in the list, the agent gets no products for that search rather than falling back to the whole catalog. 4. Products from applicable **Show these products first** rules move to the top, ahead of products that are merely boosted. Otherwise the order stays by relevance, with boosted products first. 5. A rule that names a product with variants covers all of that product's variants. When a **Show only these products** rule applies, the options the agent sees for a product (which colours or sizes are for sale) include only the variants the rule allows. Rules and weights apply to the agent's product search only. Sending a product card from the Inbox, or the catalog the customer browses in WhatsApp, is not filtered by rules. ## Troubleshooting * **The agent ignores a rule.** Check that the rule is not paused or outside its dates, that the agent has **Recommend products** on, and that the description matches how customers actually phrase the request. Test it in the agent's test chat before relying on it; see [Test and publish](/agents/test-and-publish). * **An "only" rule leaves the agent with nothing to show.** The customer's request matched the rule, but none of the products in the list matched what they asked for. Widen the product list or switch the rule to **Show these products first**. * **A product you deleted is missing from a rule.** Opening the rule drops products that no longer exist from its list. Save the rule to keep the change. * **Couldn't save the rule.** The rule needs a name ("Give this rule a name."), a description ("Describe when this rule should apply.") and at least one product ("Pick at least one product."). The **Starts** date must not be after the **Ends** date. ## Related * [Product catalog](/products/catalog) for per-product **Boost**, **Normal** and **Hide**. * [Popcorn's rules and Voice](/agents/popcorns-rules) for how the agent sounds and behaves alongside rules. # Quickstart Source: https://docs.trypopcorn.ai/quickstart Create your account, then set up your agent in three steps: your business, what it knows, and WhatsApp. Then watch its first conversation. This guide takes you from creating an account to your agent answering its first customer on WhatsApp. After you sign up, Popcorn opens **Set up your agent**, a three-step setup: **Your business**, **Your agent** and **WhatsApp**. Popcorn builds the agent from your website, or from a few lines you write, so most of your work is checking what it knows and connecting a number. ## Before you start * **A website address for your business**, such as `yourbusiness.com`. Your agent reads your main pages: products or services, prices, delivery and FAQ. If you only sell on Instagram or WhatsApp, you can describe your business in a few lines instead. * **Admin access to your store**, if you sell on Salla, Zid or Shopify, so you can approve Popcorn AI in your store dashboard. * **For the last step:** a mobile number that is not on WhatsApp yet and a Facebook account that can manage your business. The step takes about 5 minutes. See [Connect a WhatsApp number](/channels/whatsapp). ## Create your account On **Get started with Popcorn AI**, fill in **Full name**, **Email**, **Phone** and **Password** (9 or more characters), then click **Sign up**. Or click **Continue with Google**. If your account has no phone number yet, Popcorn asks for it on **Add your phone number**; click **Continue** and setup opens. If a teammate invited you by email, the sign-up page says "You've been invited to join *workspace*" and you join their workspace and land on Home. Setup is for the person who creates a workspace. See [Team and roles](/settings/team-and-roles). The button at the top right of setup switches between English and Arabic. Spanish is under **Language** in the workspace menu once you are in the app. ## Step 1: Your business **Tell your agent about your business** has three ways in. Pick the one that fits. **Website** **1. Enter your website address** Type your address under **Website** (`https://` is already there, so type `yourbusiness.com`) and click **Read website**. Popcorn shows "Reading your website…", then "Setting up your workspace…" and "Reading *N* pages from your website". **2. Connect your store if it is one** If the site runs on Salla, Zid or Shopify, Popcorn stops with "This is a *platform* store" and "Connect it so your agent can check stock and take orders." Click **Connect** with your platform's name, such as **Connect Salla**, to open your store's window. Approve Popcorn AI there and the page carries on by itself. Click **Continue without connecting** to go on with the website alone; your agent then answers from its pages and cannot check stock or take orders until you connect the store under **Integrations**. Popcorn picks the pages itself: the ones it recommends, up to 8. You can change what the agent knows later under **Knowledge**. **Store first** Under **Online store**, click **Salla**, **Zid** or **Shopify**. Your agent will see live prices and stock, take orders and send payment links. Approve Popcorn AI in the window that opens ("Finish connecting in the *platform* window. This page continues when you're done."). Popcorn then reads the website you typed, or your store's own address. If it cannot find an address, it says "Now add your website so your agent can read your delivery and returns pages." Type the address and click **Read website**. **No website** Under **Only on Instagram or WhatsApp**, click **Describe your business** and fill in: * **Business name**. * "What do you offer, and how do customers buy or book?" Prices, delivery or bookings, and how people pay help your agent most. If you take bank transfers, include your IBAN. Click **Create agent**. If you paste an Instagram, Facebook, WhatsApp, TikTok, Snapchat, X or Linktree address into **Website address**, Popcorn says "Your agent can't read *network* pages, so describe your business below." Your description becomes your agent's starting knowledge. If you sell on Salla, Zid or Shopify after all, **Connect your store instead** takes you back to the store buttons. When the workspace and agent are ready, setup moves to step 2 on its own. > [!WARNING] > > Only a workspace admin can finish setup. If you see "Only a workspace admin can finish setup. Ask an admin to sign in.", ask an admin of the workspace to sign in. ## Step 2: Your agent **Check what your agent knows** has what the agent learned on the left and **Try it as a customer** on the right. On a narrow screen, a **View** switch toggles between **What it knows** and **Try it**. Test chats are free and never reach WhatsApp. **With no store**, the page says "It read *N* pages on *host*. Try it as a customer, then put it on WhatsApp." Ask about a policy from your site, then about something it does not cover, to see how the agent behaves when it does not know. **With a store**, Popcorn gives your agent the store: it can share products, take orders and track them, and the change is published for you. For about a minute the page reads "Your agent is reading your *platform* store" and you can already chat with the agent. Then **Your store** shows what the agent has: | Row | What it tells you | If something is missing | | - | - | - | | **Products** | How many products it read, "with prices, sizes and stock" | **Try again** if the store did not send them. **Check again** after you add products in the store | | **VAT** (Zid only) | Whether your prices include VAT and whether your agent adds it | **Choose** or **Edit** opens the Zid VAT settings | | **Orders** | That it takes orders in the chat, and how: a payment link, cash on delivery or bank details | **Open agent** if the order tool is not live or was left off | | **Delivery** | The options it quotes, with fee and time | **Add fee and time** asks for **Usual fee** and optionally **Free delivery over** | | **Payment** | The ways customers can pay | **Add** opens **How customers pay**: **Payment link**, **Cash on delivery** and **Bank transfer**. **Add IBAN** saves the details your agent sends for a bank transfer | Fix what is wrong, ask your agent a few customer questions, then click **Continue to WhatsApp**. You can leave rows unfinished and return to them later: delivery and payment live under [Shipping and payment](/settings/shipping-and-payment). ## Step 3: WhatsApp **Put your agent on WhatsApp** says what to have ready and what changes. Read the two panels, then click **Connect WhatsApp**: Meta's window opens in the same click. * **Before you connect** ("About 5 minutes, in a Facebook window."): a mobile number that is not on WhatsApp yet, like a new SIM, which gets one code by text or call; and a Facebook account, where you pick your business and the name customers see. If someone else manages your Facebook, click **Ask a teammate**. * **After you connect:** WhatsApp's fee is free for the first 1,000 messages a month that your agent and your team send to answer customers, then about SAR 0.04 each, charged to a card in your Meta account. You answer chats that need a person from the Popcorn AI inbox. Customers who message your current number do not reach your agent, so you give them its new link. If Meta needs to confirm the number, **Confirm your number** asks for the 6-digit code Meta sends to it: click **Text me the code** (or **Call me instead**), type the code and click **Confirm and connect**. After connecting, Popcorn checks that the number can send and receive ("Checking it can send and receive"). If something still needs you, setup stays on this step with **Connected, one thing left**, what to fix, and **Check again**. Click **Back** to return to step 2, or **Finish later** to leave setup for Home. Home then shows your agent's setup with **Check what I know** and **Connect WhatsApp**, which reopen steps 2 and 3. See [Home dashboard](/analytics/dashboard). > [!NOTE] > > Your role needs permission to connect integrations to use **Connect WhatsApp**. Without it the button is off, and an admin has to do this step. ### Already on the WhatsApp Business app? Click **See what keeping the app changes** for **Keep using the WhatsApp Business app**. Your number and chats stay in the app and your agent answers alongside you. The screen lists **What changes**: your agent answers everyone who messages the number, you keep WhatsApp Business open at least weekly, broadcast lists stop, linked devices sign out, and groups stay in the app. It also lists what to do first: update the app, turn off greeting and away messages, and keep your current number. Click **Use a number for your agent** to go back. The full guide is [Use Popcorn with the WhatsApp Business app](/channels/whatsapp-coexistence). ### When it is live Setup ends on **Your agent is on WhatsApp** ("It answers new messages to *your number*."): * **Your agent's WhatsApp link** with **Copy link**. Message it from your own phone to see your agent answer, then put it in your Instagram bio, your website and your receipts. * **When a chat needs you**: your agent tells the customer your team will reply, marks the chat in your inbox and emails you. **Invite your team** opens **Team members**. * **WhatsApp's fee**: without a card in your Meta account, WhatsApp stops delivering messages after the first 1,000 each month. **Add card in Meta** opens Meta's billing page. Click **Open inbox** or **Go to Home**. ## What setup created | Item | What you get | Where to manage it | | - | - | - | | Workspace | Named after your business, with a currency and time zone detected from your store, country and browser | **Settings → General** | | Knowledge | A folder named **Business Knowledge Base** with the pages Popcorn read, or your description, connected to the agent | **Knowledge** | | AI agent | "*Business* Assistant", your default agent, already published. It runs on **Popcorn's rules**: Popcorn writes and tests how it sells, answers and hands over, and you keep its Knowledge up to date | **Agent** | | Store | Products, orders and customers syncing from your store, and the order tool on your agent, if you connected one | **Integrations** | | WhatsApp | Your agent's number, once you finish step 3 | **Integrations → WhatsApp** | | Credits | 100 free credits, which expire one month after the workspace is created | **Plan and billing** | The defaults on the agent are in [Create an agent](/agents/create-an-agent#the-agent-onboarding-created). ## Watch the first conversation Open **Inbox**. Conversations your agent is replying to are under **Agent**. When it hands one over, because the customer asked for a person or the chat is one it leaves to your team, the conversation shows **Needs you** and your team takes it. Tests you ran during setup are under **Test conversations**. See [Inbox overview](/inbox/overview). ## Where credits come in * Each reply your agent sends uses 1 credit, on WhatsApp and Website chat alike. Test chats from setup and **Home** are free. * Campaigns use credits too: 1 credit per 10 campaign messages and 1 credit per 5 automated campaign messages. * When credits run out the agent stops replying, every new customer message goes to your team, and the agent card in the sidebar reads **Stopped, out of credits**. Open **Plan and billing** in the workspace menu to buy credits or change plan. Details: [Plans and credits](/billing/plans-and-credits). ## If setup stops | Message | What to do | | - | - | | We couldn't open that website. Check the address and try again. | Check the address for typos and try again. | | We couldn't read your website. Try again in a moment. | Try again. If it keeps failing, describe your business instead. | | We couldn't find any pages to read on that website. Check the address and try again. | Check the address, or click **Describe your business**. | | We couldn't set up your agent. Try again. | Try again. | | This is taking longer than expected. Try again, or contact support. | Try again, then contact support. | | Your session expired. Sign in again to continue. | Sign in again, then continue. | | Your browser blocked the *platform* window. Allow pop-ups for this site, then try again. | Allow pop-ups for Popcorn and click the store button again. | | The *platform* window closed before your store connected. Try again. | Click the store button again and finish in the window. | | Your agent is set up, but we couldn't confirm it yet. Try again. | Click the button again. Your workspace already exists. | ## What happens next * **Add knowledge.** Create folders and articles under **Knowledge**. See [Writing articles](/knowledge/writing-articles). * **Review the agent.** Open **Agent**, then your agent, to set its **Voice** and switches. See [Agents overview](/agents/overview) and [Test and publish](/agents/test-and-publish). * **Invite your team.** Go to **Settings → Team members**. Roles decide who can publish agents, send campaigns, or only read. See [Team and roles](/settings/team-and-roles). * **Show products in WhatsApp.** Connect the Meta catalog so the agent can send product cards. See [Products in WhatsApp](/channels/whatsapp-catalog). * **Add the website chat.** See [Website Chat](/channels/website-chat). * **Send your first campaign.** Create a template, wait for Meta's approval, then send it to an audience. See [Campaigns overview](/campaigns/overview). > **[How Popcorn works](/how-popcorn-works)** > > The concepts behind what you just set up. > **[Agent troubleshooting](/agents/troubleshooting)** > > Agent not replying, wrong answers, or changes not showing. # Settings overview Source: https://docs.trypopcorn.ai/settings/overview Find your way around Settings: personal, workspace, automation, commerce and developer pages, and who can see each one. **Settings** holds everything that is not day-to-day inbox or campaign work: your own profile and notifications, workspace-wide options, team access, quick replies and tags, shipping and payment rules for the AI agent's checkout, and developer access. Open the workspace menu at the top of the sidebar and choose **Settings**; it opens on **Profile**. The same menu holds **Team members** and **Plan and billing** when your role allows them, plus **Language** and **Sign out**, and it lists your workspaces if you belong to more than one. ## Find a setting The left column groups the pages. The search box at the top (**Search settings**) filters the list by page name and by common words such as "currency", "invite", "password" or "webhooks", in the language the app is in. If nothing matches you see "No settings match your search". On a phone the list and the page swap places. Pages you edit in place (**Profile**, **Notifications**, **Communication**, **General**, **Payment** and the webhook section of **API keys and webhooks**) show a bar reading **Unsaved changes** with **Save changes** and **Discard** as soon as you edit something. Nothing is applied until you click **Save changes**. **Team members**, **Shipping**, **Macros**, **Conversation tags** and the key list save each item from its own dialog instead. ## The pages ### Personal These pages are about you, and every role can open them. | Page | What it does | | - | - | | **Profile** | Your name, email and role, the workspace's business name and time zone, password reset, privacy choices, and leaving a workspace. See [Profile and notifications](/settings/profile-and-notifications). | | **Notifications** | Which inbox events alert you, and whether they arrive as a pop-up, a browser notification or with a sound. See [Profile and notifications](/settings/profile-and-notifications#notifications). | | **Communication** | Whether Popcorn sends you product updates in-app, by email or on WhatsApp. See [Profile and notifications](/settings/profile-and-notifications#communication). | ### Workspace | Page | What it does | | - | - | | **General** | Inbox media handling, automatic follow-ups, working hours, product settings (default currency, quantities, custom options), VAT for Zid prices and the Knowledge workspace switch. See [Workspace settings](/settings/workspace). | | **Team members** | Invite colleagues, change their role, remove them, and manage pending invites. See [Team and roles](/settings/team-and-roles). | | **Roles and permissions** | The five predefined roles and the permission matrix each one grants. See [Team and roles](/settings/team-and-roles#roles-and-permissions). | ### Automation | Page | What it does | | - | - | | **AI assistants** | Connect ChatGPT, Claude or Codex to your workspace. See [AI assistants](/ai-assistants/overview). | | **Macros** | Reusable replies your team inserts in the Inbox with a `/shortcut`. See [Tags and macros](/inbox/tags-and-macros). | | **Conversation tags** | Tags with priorities that the AI agent applies on handover and your team uses to filter the Inbox. See [Tags and macros](/inbox/tags-and-macros). | ### Commerce | Page | What it does | | - | - | | **Shipping** | Shipping options (fee, delivery time, free-shipping threshold) and the countries and cities you deliver to; with Shopify, the delivery coverage. See [Shipping and payment](/settings/shipping-and-payment). | | **Payment** | Which payment methods the AI agent may offer at checkout: cash on delivery, bank transfer, payment link. See [Shipping and payment](/settings/shipping-and-payment#payment-methods). | ### Developer | Page | What it does | | - | - | | **API keys and webhooks** | Create API keys and configure the message-status webhook. See the [API reference](/api-reference/introduction). | Plans, credits and invoices are not under Settings. Choose **Plan and billing** in the workspace menu, or click the credits shown under your agent in the sidebar; see [Plans and credits](/billing/plans-and-credits). ## Who sees which page A page only appears in the list if your role can view the area it belongs to. **Settings** itself, and the workspace menu, are there for everyone. With the predefined roles: | Page | Owner, Admin | Manager | Agent | Viewer | | - | - | - | - | - | | **Profile**, **Notifications**, **Communication** | Yes | Yes | Yes | Yes | | **General** | Yes | Yes (view only; saving needs settings edit access) | No | No | | **Team members**, **Roles and permissions** | Yes | Yes (view only) | Yes (view only) | No | | **AI assistants**, **API keys and webhooks** | Yes | Yes (view only) | No | No | | **Macros**, **Conversation tags** | Yes | Yes | Yes | Yes (view only) | | **Shipping**, **Payment** | Yes | Yes | Yes (view only) | Yes (view only) | Seeing a page does not always mean you can change it: saving on **General** requires settings edit access, changing shipping or payment requires orders edit access, and inviting or removing teammates requires the matching team-management actions. The full matrix is in [Team and roles](/settings/team-and-roles#roles-and-permissions). ## Common tasks | I want to... | Go to | | - | - | | Invite a colleague | **Settings → Team members → Invite team members** ([guide](/settings/team-and-roles#invite-teammates)) | | Change someone's role | **Settings → Team members**, the **Role** column ([guide](/settings/team-and-roles#manage-members)) | | Fix the time zone used by reports and campaigns | **Settings → Profile → Time zone** ([guide](/settings/profile-and-notifications#profile)) | | Reset my password | **Settings → Profile → Reset password** ([guide](/settings/profile-and-notifications#profile)) | | Stop or start browser notifications | **Settings → Notifications** ([guide](/settings/profile-and-notifications#notifications)) | | Hold campaigns outside business hours | **Settings → General → Working hours** ([guide](/settings/workspace#working-hours)) | | Change the currency the agent quotes | **Settings → General → Products → Default currency** ([guide](/settings/workspace#products)) | | Set VAT for Zid prices | **Settings → General → VAT**, which opens the Zid settings when a Zid store is connected ([guide](/settings/workspace#vat)) | | Define where you deliver and what it costs | **Settings → Shipping** ([guide](/settings/shipping-and-payment#shipping-options)) | | Let customers pay on delivery, by bank transfer or by link | **Settings → Payment** ([guide](/settings/shipping-and-payment#payment-methods)) | | Connect ChatGPT, Claude or Codex | **Settings → AI assistants** ([guide](/ai-assistants/overview)) | | Create a quick reply or a conversation tag | **Settings → Macros** or **Settings → Conversation tags** ([guide](/inbox/tags-and-macros)) | | Create an API key or set a webhook | **Settings → API keys and webhooks** ([guide](/api-reference/introduction)) | | Add another store or brand, or leave a workspace | The workspace menu's **Create workspace**, or **Settings → Profile → Leave workspace** ([guide](/settings/team-and-roles#several-workspaces)) | ## Language The app itself is available in English, Arabic and Spanish. The switcher is **Language** in the workspace menu, not in Settings; see [Profile and notifications](/settings/profile-and-notifications#language). # Profile, notifications and communication Source: https://docs.trypopcorn.ai/settings/profile-and-notifications Update your name, business name and time zone, choose which inbox events alert you and how, set product-update preferences, and leave a workspace. The three pages under **Settings → Personal** are about you: **Profile** ("Manage your name, business name and time zone."), **Notifications** ("Choose how and when you want to be notified.") and **Communication** ("Choose how Popcorn AI keeps you posted about new features."). Every role can open all three, and each teammate sets their own notifications and communication choices. Two fields on **Profile**, the business name and the time zone, belong to the whole workspace. ## Profile Open **Settings → Profile**. The top card shows your avatar, name and email, with **Reset password**. Click it to be emailed a link: you see **Reset link sent** ("Check *email* for a link to set a new password.") or **Couldn't send the reset link**. The button is hidden while Popcorn staff are viewing your account. | Panel | Field | Notes | | - | - | - | | **Personal information** ("Your name and how you sign in.") | **Name** | Required: "Enter your name." Teammates see it in the Inbox and on invitations you send | | | **Email address** | Read-only. It is how you sign in | | | **Role** | Read-only: **Owner**, **Admin**, **Manager**, **Agent**, **Viewer**. It is changed on **Settings → Team members**; see [Team and roles](/settings/team-and-roles) | | **Workspace** ("Applies to everyone in your workspace.") | **Business name** | Up to 200 characters, and not empty: "Enter a business name before saving." | | | **Time zone** | A list of zones such as "(GMT+4:00) Abu Dhabi, Muscat". New workspaces start on GMT | Click **Save changes** in the **Unsaved changes** bar, or **Discard**. You see **Profile saved**, or **Couldn't save your profile**. > [!WARNING] > > **Business name** and **Time zone** change the workspace for everyone, and no role is blocked from editing them. Reports use the time zone for day boundaries and peak hours, campaigns use it to hold sends outside **Working hours**, and your AI agent is told the current day and time in it. A wrong zone shifts daily figures and can send campaigns at the wrong hour. A business name you type is kept: later store syncs and onboarding re-runs do not overwrite it. Home counts days in your browser's time zone instead; see [Home dashboard](/analytics/dashboard). ### Privacy and analytics **Manage privacy choices** reopens the consent dialog for optional analytics and advertising tracking, so you can change what you accepted at sign-up. **Read the privacy policy** opens the policy on trypopcorn.ai, in Arabic when the app is in Arabic. ### Leave a workspace The last panel, **Leave workspace**, appears only when you belong to another workspace you can work in; a suspended one doesn't count. **1. Open the panel** On **Settings → Profile**, find the row titled "Leave" and your workspace's name: "You'll lose access to its inbox, customers and settings. Your other workspaces aren't affected." **2. Confirm** Click **Leave workspace**, then **Leave** on "Leave *name*?" ("You'll need a new invitation to come back."). You see "You left *name*" and Popcorn opens your other workspace. If you can't leave, **Couldn't leave the workspace** explains why: "You're its only owner. Make another member an owner first.", "It's your only workspace now, so there would be nowhere to go." or "Your other workspaces are suspended, so there would be nowhere to go." See [Several workspaces](/settings/team-and-roles#several-workspaces). ## Notifications Open **Settings → Notifications**. Each row is an inbox event with a switch. When it is on, **Channels** shows three checkboxes: **In-app**, **Browser** and **Sound**. | Event | Fires when | | - | - | | **Unassigned messages** | A customer sends a message no one is handling | | **Customer replies** | A customer replies in a conversation assigned to you | | **Conversation assignments** | A conversation is assigned to you | | **Handovers** | The agent hands a conversation to your team | Click **Save changes**. You see **Notification settings saved**, or **Couldn't save notification settings**. If the page can't load you see **Couldn't load notification settings** with **Try again**. ### What an alert looks like * **Pop-up.** A message in the corner of the app with the customer's name and a preview, and **View**, which opens the conversation. If several arrive at once, the extras are gathered into "New activity in N more conversations". * **Browser alert.** A desktop notification from your browser, shown only while Popcorn is in the background or another window has focus, and only after you allow it. It closes itself after about ten seconds, and clicking it opens the conversation. * **Sound.** Plays only while Popcorn is in the background, and only for events whose **Sound** box is ticked. If you tick **Browser** and your browser has not been asked yet, a banner offers **Allow**. If it was blocked, the banner reads "Your browser blocks notifications from Popcorn AI. Allow them in your browser's site settings." You get no alert while you are on the Inbox, because the list updates in front of you, or while you have that conversation open. On the web, **In-app** and **Browser** act together: with either ticked you get the pop-up, and the browser alert when it applies. Clear both and nothing arrives, whatever **Sound** says. ### Defaults Defaults follow your role in the workspace you are looking at: | Role | Events on | Sound | | - | - | - | | **Owner**, **Admin** | All four | **Customer replies** and **Conversation assignments** | | **Manager**, **Agent**, **Viewer** | **Customer replies** and **Conversation assignments** | The same two | **In-app** and **Browser** are ticked for every event. A role change takes effect straight away for any event you have not changed. Once you save a different setting for an event, that choice stays the same in every workspace you belong to. ### What these settings don't cover * Email and Slack alerts for handovers are set per agent; see [Connect knowledge, tools and channels](/agents/connect-knowledge-tools-channels). * Alerts on your phone come from the app's own switch; see [Mobile app](/inbox/mobile-app#push-notifications). * **Assignment notifications** on **Settings → General** is a workspace option and does not change your alerts. * Emails about a WhatsApp number, such as one that needs a reconnect or Meta refusing payment for your WhatsApp account, go to the workspace's Owner and Admins and can't be turned off here. See [Channels troubleshooting](/channels/troubleshooting). ## Communication Open **Settings → Communication** to choose how Popcorn tells you about new features. These messages are separate from inbox notifications, and you can opt out at any time. | Option | Default | What you get | | - | - | - | | **In-app announcements** | On | "See what's new when you sign in." | | **Email updates** | On | "Occasional emails about new features and improvements." Every one carries an unsubscribe link, which turns this off | | **WhatsApp updates** | Off | Major feature news on WhatsApp, sent to the number on your account | With a number on file, **WhatsApp updates** reads "Major feature news, sent to" and the number. Without one the switch stays off and a banner reads "Add a phone number to get WhatsApp updates." with **Add phone number**, which sends you back here afterwards. You can always turn it off. Consent belongs to the number you opted in with: if your account's number changes, the switch goes off until you opt in again. Click **Save changes**. You see **Communication preferences saved**, **Couldn't save preferences**, or **Couldn't load your communication preferences** with **Try again**. ## Language Popcorn is available in English, Arabic and Spanish. Open the workspace menu at the top of the sidebar, find **Language**, and choose **English**, **العربية** or **Español**; the same menu holds **Sign out**. Arabic switches the whole app to right-to-left. The choice is stored in your browser and is yours alone; it does not change the language the AI agent uses with customers. ## Troubleshooting | Symptom | Fix | | - | - | | No browser notifications arrive | Tick **Browser** for the event, allow notifications for Popcorn in your browser, and keep the tab on a page other than the Inbox: nothing is shown while you are on the Inbox, and only a tab in the background or without focus gets a browser alert | | No alert for unassigned messages or handovers | Those two are off by default unless you are **Owner** or **Admin**. Turn them on | | No pop-up for a conversation you have open | Expected. Alerts are skipped for the conversation you are reading | | **WhatsApp updates** is disabled | Your account has no phone number. Use **Add phone number** | | **WhatsApp updates** turned itself off | Your account's phone number changed. Turn it on again to consent for the new number | | **Reports** show days shifted | Fix the **Time zone** on **Profile** | | **Leave workspace** is missing | You belong to only one workspace, your other workspaces are suspended, or you are viewing another account | ## Related * [Settings overview](/settings/overview) * [Inbox overview](/inbox/overview) for what the folders and assignments mean * [Team and roles](/settings/team-and-roles) to change someone's role # Shipping and payment Source: https://docs.trypopcorn.ai/settings/shipping-and-payment Set the shipping options, delivery coverage and payment methods the AI agent uses when it creates an order for a customer in chat. When the agent's **Take orders in chat** switch is on, it can collect an address and create an order inside the conversation. **Settings → Shipping** tells it where you deliver and what delivery costs; **Settings → Payment** tells it which payment methods it may offer and where customers send a bank transfer. Without these, the agent has no delivery fee to add and no payment method to ask for. ## Before you start * Both pages are listed for every predefined role (orders view access). Changing them needs orders edit access (Owner, Admin, Manager), and deleting a shipping option needs orders delete access. See [Team and roles](/settings/team-and-roles). * Turn on **Take orders in chat** on the agent's **Actions** tab; see [Capabilities](/agents/capabilities). * The Shipping page depends on which store is connected. With Shopify the list is titled **Delivery coverage** and fees are left to Shopify's checkout. With Zid, Salla or no store it is titled **Shipping options** and you set fees and delivery times in Popcorn. > [!NOTE] > > During setup, the agent step can open **Add delivery fee and time** (or **Add delivery time**, when your store already gave each delivery option its fee), **How customers pay** and **Add your IBAN**. They save the same delivery, payment and bank information as the pages below. ## Shipping options This is the page you get with a Zid or Salla store, or with no store connected. Each option is a delivery method with a fee, a delivery window and the countries and cities it covers. **1. Add an option** Go to **Settings → Shipping** and click **Add shipping option**. **2. Describe it** Fill in **Name**, **Fee**, **Fastest delivery (days)** and, if you like, **Slowest delivery (days)**, **Free shipping over** and **Store shipping ID**. Leave **Active** on. The money labels show your default currency, for example **Fee (SAR)**. **3. Choose where it applies** Under **Countries**, search and tick each country. Each starts as **All cities**; click **Choose cities**, tick the cities, and click **Save cities**. **4. Save** Click **Save**. The page confirms **Shipping option saved**. | Field | Meaning | | - | - | | **Name** | What the customer sees as the delivery method | | **Store shipping ID** | Optional. The method's identifier in your store; filled in for you when you use **Sync from store**. Zid needs it to create the order | | **Fee** | Amount added to the order, in the workspace [default currency](/settings/workspace#products). Enter 0 for free delivery | | **Free shipping over** | When the order's product subtotal (before delivery and cash-on-delivery fees) reaches this amount, the fee is 0. Leave it empty, or 0, for no threshold. For free delivery on every order, set the fee to 0 | | **Fastest delivery (days)** / **Slowest delivery (days)** | Expected delivery in days. The list shows "3 days" or "2 to 5 days". The slowest can't be shorter than the fastest | | **Active** | Inactive options are ignored at checkout | | **Countries** and **Cities covered** | Which countries, and which cities in each, the option delivers to. Choose at least one country, and at least one city in each unless it is **All cities** | The table lists **Name**, **Fee** ("Free" for 0, with "Free over" and the amount underneath, and, for an option synced from a Zid zone, its cash on delivery terms), **Delivery time**, **Status** (**Active** or **Inactive**) and **Ships to**, a summary such as "Saudi Arabia, all cities" or "Saudi Arabia and 3 more". Click the **Ships to** summary (on a phone, **View places** in the row menu) to see every country in a **Ships to** dialog. Click a row, or use **Edit** in its menu, to change it. **Delete** asks for confirmation ("Your agent will stop offering this option to customers. This can't be undone.") and then shows **Shipping option deleted**. ### Sync from store **Sync from store** pulls the delivery methods defined in your Zid or Salla store so you do not retype them. The button shows only with one of those stores connected. 1. Click **Sync from store**. In **Sync shipping from your store**, Popcorn lists each method with its store ID, its store status, and a badge: **New** or **Already synced**. Zid prices a method by zone, so a Zid method appears once per zone, with the zone's cities and its cash on delivery terms: **Cash on delivery fee** and the amount, **Cash on delivery, no fee**, or **No cash on delivery**. 2. Tick the methods to import. For each one enter **Fee** and **Fastest delivery (days)** (both required), and optionally **Slowest delivery (days)** and **Free shipping over**. A Zid zone's fee starts at the fee Zid sets for it; other fields start from what Popcorn already has, or what the store sends. 3. If an option that is active in Popcorn is turned off or missing in the store, it is listed under a warning ("Deactivate them so your agent stops offering them."); tick **Deactivate** to switch it off in Popcorn too. 4. Click **Sync methods**. The page confirms **Shipping methods synced**, or says how many didn't ("2 of 3 shipping methods didn't sync") and which; open **Sync from store** again to retry them. If the store has no methods the dialog reads "Your store has no shipping methods yet." > [!WARNING] > > When you connect Zid and it is the store your checkout runs on, Popcorn adds your active Zid delivery options, one per zone, if you have none yet. They carry Zid's fee for each zone when Zid shares it (a zone priced by weight has none), and never a delivery time. When Popcorn can't read Zid's zones, the options arrive with no fee. An option with no fee, or with no **Store shipping ID**, can't be ordered: the agent tells the customer your team will confirm delivery and hands the conversation over. Check that every option has a fee, and add delivery times so the agent can quote them. See [Zid](/integrations/zid#shipping-methods). ## Delivery coverage (Shopify) With a Shopify store, shipping rates and delivery windows are handled in Shopify's checkout, so Popcorn only needs to know where you deliver: "Countries and cities your agent can accept before sending a Shopify checkout." Click **Add delivery coverage**, give it a **Name**, choose **Countries** and cities, and click **Save**. The table shows only **Name**, **Status** and **Ships to**, and **Sync from store** is not offered. ## How the agent uses shipping at checkout 1. The agent checks the customer's country against your active options. If you have active options and none covers that country, it is told delivery isn't available there and asks the customer for a supported country or city. If you have no active options at all, it carries on with the customer's city. 2. It picks the active option that covers the customer's city, under any common spelling such as "Makkah" and "Mecca". When several options cover the city, it uses the one that costs this order least: an option the order gets free delivery on counts as free, and for cash on delivery the cash on delivery fee counts too. An option with no fee is used only when no option with a fee covers the city; with Zid it then stops the order, as the warning above says: the agent tells the customer your team will confirm the delivery cost and hands the conversation over. If the customer asks for another option that covers their city, the agent uses that one. 3. It adds that option's fee to the order, or 0 when the order reaches **Free shipping over**. With Zid, the fee is quoted with any VAT Zid adds on top at checkout once Popcorn knows it: for a fee you entered or changed yourself, that is after the first Zid order that uses it; see [Zid](/integrations/zid#checkout-and-payment). 4. If no option covers the city: * With Shopify or Zid, and active coverage in place, the order is not created and the agent asks for a supported city or country. * With Salla or no store, the order is created with a delivery fee of 0. 5. For cash on delivery, an option synced from a Zid zone uses the zone's own terms: its cash on delivery fee replaces the one under **Settings → Payment**, and a zone that shows **No cash on delivery** doesn't take it. The agent then names the options to that city that take cash on delivery, or asks for another payment method. 6. The order summary names the option and its fee. If that option is switched off or replaced by a sync before the customer taps **Confirm order**, the customer gets a fresh summary with the option that delivers to their city now. ## Payment methods Open **Settings → Payment**. **Payment methods** ("Choose how customers can pay.") has three switches, and the agent only offers the ones that are on. A new workspace starts with cash on delivery on. | Method | Setting | What happens at checkout | | - | - | - | | **Cash on delivery** | The switch | "Customers pay in cash when the order arrives." | | | **Charge a cash on delivery fee** | "Added to orders paid in cash on delivery." Enter **Fee amount** (0 or more); a "CoD Fee" line is added to every cash-on-delivery order, except where a Zid zone sets its own fee. With Zid, the fee is quoted with any VAT Zid adds on top once Popcorn has learned it from a Zid order that uses the fee. The switch shows only while cash on delivery is on | | **Bank transfer** | The switch, with **Bank name**, **Account holder** and **IBAN** | "Customers pay by bank transfer to your account." The agent gives the customer these details after the order. **Account holder** and **IBAN** are required while it is on; **Bank name** is optional | | **Payment link** | The switch | "Customers pay online through a link." The agent creates the order and sends a payment link from your store. It needs a connected store that can issue payment links | The **IBAN** is checked before saving: it starts with your country code, such as SA, then digits, and Popcorn refuses one with the wrong length or a wrong digit. A bank transfer saved earlier as free text keeps working and is shown under the fields ("Your agent now sends this to customers who choose bank transfer. Fill in the fields above to replace it.") until you fill them in. A bar appears with "Unsaved changes". Click **Save changes** (or **Discard**); the page confirms **Payment methods saved**. If one method can't be saved you see, for example, "Couldn't save bank transfer", and the others still save. If the page can't load it reads **Couldn't load payment methods**. If no method is on, or bank transfer is on with no details saved, the agent doesn't take the order for that method: it offers another, or tells the customer your team will confirm how to pay and hands the conversation over. With a Zid store, Popcorn first offers only the methods Zid accepts and never uses one your Zid store has off; once you change payment methods here, your choice wins. See [Zid](/integrations/zid#checkout-and-payment). ## What the customer sees 1. The agent asks for the delivery address (on WhatsApp through an address form; in Saudi Arabia it can use the national address). See [Orders](/orders/overview). 2. It checks the city against your coverage and quotes the delivery window and fee. 3. It asks for a payment method from those you enabled and creates the order, adding the delivery fee and, for cash on delivery, the CoD fee. 4. For bank transfer it sends your bank details; for payment link it sends the link; the order appears under **Orders** and in your store. ## Troubleshooting | Symptom | Cause and fix | | - | - | | The agent says delivery is not available for a country or city | No active option covers that country (any store), or, with Shopify or Zid, no option lists that city. Edit the option's coverage or add one. | | Delivery fee is 0 on every order | The order subtotal reached **Free shipping over**, the option's fee is 0, or (with Salla or no store) no option matched the city. Check the fee, the threshold and the coverage. | | The agent hands over a Zid order to your team before confirming | The Zid option has no fee or no **Store shipping ID**, or no delivery option exists. Open **Settings → Shipping** and complete it. | | Cash on delivery is refused for some cities (Zid) | The Zid zone for that city shows **No cash on delivery**. Change it in Zid and sync it again with **Sync from store**. | | Customers choose a payment method you do not offer | Turn it off on **Settings → Payment** and save. | | A bank transfer is refused | No bank details are saved. Add **Account holder** and **IBAN** on **Settings → Payment**. | | Payment link orders fail with no link | Your connected store cannot issue payment links, or no store is connected. Use cash on delivery or bank transfer, or connect a store. | | "Getting shipping methods from your store" never finishes, or **Couldn't get shipping methods from your store** | The store connection is not ready. Check **Integrations** and reconnect if needed. See [Integrations troubleshooting](/integrations/troubleshooting). | ## Related * [Orders](/orders/overview) for the order list, statuses and where orders appear in your store * [Workspace settings](/settings/workspace) for **Default currency**, quantities and custom options * [Capabilities](/agents/capabilities) for the agent's **Take orders in chat** and **Track orders** switches # Team and roles Source: https://docs.trypopcorn.ai/settings/team-and-roles Invite teammates, manage pending invites, change or remove members, work in several workspaces, and see what each role allows. Your workspace can have as many teammates as you need. Each one signs in with their own email, gets their own notification preferences, and is limited by a role. **Settings → Team members** is where you invite and manage people; **Settings → Roles and permissions** shows exactly what each role can do. You can also open **Team members** from the workspace menu at the top of the sidebar. ## Before you start * Both pages are listed for anyone with team view access (Owner, Admin, Manager and Agent). Inviting needs team-management create access; changing roles, resending and cancelling invites needs full access; removing people needs delete access. Among the predefined roles only **Owner** and **Admin** have these, so Managers and Agents can read the page but not change it. * You can only act on people ranked below you, and you can never give a role above your own. The **Owner** can't be removed and nobody can change the Owner's role. ## Invite teammates **1. Open Team members** Go to **Settings → Team members** and click **Invite team members**. **2. Enter emails** Type one or more addresses in **Email addresses**. "To invite several people, separate their email addresses with commas." You can invite up to 50 people at a time; repeated addresses are counted once. **3. Choose a role** Pick a **Role**. It starts on **Agent**. You can't pick **Owner** or a role above your own. **4. Send** Click **Send invites**. The page confirms **Invites sent** and the addresses appear under **Pending invites**. If an address is mistyped you see "Check these addresses:" and the list, with "Enter a full email address, like [name@store.com](mailto:name@store.com)". If someone already belongs to the workspace you see **Already in this workspace**. Each invitee receives an email from Popcorn with a link. The invitation only works for the address it was sent to: * **No Popcorn account yet.** The link opens sign-up, and they create the account with that email. * **Already have an account.** They sign in and land on a page titled "Join *Workspace*" ("*Name* invited you to join *Workspace* on Popcorn."), where **Join workspace** accepts it and **Not now** leaves it for later. If they are signed in with a different email, the page says "This invitation is for another account" and offers **Sign out**. Their other workspaces stay as they are. * **Link already used, cancelled or replaced.** The page says "This invitation can't be used". Ask the person who invited you to send a new one. ## Pending invites **Pending invites** ("N waiting to join") lists invitations that have not been accepted, with **Email**, **Role**, **Invited by** and **Date sent**. With full team-management access each row has a menu: | Action | What happens | | - | - | | **Resend invite** | A new email with a fresh link is sent and you see **Invite sent again**. The link in the earlier email stops working. | | **Cancel invite** | After you confirm ("Cancel the invite to *email*?"), the invitation is deleted and you see **Invite cancelled**. The link in the email stops working. You can invite them again later. | Once someone accepts, they move from **Pending invites** to the members table. If you act on an invite that was already accepted or cancelled, the page says "This invite was already accepted or cancelled." and refreshes both lists. ## Manage members **Members** ("N members") shows **Name** (with email), **Role** and **Date added**. * **Change a role.** With full team-management access, the **Role** cell is a drop-down for every member ranked below you. Pick the new role and the page confirms **Role updated**. The change applies immediately, and the member's notification defaults follow the new role (settings they customised are kept). If the role has your own rank, Popcorn asks first: "Give *name* the *role* role?", "After this you can't change their role or remove them from the team. Only someone with a higher role than yours can." Click **Change role** to continue. * **Remove a member.** With delete access, open the row menu and choose **Remove from team**. After you confirm ("Remove *name* from the team?"), the person loses access to this workspace right away and you see **Member removed**. You can invite them again later. If someone changed the team since the page loaded, a change is refused and the page refreshes. The reasons read: "This person is no longer in the workspace. Refresh the page.", "Their role is now equal to or higher than yours, so you can't change it or remove them.", "You can't give someone a role higher than your own." and "That role no longer exists. Refresh the page and try again." ## Several workspaces One account can belong to more than one workspace, for example one per store or brand. Each has its own team, inbox, agent, plan and billing, and your role can differ in each. * **Switch.** Open the workspace menu at the top of the sidebar. **Workspaces** lists yours, with a check beside the one you are in; choose another to switch. A workspace that is turned off shows **Suspended** and can't be opened. * **Create.** Choose **Create workspace** in the same menu, enter a **Workspace name** (usually the store or brand name) and click **Create workspace**. You become its Owner and land in its setup, on the free plan with its own credits. One account can create up to 10 workspaces; after that you see "You've created as many workspaces as one account can. Contact support to add more." * **Leave.** **Settings → Profile** has a **Leave workspace** section when you belong to another workspace you can work in. Click **Leave workspace**, then **Leave**; "You'll lose access to its inbox, customers and settings. Your other workspaces aren't affected." You need a new invitation to come back. You can't leave if you are its only Owner ("Make another member an owner first.") or if it is your only workspace. ## Roles and permissions **Settings → Roles and permissions** lists the roles with their member counts ("N roles"). Click a role to see its permission matrix. The five predefined roles are marked **System** and are read-only ("System roles can't be changed."). People with full team access see the note "Every workspace uses these roles. Custom roles aren't available yet." | Role | Summary | | - | - | | **Owner** | "Full access to everything. Can't be removed." Nobody can change the Owner's role. | | **Admin** | "Full access to all app resources." The same permissions as Owner; an Admin can be changed or removed by the Owner. | | **Manager** | "Manages daily operations and team workflows": everything in the Inbox, campaigns, templates, Knowledge, products, customers, orders, macros and tags; can view and edit agents; read-only on analytics, team, settings, billing, API keys and integrations. | | **Agent** | "Handles conversations and customer interactions": works the Inbox, creates and edits templates, edits customers, creates and edits macros and tags; read-only on campaigns, Knowledge, products, orders, analytics and team. | | **Viewer** | "Can view data but not change it": read-only on the Inbox, campaigns, templates, Knowledge, products, customers, orders, analytics, macros and tags. | ### The permission matrix Each role is a grid of areas (rows) against actions (columns): **View**, **Create**, **Edit**, **Delete** and **Full access**. **Full access** on a row includes every other action on that row, plus the right to publish Knowledge articles. | Area | Owner, Admin | Manager | Agent | Viewer | | - | - | - | - | - | | **Inbox** | Full access | Full access | View, Create, Edit | View | | **Campaigns** | Full access | Full access | View | View | | **Knowledge base** | Full access | Full access | View | View | | **Products** | Full access | Full access | View | View | | **Customers** | Full access | Full access | View, Edit | View | | **Orders** | Full access | Full access | View | View | | **Agents** | Full access | View, Edit | none | none | | **Integrations** | Full access | View | none | none | | **Analytics** | Full access | View | View | View | | **Team** | Full access | View | View | none | | **Settings** | Full access | View | none | none | | **Billing** | Full access | View | none | none | | **API keys** | Full access | View | none | none | | **Macros** | Full access | Full access | View, Create, Edit | View | | **Tags** | Full access | Full access | View, Create, Edit | View | Templates follow the same access as campaigns for Managers and Viewers; Agents can view, create and edit templates. What the areas control in practice: * **Agents** with **View, Edit** (Manager) can change an agent's configuration and tools but not create or delete agents. * **Agents** view is what makes **Agent**, **Knowledge** and **Spotlight** appear under **Your agent** in the sidebar. Agents and Viewers do not see them. * **Customers**, **Orders**, **Products** and **Campaigns** view each make their sidebar item appear, and **Analytics** view makes **Reports** appear. * **Integrations** view is what makes **Integrations** appear at the foot of the sidebar. **Billing** view is what makes **Plan and billing** appear in the workspace menu, and **Team** view makes **Team members** appear there. Agents and Viewers see neither of the first two. * **Settings** view is what makes **Settings → General** appear; saving it needs **Edit** or **Full access**. * **API keys** view is what makes **Settings → AI assistants** and **Settings → API keys and webhooks** appear. * Areas a role cannot view are hidden from that person's sidebar. Role permissions also bound what a connected AI assistant may do on that person's behalf; see [Permissions and safety](/ai-assistants/permissions-and-safety). ## Troubleshooting | Symptom | Cause and fix | | - | - | | "You can't give someone a role higher than your own." | Choose a role at or below yours, or ask the Owner or an Admin to send the invite. | | "You can invite up to 50 people at a time." | The invite had more than 50 distinct addresses. Split it into two. | | "Their role is now equal to or higher than yours, so you can't change it or remove them." | Only someone above that member's rank can change it. Ask the Owner. | | The invitee says the link does not work | The invite was resent (older links stop working) or cancelled, or they are signed in with a different email. Resend and ask them to use the exact invited address. | | **Invite team members** is missing | Your role lacks team-management create access. | | A member cannot see **Reports**, **Settings → General** or **Integrations** | Their role has no view access to that area. Change the role. | | **Leave workspace** is missing | You belong to only one workspace, your other workspaces are suspended, or you are viewing another account. | ## Related * [Settings overview](/settings/overview) for which settings pages each role sees * [Profile and notifications](/settings/profile-and-notifications) for per-person notification defaults by role # Workspace settings Source: https://docs.trypopcorn.ai/settings/workspace Configure Settings → General: media handling, auto follow-up, working hours, default currency, product options, Zid VAT and the Knowledge workspace. **Settings → General** ("Inbox, working hours, products and VAT for your workspace.") holds the options that apply to the whole workspace: how the Inbox treats media, which template is used when a WhatsApp reply falls outside the 24-hour window, the working hours that hold campaigns, the currency and product options your AI agent works with, and VAT handling for Zid prices. Everyone on the team is affected by what you save here. ## Before you start * You need settings view access to open the page (Owner, Admin, Manager) and settings edit access to change it (Owner, Admin). Without edit access every control is disabled and a banner reads "Only people who can edit workspace settings can change these." See [Team and roles](/settings/team-and-roles). * Changes are applied only when you click **Save changes** in the **Unsaved changes** bar; **Discard** reverts them. A successful save reads **Settings saved**. If it fails you see **Couldn't save your settings** and your edits stay on the page. * If the page can't load you see **Couldn't load these settings** with **Try again**. ## Inbox The **Inbox** panel ("How the inbox handles media, follow-ups and assignments.") has three settings. | Setting | What it does | | - | - | | **Let the agent handle media messages** | When on, images, videos and documents a customer sends are passed to the agent, which keeps handling the conversation; stickers and GIFs reach it as pictures. When off, "images, videos and files go to your team with the reply below": the conversation leaves the agent and lands in **Unassigned** for your team. Voice notes, locations, button and list replies, catalog orders and address-form responses are handled by the agent whatever this setting is. | | **Reply to media messages** | Shown while the setting above is off. The text sent to the customer when the agent can't handle a file and the conversation is handed over ("Sent to the customer, then the conversation goes to your team."). Leave it empty to hand over silently. | | **Auto follow-up** | "Follows up with an approved template within the 24-hour response window." Turning it on reveals **Follow-up template**. | | **Follow-up template** | An approved WhatsApp template ("Select a template"). On a number running in coexistence with the WhatsApp Business app, when a reply can't be delivered because the customer's 24-hour window has closed, Popcorn sends this template instead. See [WhatsApp coexistence](/channels/whatsapp-coexistence). | | **Assignment notifications** | A workspace switch saved with these settings. It does not control your own alerts; those are per person under **Settings → Notifications** (see [Profile and notifications](/settings/profile-and-notifications#notifications)). | Only approved templates appear in **Follow-up template**. With auto follow-up on, a save is blocked until you pick one: you see "You don't have an approved template yet." when none is approved, or "Pick an approved template, or follow-ups won't be sent." A template that was selected and is no longer approved shows as "name (not approved)". If templates can't load you see **Couldn't load your templates** with **Try again**; create and submit templates under [Templates](/campaigns/templates). The agent's own follow-up messages (how many, after how long, with what instructions) are configured per agent in its **Configuration** tab; see [Capabilities](/agents/capabilities). ## Working hours "Set the hours used for business-hours reports and campaign restrictions." | Setting | What it does | | - | - | | **Restrict to working hours** | When on, a campaign launched outside the hours below is held and starts sending at the next **Start**. "When off, campaigns can be sent at any time." | | **Start** / **End** | Times in the workspace time zone. Overnight ranges such as 22:00 to 06:00 are allowed. | Under the fields the page says "Times use your workspace time zone:" with the zone name and a **Change it on Profile** link, which opens **Settings → Profile**. Reports always use these hours for **Median first reply in business hours** and the business-hours column of the conversation export, whether or not the restriction switch is on. If you have never set them, reports assume 09:00 to 17:00. See [Reports](/analytics/reports). Working hours do not stop the agent from replying; it answers customers around the clock. ## Products The **Products** panel ("Currency and product options for your catalog.") has four settings. | Setting | What it does | | - | - | | **Default currency** | The currency used on Home, in shipping fees, and in the price the agent quotes when currency visibility is on. Pick the currency your store sells in; the list shows ISO currencies such as "USD - US Dollar (\$)". | | **Product quantities** | When on, stock quantities are shown in **Products**, the agent sees the available quantity of each product it recommends, and a product whose stock is 0 is marked inactive when it syncs, is imported or is saved, so the agent stops recommending it. When off, stock is ignored, and active products are sent to your Meta catalog with a placeholder quantity instead of the real stock. | | **Custom product options** | When on, each product page shows a **Custom options** section where you add fields that collect extra information from customers during checkout, such as a gifter name or engraving text, optionally with an extra price. | | **Show currency to the agent** | When on, the agent is told that all product prices are in the default currency and mentions it when quoting prices. | > [!NOTE] > > If your workspace still holds an older currency symbol such as \$ (which Zid and Salla catalogs treat as the store's own currency), it shows as its own option until you pick a currency. Saving other changes does not rewrite it. Saving a change to the currency, quantities, custom options, currency visibility or VAT reloads product data across the app. Catalog behaviour, recommendation weights and the product page are described in [Product catalog](/products/catalog). ## VAT The **VAT** panel ("How VAT applies to prices synced from Zid.") depends on whether a Zid store is connected. * **Zid connected.** The panel reads "VAT is set in your Zid settings": "Your agent reads it from Zid, and you can choose it yourself there." **Open Zid settings** opens the Zid settings dialog on Integrations. The button shows only to roles that can edit settings, and the panel itself only if your role can view integrations. See [VAT for Zid prices](/integrations/zid#vat-for-zid-prices). * **No Zid store connected.** The panel offers **Add VAT to Zid prices** ("Turn on only if your Zid store shows prices without VAT.") with **VAT rate (%)**. When it is on, Popcorn adds VAT to every product price and sale price as it syncs from Zid, so the agent quotes the price the customer pays. The page shows the worked example "With 15%, a Zid price of 256.52 is saved in Popcorn AI as 295.00." The rate must be from 0 to 100; otherwise you see "Enter a rate from 0 to 100." The adjustment is applied at sync time and does not affect Shopify or Salla catalogs. After changing it, use **Resync products** on the Zid integration so existing prices are refreshed. ## Knowledge workspace People who can edit settings also see a **Knowledge workspace** switch ("Use the new knowledge workspace for articles, drafts and version history."). See [Knowledge](/knowledge/overview). ## Troubleshooting | Symptom | Cause and fix | | - | - | | Every control is disabled | Your role can view settings but not edit them (Manager). Ask an Owner or Admin. | | A campaign launched during the day has not started sending | **Restrict to working hours** is on and the current time is outside **Start** to **End** in the workspace time zone. It starts at the next **Start**. Check the time zone on **Settings → Profile**. | | The agent keeps recommending out-of-stock products | Turn on **Product quantities**, then **Resync products** so stock levels mark them inactive. | | The agent quotes prices without a currency, or the wrong one | Set **Default currency** and turn on **Show currency to the agent**. | | Zid prices in Popcorn are lower than in your store | Your Zid store shows prices without VAT. Set VAT in the Zid settings on Integrations, or, with no Zid store connected, turn on **Add VAT to Zid prices** here, enter the rate, save and resync. | | Customers sending photos are handed to your team every time | **Let the agent handle media messages** is off. Turn it on if you want the agent to handle images and documents. | | **Save changes** does nothing with auto follow-up on | No approved template is selected. Pick one under **Follow-up template**. | ## Related * [Profile and notifications](/settings/profile-and-notifications) for the workspace time zone * [Shipping and payment](/settings/shipping-and-payment) for the other checkout-related settings * [Send a campaign](/campaigns/send-a-campaign) for how working hours affect a launch * [Reports](/analytics/reports) for the business-hours response-time figures * [Product catalog](/products/catalog) for stock, custom options and recommendation weights # Create a custom tool Source: https://docs.trypopcorn.ai/tools/create-a-tool Build a tool with New tool: description, method, URL, headers, parameters and their sources, then connect it to an agent and test it. This page walks through **New tool** from an empty form to a tool your agent calls in a test conversation. Read [Custom tools overview](/tools/overview) first if you have not decided what the tool should do. ## Before you start * The API endpoint: an `https://` address, the method, and which values it expects in the path, query string, or body. * Any key or token the API needs, to put in a header. Keys go in **Headers**, never in the URL. * A clear sentence about when the agent should use the tool. You will put it in **Description**. ## Open the form Click **Agent** in the sidebar, open an agent, go to its **Actions** tab and click **Add tool** in the **Tools** panel. If you already have tools, you can also click **Manage tools** and then **New tool**, or press **g** then **t** to reach the **Tools** page. The **New tool** page has the form in the main column and **Start from API docs** beside it (above the form on a narrow screen). ## Optional: start from the API documentation **Start from API docs** can fill the form for you from a public documentation page. **1. Paste the documentation link** Under **Documentation link**, enter the address of the docs for one endpoint ("Paste a link to the docs for one endpoint and we fill in the form.") and click **Fill in from docs**. The page must be publicly reachable; local or private addresses, and addresses with a username and password, are refused. **2. Wait for the result** Reading the docs takes up to a minute. When it finishes you see **Filled in from the docs. Check the details before you create the tool.** and the name, description, method, URL, headers and parameters are filled in. Every `{placeholder}` in the URL gets a parameter of its own. **3. Review everything** Check each field against the documentation. Placeholders such as `Bearer ` in **Headers** must be replaced with your real value, and parameters the reader guessed may need better descriptions. If it does not work, the message under the link says why: | Message | What to do | | - | - | | **Enter a full URL, starting with https\://** | The link is not a web address. Paste the full address. | | **Enter a public https\:// link to the API docs.** | The link is private or unsupported. Use a public documentation page. | | **The docs took too long to read. Try a link to the page for one endpoint.** | Link to the page for a single endpoint instead of a whole reference. | | **Your session expired. Sign in again and retry.** | Sign in again. | | **You don't have permission to create tools.** | Ask an Owner or Admin to change your role. | | **Couldn't read those docs. Fill in the details below instead.** | Fill in the form by hand. | ## Details | Field | What to enter | | - | - | | **Name** | A short name, such as *Check repair status*. | | **Description** | When the agent should use the tool and what it returns. The agent reads this to decide whether to call the tool, so name the trigger: *Use when a customer asks about the status of a repair or service ticket. Returns the current stage and expected completion date.* | ## Request **1. Method and URL** Choose the **Method** (`GET`, `POST`, `PUT`, `DELETE`) and enter the **URL**. For values that belong in the path, use curly braces: `https://api.example.com/tickets/{ticketId}`. Do not add keys to the URL; define query parameters instead. **2. Headers** Click **Add header** for each header and fill in its **Name** and **Value**, for example `Authorization` and `Bearer sk_live_…`. Values are hidden as you type; **Show values** and **Hide values** toggle them in browsers that can hide them. **Remove header** deletes a row. **3. Query parameters** Click **Add query parameter** for each value that goes in the query string ("Values your agent fills in and sends in the URL."). Path values written as `{name}` in the URL are defined here too: give the parameter the same name and it is marked **In the URL**. **4. Body parameters** For any method other than `GET`, the **Body parameters** panel appears. Click **Add body parameter** for each field of the JSON body ("Values your agent fills in and sends in the request body."). If you switch to `GET`, body parameters are not saved, and the **Method** field warns you: "Body parameters aren't saved for GET requests. Switch to POST or PUT to keep them." ### Parameter fields | Field | Meaning | | - | - | | **Name** | The exact field name your API expects. Use letters, numbers and underscores, no spaces. | | **Type** | **Text**, **Number**, **Yes or no**, **Object** or **List**. For an **Object**, click **Add property** to define its fields. For a **List**, choose **Type of each item**; for a list of objects, click **Add property**. **Hide properties** and **Show properties** collapse and expand them. | | **Description** | What the value is, in words the agent can match to the conversation: *The 6-digit ticket number printed on the receipt.* The field reads "What the agent should send". | | **Required** | The agent must have a value before calling. If it is missing, the agent asks the customer. Required parameters need a description. | | **In the URL** | A badge, not a setting: it appears when the parameter's name matches a `{placeholder}` in the URL. | ### Where the value comes from Each parameter has a **Where the value comes from** setting that decides how its value is found at call time: | Source | Behaviour | | - | - | | **Ask the customer** (default) | The agent takes the value from what the customer said, or asks for it. | | **Customer profile** | Popcorn fills the value from the customer's profile. Pick the **Profile field**: **Email**, **First name**, **Last name**, **Phone number** or **User ID**. **If the profile has no value** decides what happens when it is empty: **Ask the customer**, **Use the fixed value** (then fill in **Fixed value**), or **Stop with an error** (the tool does not run and the agent gets an error). | | **Fixed value** | The value you enter under **Fixed value** is always sent. Use it for fixed settings your API needs, such as a store code. | A line under the parameter restates the choice in plain words, for example "Filled from the customer's email. If it's missing, your agent asks the customer." Tools created through an AI assistant can also use **Customer details**, which fills the value from the customer's details when they do not give one in the chat. The form shows that source but does not offer it. ## Create the tool As soon as you type, a bar across the top reads **Unsaved changes** with **Discard** and **Create tool**. Click **Create tool**. Checks run first; if something needs fixing you see **Fix *N* fields to save**, the first problem is highlighted, and each one says what to do: | Message | What to do | | - | - | | **Give the tool a name** / **Describe when your agent should use this tool** | Fill in **Name** and **Description**. | | **Enter a full URL, starting with https\://** | The **URL** is empty or not a web address. | | **ticketId is in the URL but no parameter has that name. Add a parameter named ticketId.** | A placeholder such as `{ticketId}` in the URL has no matching parameter. Add one with the same name. | | **ticketId is in the URL, so it can't be an object. Pick another type.** | A parameter that fills the URL must be **Text**, **Number**, **Yes or no** or **List**. | | **Give this parameter a name** / **Use letters, numbers and underscores, no spaces** | Fix the parameter's **Name**. | | **Required parameters need a description** | Describe the parameter, or untick **Required**. | | **Add a property, or pick another type** | An **Object** needs at least one property. | | **Two parameters are saved as ticketId. Rename or remove one.** | Two parameters would send the same field. | On success you see **Tool created** and the page for the new tool opens, where later changes are saved with **Save changes**. > [!NOTE] > > Header values are hidden after saving. When you reopen a tool, a header with a stored value shows *Saved. Leave blank to keep it.* in its **Value** field. Leave it blank to keep the stored value, type a new value to replace it, or remove the row to clear it. The name is matched regardless of capitalisation, so retyping `x-api-key` for a stored `X-API-Key` keeps the value. ## Edit a saved tool Open the tool from the **Tools** page (click its row, or **⋯** then **Edit**), change what you need, and click **Save changes** in the bar that appears ("Tool saved" confirms it). You can edit a tool while agents have it switched on: the tool is updated in place, and every copy your agents hold in this workspace is updated with it. A header value you type applies to those copies too; a value you leave blank stays as each copy has it stored. A new URL, method or header value applies to the agents' next calls. A new name, description or parameter set is part of each agent's published version, so click **Save and review** and **Publish changes** on the agent for those to reach customers. A tool you have shared in the showcase stays shared, and saving also refreshes its showcase copy. If that refresh fails you see **Tool saved, but its showcase copy wasn't updated**; see [Tools showcase](/tools/marketplace). ## Connect the tool to an agent **1. Open the agent** Click **Agent** in the sidebar and open the agent that should use the tool. **2. Switch the tool on** On the **Actions** tab, find your tool in the **Tools** panel ("Actions you set up yourself or add from the marketplace.") and switch it on. The tool does not need to be shared. **3. Publish** Click **Save and review**, then **Publish changes**. Until you publish, live conversations do not have the tool. See [Test and publish](/agents/test-and-publish). If a tool could not be enabled, saving shows *Couldn't turn on … Your other changes were saved.*; switch the tool on again and click **Save and review**. ## Test it 1. Publish the agent with the tool switched on. The test chat uses the published version. 2. Open the **Test your agent** panel (or **Test agent** on a narrower screen) and ask for something only the tool can answer, the way a customer would: *Where is my repair? Ticket 482913.* Under the reply, **Used** followed by the tool's name shows that it ran. 3. Check the reply against your system, then open the conversation in the Inbox and click **Details** next to the tool name. **Message source** shows the **Tool used**. If the agent never calls the tool, sharpen the **Description** and the parameter descriptions; that is all the agent has to go on. If it calls the tool but replies with an error, check that the URL is `https://` with no keys in the query string and no username or password in it, that it is not a private or internal address, that the header value is correct, and that your API returns JSON. ## Delete a tool On the **Tools** page, open the **⋯** menu on the tool's row, choose **Delete** and confirm with **Delete tool**. You see **Tool deleted**. Deletion is refused while an agent still has the tool switched on: turn it off in the **Tools** panel on each agent's **Actions** tab and save those agents first. The app's message calls that panel the agent's "Tools tab". ## Related * [Custom tools overview](/tools/overview) * [Tools showcase](/tools/marketplace) * [Knowledge, tools, channels and notifications on the agent page](/agents/connect-knowledge-tools-channels) # Tools showcase Source: https://docs.trypopcorn.ai/tools/marketplace Add a custom tool that another Popcorn account shared, or publish your own to the Tools showcase when it meets the sharing rules. The Tools showcase, called the marketplace on the agent page, is where custom tools are shared between Popcorn accounts. Open it with **Open marketplace** in the **Tools** panel on an agent's **Actions** tab, or with **Tools showcase** on the **Tools** page. Anything listed there was published by a Popcorn account and can be added to yours. ## Add a shared tool to your workspace **1. Find the tool** In the showcase, use **Search tools** to filter by name or description, then click a tool. When nothing matches, the page reads **No tools match "…"** with **Clear search**. **2. Read what it does** The tool's page shows its image and description. **After you add it** lists the four steps that follow: open the tool from your tools list, add your own header values such as your API key, save the tool, and turn it on from an agent. **3. Add it** Click **Add to my tools**. You see **Tool added** and return to the **Tools** page, where the copy now appears. If it cannot be added you see **Couldn't add this tool. Try again.** **4. Enter your own credentials** Open the copy from **Tools**, fill in every header **Value** (they are empty on purpose), review the URL and parameters, and click **Save changes**. **5. Connect it to an agent** Open the agent, switch the tool on in the **Tools** panel on its **Actions** tab, then click **Save and review** and **Publish changes**. Test it in **Test your agent**. See [Create a custom tool](/tools/create-a-tool) for the full connection and testing steps. What you get: * The copy is yours: edit it, rename it, or delete it without affecting the original or anyone else's copy. * Updates the author makes later do not reach your copy. Add the tool again if you want the newer version, then delete the old copy. * The copy is private to your workspace unless you share it yourself and it meets the rules below. ## Share your own tool > [!WARNING] > > Shared tools are visible to every Popcorn account, not only your team. Popcorn only accepts tools that cannot carry anyone's credentials, so most tools stay private to your workspace. A tool can be published only when all of these are true: | Rule | Detail | | - | - | | Reviewed public API host | The **URL** is an `https://` address on a host Popcorn has reviewed as a public API. At the moment those are the Salla and Zid APIs (`api.salla.dev` and `api.zid.sa`). A tool that calls your own API stays private. | | Standard address | No custom port, username, password or `#` fragment; the path uses only standard segments (for example `api`, `orders`, `products`, `customers`, or a version such as `v1`) and placeholders such as `{orderId}`; any `?` options are limited to static ones such as a version, format, language or paging number. | | No credentials | No parameter has a **Fixed value**, no parameter is named like a credential (for example `api_key`, `token`, `password` or `secret`), and no header name, tool name or description looks like a pasted key or token. | If a tool does not qualify, **Publish tool** fails with **Couldn't publish this tool**. ### What is shared | Shared | Not shared | | - | - | | Name, description and image | Header **values** (keys, tokens) | | Method and URL | Your agents or conversations | | Header **names** | | | Query and body parameters, with their descriptions and sources | | Someone who adds your tool gets a copy with empty header values and must enter their own. They cannot see yours. Because other accounts' agents will read your tool exactly as you wrote it, check that the **Description** and parameter descriptions explain the tool to someone who has never seen your system. ### Publish it **1. Save the tool first** Publishing shares the saved tool. Open it from the **Tools** page; if you have unsaved edits, the panel reads **Save your changes before publishing.** **2. Add an image** In the **Tools showcase** panel beside the form ("Share this tool so other Popcorn AI accounts can add it."), choose an image under **Image**: JPG, PNG, GIF or WebP, up to 5 MB. A different type or a larger file shows **Use a JPG, PNG, GIF or WebP image up to 5 MB.** **Publish to showcase** stays disabled until an image is set (**Add an image to publish.**). **3. Publish it** Click **Publish to showcase**. The dialog **Publish *name* to the showcase?** explains that other Popcorn AI accounts will see its name, description and image, can add a copy with its URL and parameters, and do not get your header values. Click **Publish tool**. You see **Published to the showcase**, the panel reads "Other Popcorn AI accounts can find and add this tool.", the tool's page shows an **In showcase** badge, and the **Tools** page lists the badge in its **Showcase** column. You can replace the image later and save; saving a shared tool also refreshes its showcase copy, and if that fails you see **Tool saved, but its showcase copy wasn't updated**. There is no way to make a shared tool private again from the dashboard ("You can't unpublish it here"). ## Remove a tool from the showcase Delete the tool: on the **Tools** page, open the **⋯** menu on its row, choose **Delete** and confirm with **Delete tool**. The listing disappears from the showcase. Copies that other accounts already added keep working, because each copy is independent. Deletion is refused while one of your agents has the tool switched on. Switch it off in the **Tools** panel on the agent's **Actions** tab, save the agent, then delete. ## Related * [Custom tools overview](/tools/overview) * [Create a custom tool](/tools/create-a-tool) * [Knowledge, tools, channels and notifications on the agent page](/agents/connect-knowledge-tools-channels) # Custom tools overview Source: https://docs.trypopcorn.ai/tools/overview Let your agent call your own systems during a conversation, how a tool looks to the agent, and what your API must support. A custom tool is an HTTP request your agent can make in the middle of a conversation: check a booking in your reservation system, look up a customer's loyalty points, get the status of a repair ticket, or register a warranty claim. Knowledge covers facts you can write down; tools cover facts the agent must fetch live. ## Where to find tools Tools has no row in the sidebar. Click **Agent**, open an agent and go to its **Actions** tab. The **Tools** panel lists your tools with a switch for each, and its buttons lead to the rest: * **Manage tools** (shown once you have a tool) opens the **Tools** page with your list. * **Add tool** starts a new tool. * **Open marketplace** opens the **Tools showcase**, where tools other Popcorn accounts shared can be added to yours. > [!TIP] > > Anywhere in the app, outside a text field or a dialog, press **g** and then **t** to open the **Tools** page. ## What a tool is made of | Part | What it does | | - | - | | **Name** and **Description** | What the agent reads to decide whether the tool fits the customer's request. The description is the single most important field: *Look up the delivery status of a repair ticket by ticket number* tells the agent exactly when to use it. | | **Method** and **URL** | Where the request goes: `GET`, `POST`, `PUT` or `DELETE`, and an `https://` address. Parts of the path that change per call, such as a ticket number, are written as `{ticketId}`. | | **Headers** | Fixed values sent with every call, typically an authorization key. Header values are stored and never shown again after saving; when you reopen the tool, a header with a stored value shows *Saved. Leave blank to keep it.* in its **Value** field. | | **Query parameters** and **Body parameters** | The values the request needs. Each has a name, a **Type** (**Text**, **Number**, **Yes or no**, **Object** or **List**), a description the agent reads, and a source: ask the customer, take it from the customer's profile, or use a fixed value. Body parameters are only available for methods other than `GET`. | For the full field-by-field walkthrough, see [Create a custom tool](/tools/create-a-tool). ## What happens during a conversation 1. The agent reads the tool's description and its parameter descriptions alongside everything else it can do, and decides on each message whether the tool fits. 2. It gathers the parameter values: from what the customer said, from the customer's profile, or from the fixed value you configured. If a required value is missing, it asks the customer. 3. Popcorn sends the request to your URL with the configured method, headers, query string, path values and JSON body. 4. Your API's JSON response is handed back to the agent, which uses it to write the reply in its own words. 5. If the request fails or your API returns an error, the agent receives the error instead of data and replies without the result. In the Inbox, a reply that used a tool shows **Used** followed by the tool's name under the message. Click **Details** to open **Message source**; **Tool used** names the tool. See [Working with conversations](/inbox/working-conversations). ## What your API must support | Requirement | Detail | | - | - | | HTTPS | The URL must use `https://`. An `http://` address can be saved but is refused when the agent calls it, and so are addresses with a username and password in them or a `#` fragment. | | No keys in the URL | Only a few static options may follow a `?`: `version` (or `api-version`, `v`), `format` (`json`, `xml` or `csv`), `locale` (or `lang`), and paging numbers such as `page`, `limit`, `offset`, `per_page` or `page_size`. Anything else, such as `?key=…`, is refused when the agent calls the tool. Put keys in **Headers** and per-call values in **Query parameters**. | | JSON | Popcorn sends `Content-Type: application/json` and asks for `application/json` back. | | Reachable from the internet | Popcorn calls your API from its servers, not from the customer's device. Private or internal addresses (such as `localhost`, names ending in `.local` or `.internal`, or a local network IP) are refused. | | No redirects | Popcorn does not follow redirects, so use the final address. | ## An example A repair shop wants the agent to answer "where is my repair?" from its ticketing system. | Field | Value | | - | - | | **Name** | Check repair status | | **Description** | Use when a customer asks about the progress of a repair or service ticket. Returns the current stage and the expected completion date. | | **Method** | `GET` | | **URL** | `https://api.example-repairs.com/tickets/{ticketId}` | | **Headers** | `Authorization` with the value `Bearer …` | | **Query parameters** | `ticketId` (**Text**, **Required**, marked **In the URL**): *The 6-digit ticket number printed on the receipt.* Source: **Ask the customer**. | When a customer writes "any news on ticket 482913?", the agent recognises the request from the description, takes `482913` from the message, calls `https://api.example-repairs.com/tickets/482913`, and answers from the JSON that comes back. ## Manage your tools The **Tools** page lists one row per tool with its image (or initial), name and description. The **⋯** menu on a row offers **Edit** and **Delete**, and a **Showcase** column with an **In showcase** badge appears once you have shared a tool. The back link at the top reads **Agents**. The list shows tools that belong to the workspace; which agents use them is managed from each agent's page, not here. ## Tools and agents A tool in the **Tools** list belongs to your workspace. To let an agent use it, switch it on in the **Tools** panel on the agent's **Actions** tab and publish the agent; Popcorn then gives that agent its own copy of the tool, header values included. The tool does not need to be shared. Two consequences follow: * To delete a tool, first switch it off in every agent that uses it and save those agents. Otherwise **Couldn't delete** followed by the tool name appears with the line "If an agent uses this tool, turn it off in that agent's Tools tab first." (that is the **Tools** panel on the **Actions** tab). * Editing a tool needs no disconnecting: the copies your agents hold are updated with it. A new URL, method or header value applies to the agents' next calls. A new name, description or parameter set is part of each agent's published version, so click **Save and review** and **Publish changes** on the agent for those to reach customers. ## The showcase The **Tools showcase** lists tools other Popcorn accounts have shared. You can add one to your workspace with **Add to my tools** and then fill in your own header values. Sharing your own tool has strict rules: it must call a reviewed public API host and carry no keys or fixed values. See [Tools showcase](/tools/marketplace). ## Next steps > **[Create a custom tool](/tools/create-a-tool)** > > New tool, the docs-based starter, parameters, and connecting to an agent. > **[Tools showcase](/tools/marketplace)** > > Add a shared tool, or share one that meets the rules. > **[Agent capabilities](/agents/capabilities)** > > The built-in abilities you turn on on the agent's tabs. > **[Knowledge](/knowledge/overview)** > > For facts you can write down instead of fetching.