Frequently Asked Questions

Kuruvi is a unified inbox + marketplace for small online sellers. It pulls WhatsApp, Instagram DMs, Messenger, Telegram and email into one stream, with Shopify, WooCommerce and eBay order context beside every chat. Built in Flutter, it runs on iOS, Android, macOS, Windows (planned), and web (beta).

No. Sign up free and use unlimited Kuruvi-to-Kuruvi messaging, voice and video calls, group chats and the marketplace — forever, with no card on file.

A card is only needed when you start a 14-day trial of Business or Growth. Stripe captures the card but doesn't charge it for 14 days; cancel anytime in that window and you won't be billed.

iOS and Android are the primary supported platforms. macOS and web run in beta. Windows desktop distribution is planned. Voice and video calls work between any two Kuruvi clients regardless of the platforms on either end.

1. Open Settings → Selling channels → Shopify → Connect with Shopify.
2. Enter your store domain (e.g. yourstore.myshopify.com).
3. Kuruvi opens Shopify's OAuth in your browser; approve.
4. You'll be redirected back; order context starts appearing in the inbox within 30-60 seconds.

See the Shopify section below for backfill timing, contact matching, and team-workspace caveats.

Conversations, contacts and connection state live in your own isolated Firestore data, scoped to your user ID (or your team's ID). External-platform tokens (WhatsApp, Shopify, mail passwords, etc.) sit in a private credentials subcollection that no client — including yours — can read directly; only the server functions that need them can read them.

Email, phone number, and your Stripe customer ID are split out into an owner-only profile document so they aren't visible to other users who view your public profile. Full detail in our Privacy Policy.

Your bot is a separate Telegram account that lives on Telegram's servers — not on your phone. You created it via @BotFather and Kuruvi stores its token.

Kuruvi only sees messages sent to the bot. Messages between two regular Telegram users (your iPhone and your Android, for example) are completely invisible to bots — Telegram blocks that for privacy. This is the #1 source of confusion when people first set up Telegram.

1. Open Settings → Telegram in Kuruvi.
2. Copy your bot link (https://t.me/your_bot_name) with the copy button.
3. Share that link with a friend via WhatsApp, SMS, or email.
4. They tap the link → Telegram opens → tap Start.
5. Their first message lands in your Kuruvi inbox within seconds.
6. From now on you can reply from Kuruvi or message them by @username in the compose screen.

No. This is Telegram's rule, not Kuruvi's. Bots cannot initiate conversations — only reply. There's no workaround that follows Telegram's terms of service. Tools that try to bypass this get banned.

The standard practice is to put your bot link on your website, social profiles, business cards, etc., so customers find it and initiate themselves.

Because that was a regular Telegram chat between two human users — not a message to your bot. Telegram only routes bot-addressed messages to your webhook.

To test: from one of your phones, search for your bot's username (@your_bot_name), open the chat with the bot, and send a message there. That one will appear in Kuruvi.

Approval happens in Meta Business Manager, not Kuruvi. You'll need:

• A verified business profile in Meta Business Manager.
• A phone number not currently used for personal WhatsApp.
• A display name that closely matches your registered business name.

Meta usually approves a display name within 1-3 business days. If you've never used Meta Business Manager, the business verification itself is the slowest step — expect 1-2 weeks end-to-end for a brand new business. Kuruvi can't speed this up; it's entirely on Meta's side.

Free-form messages are normal WhatsApp messages — text, image, document, sticker — and can only be sent within 24 hours of the customer's last reply. Meta calls this the customer service window.

Outside that 24h window you must send a template: a pre-approved message with named placeholders like {{1}} that you fill in at send time. Templates are how shipping confirmations, OTP codes, and re-engagement messages reach customers who haven't messaged you recently.

The most common reasons:

• Wrong category — a marketing template submitted as utility, or vice versa.
• Vague content — "Hi {{1}}, click here for a deal" doesn't meet Meta's bar; they want concrete value.
• Missing opt-in language — marketing templates need to reference the customer's opt-in.
• Promotional emoji or ALL CAPS — gets flagged as low-quality.
• Unbound variables — a {{1}} placeholder with no example value attached.

Resubmit with the issue fixed; Meta's re-review usually completes within 1-2 hours.

In Meta Business Manager → WhatsApp Manager → Phone numbers → Add. The number must not be active on regular WhatsApp; if it is, you'll need to delete that account from WhatsApp first, or use a different number.

Once Meta confirms the number, Kuruvi reads the phone number ID from your connection and routes incoming/outgoing messages to it. You can add multiple numbers to one Meta Business account and switch between them per conversation in Kuruvi.

Yes, but only with a template message pre-approved by Meta (see the template question above). Free-form requires the customer to have messaged you within the past 24 hours.

Kuruvi includes a template manager (Settings → WhatsApp → Templates) so you can submit templates and reuse approved ones.

The customer hasn't replied to you in over 24 hours. Switch to a template message in compose, or wait for them to reply again.

Initial backfill is near-instant for stores under ~5,000 orders — order history starts appearing in the inbox within 30-60 seconds. Beyond that, Kuruvi paginates through Shopify's order API and you'll see the count climb in Settings → Shopify. Webhooks fire in real time once the connection is live, so new orders show up immediately regardless of how big your history is.

Kuruvi matches by phone number first, then email. If the Shopify customer used a different phone format (no country code, a typo, a different number entirely) than the messaging contact, they won't auto-link. You can manually link them in the contact's detail screen — that match is remembered for future orders.

Connections are owned by whoever connected them. When you move to a team workspace, your existing connection stays on your personal user ID. To share order context with the team, disconnect Shopify, switch into the team workspace, and connect again from there. The new connection is then owned by the team and visible to all members.

Only for the cross-listing feature (mark-as-sold sync, listing creates from Kuruvi marketplace). If you only want Kuruvi for order context and customer chats, you can skip the read/write scopes — but cross-listing won't work. We don't push promotional content, edit prices, or modify customers without your explicit action.

1. In WordPress admin: WooCommerce → Settings → Advanced → REST API.
2. Click Add Key. Set Permissions to Read/Write.
3. Copy both the Consumer Key and Consumer Secret immediately — the secret is only shown once.
4. Paste them into Settings → WooCommerce in Kuruvi along with your store URL.

Kuruvi verifies the REST API connection and registers the webhooks (order.created, order.updated, product.created, product.updated) for you. You don't need to set them up manually.

This is almost always WP-Cron, not Kuruvi. To diagnose:

1. In WordPress → WooCommerce → Status → Scheduled Actions.
2. Filter for woocommerce_deliver_webhook_async.
3. If actions sit in Pending for more than a few minutes, WP-Cron is delayed.
4. Either install the WP Crontrol plugin and run cron manually, or configure your host to call https://yourstore.com/wp-cron.php?doing_wp_cron every minute.
5. Confirm webhooks are Active under WooCommerce → Settings → Advanced → Webhooks.

Yes, but you need a real system cron job. Most managed WooCommerce hosts (Pressable, Kinsta, WP Engine, etc.) document this — search their docs for "alternate cron" or "system cron." Once cron runs reliably, webhooks deliver within seconds and Kuruvi catches up automatically.

In a private credentials subcollection in Firestore — not readable from any client. The Cloud Function that talks to WooCommerce reads them with admin privileges; nobody else can see them. If you disconnect, the credentials are deleted server-side immediately.

eBay returns 25005 when your seller account doesn't have a valid merchant location (ship-from address) configured. Kuruvi can't fix this on eBay's side — go to eBay → My eBay → Shipping → Add a ship-from location. Save, then retry the connect or listing in Kuruvi.

This is an eBay rule for any seller who wants to publish offers via their API — it isn't specific to Kuruvi.

Sandbox is eBay's test environment — listings created there aren't real and don't appear to buyers. When you connect in sandbox mode, the connected row shows sandbox next to your username.

For real listings, switch to production by completing eBay's developer keyset upgrade. Kuruvi's connect screen has the link to the eBay developer portal. Most sellers should connect directly to production unless they're explicitly testing.

Yes. eBay is independent — you can have eBay-only, Shopify-only, or any combination. Only the inbox is unified across channels; the connections themselves are separate and can be added or removed individually.

The Business plan ($9.99/month) covers all messaging channels including Telegram, WhatsApp, Messenger, and Instagram DMs. Growth ($24.99/month) adds team accounts, video posting, and analytics.

When you pick a paid plan in Kuruvi, you're redirected to Stripe to enter your card. The card is captured but not charged for 14 days. Cancel anytime in those 14 days and you won't be billed. After 14 days the subscription auto-renews on the same card.

On iOS, subscriptions go through Apple In-App Purchase instead of Stripe — Apple's trial rules apply (similar 14-day window but managed in Settings → Apple ID → Subscriptions).

Settings → Subscription → tap Cancel subscription. You keep access until the end of the current billing period. For iOS users where the app can't show Stripe directly, manage billing on kuruvi.com/account.

Annual billing with two months free is on the roadmap but not shipped yet. For now we keep things monthly so you can leave easily if Kuruvi isn't the right fit. Want to be notified when annual launches? Email hello@kuruvi.com.

Bot tokens, Page Access Tokens, WooCommerce Consumer Secrets, mail passwords, and OAuth refresh tokens are stored in a private credentials subcollection in your Kuruvi project's Firestore — never shared with us or other tenants, and not client-readable. Storage rules restrict access to your own UID. See our Privacy Policy for full details.

No. Connection saves and disconnects require admin or manager role on the team. Agents can read conversations and reply but cannot replace the team's bot token or Page Access Token.

Account deletion is permanent and removes your profile, conversations, OAuth tokens, and Stripe customer reference within 30 days. Start the deletion from Settings or visit our data-deletion page.

Provider records (Stripe invoices, Meta business records, etc.) may remain on the provider's side under their own legal retention rules — that's outside our control.

Both live in an owner-only profile document (users/{uid}/private/profile) so they aren't visible to other users who view your public profile. The public profile only carries your display name, username, and avatar — nothing contactable.