# Credits Source: https://docs.bizzyco.ai/admin-guide/billing/credits Pre-pay for usage beyond your plan with one-time top-ups or auto top-up Credits are a USD balance on your account that Bizzy draws from when usage exceeds your monthly plan allowance. Every consumable — LLM tokens, API calls, MCP calls, storage, email sends, SMS, and voice minutes — bills against credits at the per-tier overage rate. For the full per-tier overage table and how usage is tracked, see [Usage and metrics](/admin-guide/billing/usage). ## Prerequisites * You must be an **Owner** or **Admin** to view the credit balance, purchase credits, or change auto top-up settings * Credit purchases use the same payment method as your subscription ## View your credit balance 1. Navigate to **Settings > Account > Billing** 2. Find the **Credits** card The card shows: | Field | Meaning | | ----------------------- | -------------------------------------------------------------------------------------------------------------------- | | **Current balance** | Available credits in USD. A **Low Balance** badge appears when the balance is at or below your low-balance threshold | | **Lifetime added** | Total credits ever purchased or auto-topped-up | | **Lifetime spent** | Total credits ever consumed by overages | | **Recent Transactions** | 5 most recent credit movements (purchase, auto top-up, consumption, refund) with amount and running balance | If you have more than 5 transactions, a **History →** button expands the list to show all movements. ## One-time credit purchase To buy credits without enabling auto top-up: 1. On the **Credits** card, click **Purchase Credits** 2. In the **Purchase Credits** dialog, enter an amount in USD 3. Click **Purchase** 4. Complete payment in the embedded Stripe Checkout form. Apple Pay, Google Pay, and Link appear inside the same payment form when your browser supports them — no separate wallet button row The amount field is free-form: the default is **$10**, the minimum is **$5**, and the maximum is **\$1,000** per purchase. Credits land in your account immediately on successful payment. ### After you submit Once you click **Pay**, one of three outcomes appears on the billing page: | Outcome | What you see | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Immediate success** | The Credits card refreshes with the new balance. | | **Payment processing** | A notice reading "Your payment is processing. We'll email you when it completes." Credits are added to your account once the payment settles (typically minutes for most methods). | | **Payment error** | A notice reading "We couldn't confirm your payment. Please try again." No credits are added; re-open the purchase dialog to retry with a different card if needed. | The processing outcome applies to bank-debit methods (SEPA, BACS, and similar) that settle asynchronously. Card payments resolve immediately. Credits do not expire and roll over month to month. They are not refundable except where required by law. ## Auto top-up Auto top-up keeps your credit balance topped up automatically so usage never gets cut off mid-month. It's **off by default**. To configure auto top-up: 1. On the **Credits** card, in the **Auto Top-Up** section, click **Enable** (or **Manage** if already enabled) 2. In the **Auto Top Up** dialog, toggle **Enable auto top up** on 3. Confirm your default payment method, or add one if none is on file 4. Set **When credits are below** — the balance at which a top-up fires 5. Set **Purchase this amount** — how much to add per top-up 6. Click **Save** | Setting | Range | | ---------------------------------- | ----------------------------- | | When credits are below (threshold) | \$0 up to the purchase amount | | Purchase this amount | $5 – $100,000 | When your balance drops below the threshold, Bizzy charges your saved payment method for the purchase amount and credits your balance. You receive a `credit_auto_recharge_triggered` notification on each successful top-up and a `credit_purchase_failed` notification if the charge fails. A failed auto top-up does not retry automatically. Update your default card on the [Payment methods](/admin-guide/billing/payment-methods) page and trigger a one-time purchase to restore service. ## What happens when credits run out When your monthly allowance is exhausted **and** your credit balance is depleted, behavior depends on the consumable: * **LLM tokens (agent chat).** Agent conversations are blocked. The chat shows an **Out of Credits** card with a button to purchase more * **Other consumables (API calls, MCP calls, email, SMS, voice, storage).** New requests fail until you top up credits, your billing cycle resets, or you upgrade * **Free tier.** Same behavior — Free accounts can purchase credits to keep working past the included allowance You also receive notifications as you approach exhaustion: | Notification | When | | ------------------------- | --------------------------------------------------------------------------------------------- | | `credit_balance_low` | Balance falls below your auto top-up threshold (or a default threshold if auto top-up is off) | | `credit_balance_depleted` | Balance reaches zero | ## Next steps See current usage and per-tier overage rates View and pay invoices for credit purchases # Billing Source: https://docs.bizzyco.ai/admin-guide/billing/index Manage billing, subscriptions, and usage in Bizzy Bizzy uses an account-based subscription model with tiered pricing. As an administrator, you manage billing at the account level, which covers all organizations and team members under your account. ## Billing Concepts ### Account-Based Billing Billing in Bizzy is managed at the **account** level, not the organization level. A single account can contain multiple organizations, and all usage across organizations counts toward your account's limits. ``` Account (Billing Entity) ├── Subscription (Tier & Limits) ├── Organizations (Workspaces) │ └── Members (Users) └── Account Members (Billing Admins) ``` ### Subscriptions Your subscription determines: * **Resource limits** - How many organizations, seats, agents, MCP servers, and automations you can create * **Consumable allowances** - Monthly limits for LLM tokens, API calls, and MCP calls * **Feature access** - Which AI models and features are available ### Seats Seats represent unique users across all organizations in your account. A user who belongs to multiple organizations only counts as one seat. Each tier includes a certain number of seats, and you can purchase additional seats on paid tiers. ## Quick Reference | Tier | Price | Seats | Businesses | Agents | LLM Tokens/mo | | -------------- | -------- | --------- | ---------- | --------- | ------------- | | **Free** | \$0 | 1 | 1 | 3 | 100K | | **Starter** | \$25/mo | 3 | 3 | 10 | 1M | | **Pro** | \$100/mo | 10 | 10 | 50 | 10M | | **Enterprise** | Custom | Unlimited | Unlimited | Unlimited | Unlimited | See [Usage and metrics](/admin-guide/billing/usage) for the full object-and-consumable table including MCP servers, automations, storage, email sends, SMS, and voice minutes. ## Billing Topics Compare features, resource limits, and AI model access across all tiers Subscription pricing, seat add-ons, trial periods, and billing cycles Current usage, account object limits, and per-tier overage rates Balance, one-time purchases, and auto-recharge Compare tiers and switch your subscription View, download, and pay invoices in-app Add, remove, and set the default card on file Tax info and subscription changes Warning thresholds and downgrade behavior ## Managing your subscription From **Settings > Account > Billing** you can: * View current usage and remaining allowances ([Usage and metrics](/admin-guide/billing/usage)) * Upgrade or downgrade your subscription ([Upgrade](/admin-guide/billing/upgrade)) * Purchase credits or enable auto-recharge ([Credits](/admin-guide/billing/credits)) * View, download, and pay invoices ([Invoices](/admin-guide/billing/invoices)) * Manage saved cards ([Payment methods](/admin-guide/billing/payment-methods)) * Update tax info and subscription details ([Stripe Customer Portal](/admin-guide/billing/portal)) Only account members with **Owner** or **Admin** roles can access billing settings and make changes to the subscription. # Invoices Source: https://docs.bizzyco.ai/admin-guide/billing/invoices View, download, and pay the invoices on your Bizzy account New See every invoice Bizzy has issued to your account — directly inside the app, with links out to Stripe-hosted copies and downloadable PDFs. ## Prerequisites * You must be an **Owner** or **Admin** to view invoices * An active Stripe customer record (created automatically the first time you save a card or upgrade a plan) ## Open the page 1. Navigate to **Settings > Account > Billing** 2. Click **View invoices** in the page header You'll land on the Invoices table. ## What you'll see Each row shows: | Column | What it means | | --------------- | ---------------------------------------------------------- | | **Date** | When the invoice was issued | | **Description** | The line description, or the billing period if none | | **Amount** | Total due in the invoice currency | | **Status** | Current state — see [statuses](#statuses) below | | **Actions** | View hosted invoice, Download PDF, and (when open) Pay now | The list shows the most recent 20 invoices first. Click **Load more** to append the next page. ## Actions | Action | What happens | | ----------- | ------------------------------------------------------------------------------------------------------------------- | | **View** | Opens the Stripe-hosted invoice page in a new tab — usable for self-service payment and download | | **PDF** | Downloads the invoice PDF directly from Stripe | | **Pay now** | Available on **Open** and **Past due** invoices. Charges your default card on file in-app — see [Pay now](#pay-now) | ### Pay now Click **Pay now** on any open invoice to charge your default card without leaving the app. A confirmation dialog shows the card that will be used and the exact amount. * If you have more than one card on file, click **Use a different card** in the dialog to pick another one before confirming. * If the charge is declined, the decline reason appears inline in the dialog so you can switch cards and retry — your session stays put. * If you don't have a card on file yet, the dialog links to **Payment methods** so you can add one and try again. On a successful charge, the row's status flips to **Paid** automatically and your account state catches up (for example, a past-due account returns to active). ## Statuses | Status | Meaning | | ----------------- | ------------------------------------------------------------------------------- | | **Paid** | Charge succeeded; nothing more is owed | | **Open** | Finalized and awaiting payment, not yet overdue | | **Past due** | Open invoice whose due date has passed — pay soon to avoid service interruption | | **Draft** | Not finalized yet; usually a transient state during billing cycles | | **Uncollectible** | Stripe marked the invoice unrecoverable (rare; contact support if you see this) | | **Void** | The invoice was canceled and isn't owed | ## Empty state If you haven't been charged yet — or your account doesn't have a Stripe customer record yet — the page shows **"No invoices yet — they'll appear here after your first charge."** This is expected for trial-only accounts and brand-new sign-ups; no action is needed. ## Related Manage the cards used to settle invoices How credit purchases appear as invoices # Understanding Limits Source: https://docs.bizzyco.ai/admin-guide/billing/limits Learn how Bizzy enforces usage limits and what happens when you exceed them Bizzy enforces two types of limits: resource limits (for creating objects) and consumable limits (for usage). This page explains how each type of limit works and what to expect as you approach or exceed them. ## Types of Limits ### Resource Limits Resource limits control how many of each resource type you can create: * Organizations * Seats (team members) * MCP Servers * Agents * Automations **Resource limits are hard limits.** When you reach the limit, you cannot create additional resources until you upgrade your tier or delete existing resources. ### Consumable Limits Consumable limits control your monthly usage of: * LLM Tokens * API Calls * MCP Calls **Consumable limits have flexible enforcement** with warning thresholds and a grace period for paid tiers. Free tier has a hard cutoff at 100%. ## Warning Thresholds Bizzy monitors your consumable usage and sends notifications at key thresholds: | Threshold | Level | What Happens | | --------- | -------- | ----------------------------------------------------------- | | **90%** | Warning | Email and in-app banner alerting you to high usage | | **100%** | Critical | Email and in-app modal; overage billing begins (paid tiers) | | **110%** | Cutoff | Service paused until next billing cycle or upgrade | ### Free Tier Warnings When you approach your limits on the Free tier: * **At 90%:** "You've used 90% of your monthly allowance. Upgrade to continue." * **At 100%:** "You've reached your limit. Upgrade to Starter for more capacity." The Free tier has a **hard cutoff at 100%**. There is no grace period or overage billing. Service is paused until your next billing cycle or you upgrade. ### Paid Tier Warnings When you approach your limits on paid tiers (Starter, Pro, Enterprise): * **At 90%:** "You've used 90% of your monthly allowance. Overage billing will apply beyond 100%." * **At 100%:** "You've exceeded your allowance. Overage charges: \$X.XX. Consider upgrading." * **At 110%:** "You've reached the maximum overage limit. Service paused until next billing cycle or upgrade." Paid tiers have a **soft limit with a 10% overage allowance**. You can continue using the service up to 110% of your monthly allowance, with overage charges applying for usage between 100% and 110%. At 110%, service is paused until you purchase more credits or your billing cycle resets. ## Viewing Your Usage You can monitor your usage at any time from the usage dashboard in your account settings. The dashboard shows: * Current usage for all consumables * Remaining allowance for the billing period * Progress bars indicating usage percentage * Days until your allowances reset * Historical usage trends To access your usage dashboard: 1. Go to your account settings 2. Select **Usage** from the sidebar 3. View your current period usage and resource capacity ## What Happens When Limits Are Exceeded ### Resource Limits When you reach a resource limit: * You cannot create new resources of that type * Existing resources continue to work normally * You see an error message explaining the limit * You're prompted to upgrade or delete existing resources ### Consumable Limits (Free Tier) When you reach 100% on the Free tier: * The affected service is paused immediately * Existing data is preserved * You can still access your account and view data * AI features (agents, automations) that consume tokens are disabled * API calls return a 429 error with upgrade instructions ### Consumable Limits (Paid Tiers) When you exceed your allowance on paid tiers: 1. **100% - 110%:** Overage billing applies, service continues 2. **At 110%:** Service is paused 3. You receive email notifications at each threshold 4. Service resumes when: * You purchase additional credits * Your billing cycle resets * You upgrade to a higher tier ## Managing High Usage Check your usage dashboard regularly, especially during high-activity periods. Set up internal alerts when you approach 80% of your limits. If you anticipate high usage, purchase credits in advance. Credits can be used immediately and carry over between billing cycles. Review your agents and automations for opportunities to reduce token consumption. Shorter prompts and more efficient workflows can significantly reduce usage. If you consistently exceed your limits, upgrading to a higher tier is often more cost-effective than paying overage charges. Compare the cost of overages against the higher tier pricing. ## Limit Reset * **Monthly allowances** reset on your billing cycle anniversary date * **Resource limits** do not reset; they are permanent caps * **Credit balances** do not expire and carry over between periods Your billing cycle anniversary is the day you started your subscription. For example, if you subscribed on the 15th, your allowances reset on the 15th of each month. ## Upgrading to Increase Limits When you upgrade your subscription: * New resource limits take effect immediately * New consumable allowances are prorated for the current period * You're charged a prorated amount for the upgrade * Any existing overage usage is resolved with the new higher limits ## API Rate Limit Enforcement API rate limits work differently from consumable limits. While consumable limits track your total monthly usage, rate limits control how many requests you can make per minute. | Tier | Requests per Minute | | -------------- | ------------------- | | **Free** | 10 | | **Starter** | 30 | | **Pro** | 100 | | **Enterprise** | Custom | ### How Rate Limits Work * **Per-minute window:** Rate limits reset every minute * **429 responses:** When you exceed your rate limit, API requests return a `429 Too Many Requests` error * **No overage billing:** Unlike consumable limits, exceeding rate limits does not incur additional charges * **Automatic recovery:** Simply wait for the next minute window and your requests will succeed again If you consistently hit rate limits, consider upgrading to a higher tier for increased capacity. Enterprise tier offers custom rate limits tailored to your needs. ## Downgrade Behavior When you downgrade to a tier with lower limits, your existing resources are preserved but may become restricted. ### What Happens to Excess Resources * **Resources are not deleted:** Your existing organizations, agents, automations, and other resources remain intact * **Read-only access:** Excess resources become read-only - you can view and use them but cannot modify them * **Creation blocked:** You cannot create new resources of that type until you're under the limit * **Deletion required:** To regain full access, delete excess resources until you're within your new tier's limits ### Examples | Scenario | Result | | ---------------------------------------------------- | ------------------------------------------------- | | Pro (10 orgs) → Starter (3 orgs) with 5 orgs | 2 orgs become read-only until you delete them | | Pro (50 agents) → Starter (10 agents) with 25 agents | 15 agents become read-only | | Starter → Free with 5 seats | 2 seats must be removed before adding new members | ### Consumable Allowances on Downgrade * New consumable limits take effect at the start of your next billing cycle * Current period usage is not affected * If you've already exceeded the new tier's limit, overage billing continues until cycle reset Plan your downgrade carefully. Consider archiving or exporting data from resources you'll need to delete. Compare tier features and limits View pricing and consumable allowances # Payment methods Source: https://docs.bizzyco.ai/admin-guide/billing/payment-methods View, add, set as default, and remove the payment methods saved on your Bizzy account New Manage the payment methods saved on your account directly inside Bizzy — no need to leave Bizzy for routine changes. ## Prerequisites * You must be an **Owner** or **Admin** to view or change payment methods * An active billing customer record (created automatically the first time you save a payment method or upgrade a plan) ## Open the page 1. Navigate to **Settings > Account > Billing** 2. Click **Manage payment methods** in the page header You land at `/settings/account/billing/payment-methods`. ## What you can do | Action | What happens | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Add payment method** | Opens an in-app dialog with a secure form powered by Stripe Checkout. Save a card or US bank account (ACH); Apple Pay, Google Pay, and Link also appear automatically when supported by your browser or device. After your bank approves it (including any 3-D Secure step), it appears in the list. | | **Set as default** | Marks the payment method as the one used for subscription renewal, credit top-ups, and consumable overage charges. The current default's row shows a **Default** badge. | | **Remove** | Detaches the payment method from your account immediately. Confirm in the prompt before it's removed. You can't remove your last payment method — add a new one first if you want to swap. | The first payment method you add is automatically promoted to default. ### After you add a payment method Once you complete the form and click **Save payment method**, one of three outcomes appears at the top of the page: | Outcome | What you see | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **Immediate success** | The payment method appears in your list and is set as default if it's your first one. | | **Save processing** | A notice reading "Your payment is processing. We'll email you when it completes." This can occur for bank-debit methods that settle asynchronously. | | **Error** | A notice reading "We couldn't save your payment method. Please try again." Nothing was saved; try again or use a different payment method. | ## Empty state When no payment methods are saved yet, the page shows an empty state with a prominent **Add payment method** call-to-action. The same dialog opens whether you click the empty-state button or the **Add payment method** button in the page header. ## Default payment method behavior * Exactly one payment method is the default at any time. Setting a non-default one as default replaces the previous one. * If you remove the default and others remain, Bizzy automatically promotes the most-recently-added remaining payment method on the next page load. To pick a different default, use **Set as default** on the one you prefer. * Subscription invoices, credit top-ups, and overage charges all bill the default payment method. * At least one payment method must always be on file. Removing your only one is blocked; add a replacement first. ## If a payment fails When we can't charge your default payment method for a subscription renewal, your account enters a 48-hour grace window. Retries run on a schedule (roughly +1h, +24h, +47h after the first failure) before canceling the subscription. You'll receive escalating emails over that window: | When | Notification | What it tells you | | ---------------- | ------------------------------------- | ------------------------------------------------------------------------------------------ | | Right away | Payment failed | The first attempt didn't go through; update your payment method to keep your subscription. | | \~24 hours later | Service interruption warning | Still no successful payment; one more retry remains. | | \~48 hours later | Final warning — cancellation imminent | Your subscription is about to be canceled. | If all retries fail, the subscription is canceled and Bizzy automatically: * Moves the account to the **Free** plan * Disables (but does not delete) resources beyond Free-tier limits — agents, automations, MCP servers, and extra members * Sends a final "subscription canceled" email summarizing what happened Your data is preserved throughout — nothing is deleted. To restore your subscription, update your payment method in the [Stripe Customer Portal](/admin-guide/billing/portal) and pick a plan. Disabled resources can be re-activated once you're back within that tier's limits. ## Related View, download, and pay invoices in-app Use the hosted portal for tax info and plan changes How credits and auto-recharge use your default payment method # Stripe Customer Portal Source: https://docs.bizzyco.ai/admin-guide/billing/portal Manage tax info, plan changes, and cancellation in the Stripe-hosted billing portal Bizzy uses Stripe's customer-portal for tax info, plan changes, and cancellation. The portal is hosted by Stripe and opens with single-sign-on from your Bizzy account. Saved cards are managed in-app on the [Payment methods](/admin-guide/billing/payment-methods) page, and invoices live in-app on the [Invoices](/admin-guide/billing/invoices) page — no portal hop required for either. ## Prerequisites * You must be an **Owner** or **Admin** to open the portal * An active or trialing subscription with a Stripe customer record (the portal is not available before your first paid plan) ## Open the portal 1. Navigate to **Settings > Account > Billing** 2. Click **Manage billing in Stripe** A new tab opens directly into the Stripe-hosted portal. When you finish, close the tab to return to Bizzy. Portal sessions are rate-limited to 10 per minute per account. If you've recently opened a session, wait a few seconds before opening another. ## What you can do The portal supports several focused flows. Bizzy links you directly to the right one based on which button you click. | Flow | Triggered from | What you can do | | ----------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------- | | **Manage billing** | Default **Manage billing in Stripe** button | Update tax info, see subscription history | | **Cancel subscription** | The "Cancel subscription" link | Cancel at period end with optional feedback | | **Change plan** | "Upgrade" or "Downgrade" buttons on the [Upgrade page](/admin-guide/billing/upgrade) | Switch tier, switch monthly ↔ annual, confirm prorated charges | ## Downgrade pre-validation Plan changes that *increase* limits go straight to the portal. Plan changes that *decrease* limits run through a pre-validation step in Bizzy before handing off to Stripe. If your current usage exceeds the target tier's limits — for example, you have 25 agents and want to downgrade to a plan that allows 10 — Bizzy blocks the downgrade and sends you back to **Settings > Account > Billing** with a banner that lists the specific violations: > Too many agents: 25 in use, 10 allowed on Starter To complete the downgrade: 1. Reduce the listed objects below the target tier's limits (delete agents, remove team members, archive automations, etc.) 2. Return to the [Upgrade page](/admin-guide/billing/upgrade) and select the lower tier again 3. Confirm the change in the portal Pre-validation only catches account objects (seats, businesses, agents, MCP servers, automations). Consumable usage above the new tier's allowance will simply bill as overages on the next cycle — see [Limits](/admin-guide/billing/limits) for details. ## Errors and recovery | Banner you see | What to do | | ----------------------- | -------------------------------------------------------------------------------------------------------------------- | | `Portal is unavailable` | Your account has no Stripe customer record yet — start from the [Upgrade page](/admin-guide/billing/upgrade) instead | | `Downgrade blocked` | See the listed violations and reduce usage before retrying | | `Rate limited` | Wait a few seconds and try again | ## Next steps View, download, and pay invoices in-app Compare tiers and switch plans Subscription, seat, and overage pricing # Pricing & Consumables Source: https://docs.bizzyco.ai/admin-guide/billing/pricing Understand Bizzy pricing, monthly allowances, and overage billing Bizzy uses a subscription-based pricing model with monthly consumable allowances. This page explains how pricing works, what's included in each tier, and how overage billing applies. ## Subscription Pricing | Tier | Monthly | Annual | Savings | | -------------- | ------- | ------- | ------------- | | **Free** | \$0 | - | - | | **Starter** | \$25 | \$250 | 2 months free | | **Pro** | \$100 | \$1,000 | 2 months free | | **Enterprise** | Custom | Custom | Contact sales | Annual billing saves you 2 months free. The Starter tier includes a 30-day free trial with no payment method required until the trial ends. ## Monthly Consumable Allowances Each tier includes monthly allowances for consumable resources. These reset on your billing cycle anniversary date. | Consumable | Free | Starter | Pro | Enterprise | | -------------- | ------- | --------- | ---------- | ---------- | | **LLM Tokens** | 100,000 | 1,000,000 | 10,000,000 | Custom | | **API Calls** | 1,000 | 10,000 | 100,000 | Custom | | **MCP Calls** | 500 | 5,000 | 50,000 | Custom | ### Understanding Consumables * **LLM Tokens** - Tokens used when AI agents process messages, generate responses, or run automations. Both input and output tokens count toward your limit. * **API Calls** - Requests made to the Bizzy API, whether from your applications or third-party integrations. * **MCP Calls** - Calls made to MCP servers connected to your agents. **API rate limits** also vary by tier (Free: 10 req/min, Starter: 30 req/min, Pro: 100 req/min). See the [Subscription Tiers](/admin-guide/billing/tiers) page for full details. ## Credit System Paid tiers (Starter, Pro, Enterprise) use a credit system for usage beyond your monthly allowance. ### How Credits Work 1. Each month, you receive your tier's consumable allowances 2. Usage is first deducted from your monthly allowance 3. When you exceed your allowance, usage is automatically deducted from your credit balance in real-time 4. You can purchase credits at any time from the billing dashboard ### Overage Rates When you exceed your monthly allowance, the following rates apply: | Consumable | Rate | Unit | | -------------- | ------ | ----------------- | | **LLM Tokens** | \$0.10 | per 10,000 tokens | | **API Calls** | \$0.01 | per 100 calls | | **MCP Calls** | \$0.01 | per 100 calls | **Free tier has no overage billing.** When you reach 100% of your limit on the Free tier, service is paused until the next billing cycle or you upgrade. Paid tiers allow usage up to 110% of the limit before pausing. ### Credit Purchase Options You can purchase credits from the **Billing** section in your account dashboard. Credits are available in the following amounts: | Amount | Credits | | ------ | -------------- | | \$10 | 1,000 credits | | \$20 | 2,000 credits | | \$50 | 5,000 credits | | \$100 | 10,000 credits | **Credit conversion rate:** 1 credit = \$0.01. Credits never expire and carry over between billing cycles. ### Example: Overage Calculation A Pro tier account with a 10M token allowance and \$50 credit balance: | Usage Range | Cost | | ----------------- | -------------------------------------------- | | 0 - 10M tokens | Included in subscription | | 10M - 15M tokens | $50 from credit balance ($0.10 per 10K) | | Beyond 15M tokens | Paused until credits purchased or next cycle | ## Additional Seats If you need more seats than included in your tier, you can purchase additional seats. | Tier | Included Seats | Additional Seat Cost | | -------------- | -------------- | -------------------- | | **Free** | 3 | Not available | | **Starter** | 10 | \$5/seat/month | | **Pro** | 25 | \$8/seat/month | | **Enterprise** | Custom | Custom | Additional seats are billed monthly and prorated when added mid-cycle. ## Trial Period The Starter tier includes a **30-day free trial**: * Full access to all Starter tier features and limits * No payment method required to start * Automatic downgrade to Free tier if not converted * Convert to paid at any time during the trial Stripe manages the trial period. You'll receive email reminders before your trial ends to add a payment method and continue your subscription. The Pro tier does not include a trial period. You can start with the Starter tier trial and upgrade to Pro at any time. ## Billing Cycle * **Monthly subscriptions** are billed on the same day each month * **Annual subscriptions** are billed once per year on your subscription anniversary * **Consumable allowances** reset on your billing cycle anniversary date * **Upgrades** take effect immediately with prorated charges * **Downgrades** take effect at the end of your current billing period ## Managing Your Billing You can manage all billing settings from your account dashboard: * View current usage and remaining allowances * Purchase credits * Add or remove seats * Upgrade or downgrade your subscription * Update payment methods * Download invoices Compare tier features and limits Learn how limits are enforced # Billing profile Source: https://docs.bizzyco.ai/admin-guide/billing/profile Edit the billing contact, billing address, and tax ID stored on your Bizzy account New Keep the contact, address, and tax details that appear on your invoices and receipts up to date — all in one place inside Bizzy. ## Prerequisites * You must be an **Owner** or **Admin** to view or change the billing profile ## Open the page 1. Navigate to **Settings > Account > Billing** 2. Click **Billing profile** in the page header You land at `/settings/account/billing/profile`. The form is pre-populated with your account's current values. ## What you can edit | Section | Fields | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Billing contact** | **Billing email** (required) — where billing notifications and receipts are sent — and an optional **Company name**. | | **Billing address** | Address line 1, address line 2, city, state/province, postal code, and country. **Country** is chosen from a list of ISO 3166-1 alpha-2 countries. | | **Tax** | A **Tax ID type** chosen from a list (for example United States — EIN, European Union — VAT, United Kingdom — VAT) and the **Tax ID** value itself. When you enter a Tax ID value, you must also select its type so it can be applied to your invoices. | ## Save your changes Click **Save changes**. Bizzy validates the form and: * Surfaces inline errors beneath any field that needs attention: * The billing email is required and must be a valid email address. * A country is required once you start filling in the billing address, and is chosen from the ISO 3166-1 alpha-2 list. The postal code is checked against the selected country's format for the United States, Canada, and the United Kingdom (other countries are accepted as-is). * A Tax ID requires a type, and must be 50 characters or fewer with no leading or trailing spaces. * On success, saves your details and shows a confirmation toast. The form reflects the saved values. Your billing details are also written through to your payment provider so the email, name, address, and tax ID on your invoices and receipts stay in sync. If that sync can't be completed, the save is rolled back and an inline error asks you to try again — so your Bizzy account and your invoices never drift out of step. ## Related Manage the cards and bank accounts on file View, download, and pay invoices in-app # Subscription Tiers Source: https://docs.bizzyco.ai/admin-guide/billing/tiers Compare Bizzy subscription tiers and choose the right tier for your organization Bizzy offers four subscription tiers designed to scale with your business needs. Each tier provides different resource limits, consumable allowances, and feature access. ## Tier Overview | Tier | Price | Billing Options | Trial | | -------------- | ----------- | ----------------- | ---------- | | **Free** | \$0/month | Monthly only | None | | **Starter** | \$25/month | Monthly or Annual | 30 days | | **Pro** | \$100/month | Monthly or Annual | None | | **Enterprise** | Custom | Custom | Negotiated | **Annual billing discount:** Save 2 months free when you choose annual billing. Starter annual is $250/year and Pro annual is $1,000/year. ## Resource Limits Resource limits determine how many of each resource type you can create within your account. | Resource | Free | Starter | Pro | Enterprise | | -------------------- | ------------- | -------------- | -------------- | ---------- | | **Organizations** | 1 | 3 | 10 | Unlimited | | **Seats (included)** | 3 | 10 | 25 | Custom | | **Additional Seats** | Not available | \$5/seat/month | \$8/seat/month | Custom | | **MCP Servers** | 2 | 5 | 20 | Unlimited | | **Agents** | 3 | 10 | 50 | Unlimited | | **Automations** | 5 | 25 | 100 | Unlimited | Resource limits are **hard limits**. You cannot create resources beyond your tier limit. To add more resources, upgrade to a higher tier. ## AI Model Access Different tiers provide access to different AI models for agents and automations. | Model | Free | Starter | Pro | Enterprise | | ------------------------ | ---- | ------- | --- | ---------- | | **GPT-3.5 Turbo** | Yes | Yes | Yes | Yes | | **GPT-4o-mini** | - | Yes | Yes | Yes | | **GPT-4** | - | - | Yes | Yes | | **GPT-4 Turbo** | - | - | Yes | Yes | | **Claude 3 Haiku** | Yes | Yes | Yes | Yes | | **Claude 3.5 Sonnet** | - | Yes | Yes | Yes | | **Claude 3 Opus** | - | - | Yes | Yes | | **Claude 3.5 Sonnet V2** | - | - | Yes | Yes | | **Custom Models** | - | - | - | Yes | ## Feature Access Certain features are only available on higher tiers. | Feature | Free | Starter | Pro | Enterprise | | ----------------------------- | ---- | ------- | --- | ---------- | | **Email Integration** | Yes | Yes | Yes | Yes | | **API Access** | Yes | Yes | Yes | Yes | | **Automations** | Yes | Yes | Yes | Yes | | **SMS Marketing Campaigns** | - | - | Yes | Yes | | **Priority Support** | - | - | Yes | Yes | | **SSO (SAML/OAuth)** | - | - | - | Yes | | **Custom Branding** | - | - | - | Yes | | **SLA Guarantee** | - | - | - | Yes | | **Dedicated Account Manager** | - | - | - | Yes | ## API Rate Limits | Tier | Requests per Minute | | -------------- | ------------------- | | **Free** | 10 | | **Starter** | 30 | | **Pro** | 100 | | **Enterprise** | Custom | ## Choosing the Right Tier The Free tier is perfect for individuals or small teams who want to explore Bizzy's capabilities. You get access to basic AI models and can create a limited number of agents and automations. **Best for:** Personal use, evaluation, small side projects The Starter tier is designed for small businesses or teams who need more capacity and better AI models. The 30-day trial lets you experience the full tier before committing. **Best for:** Small businesses, startups, growing teams The Pro tier provides significantly higher limits and access to the most capable AI models. SMS marketing and priority support make it ideal for businesses with demanding requirements. **Best for:** Established businesses, agencies, teams with heavy usage The Enterprise tier offers unlimited resources, custom pricing, and dedicated support. SSO, custom branding, and SLA guarantees meet the needs of large organizations. **Best for:** Large organizations, enterprises with custom requirements ## Upgrading Your Tier You can upgrade your subscription at any time from the billing settings in your dashboard. When you upgrade: * New limits take effect immediately * You're charged a prorated amount for the remainder of the billing period * All your existing data and configurations are preserved View detailed pricing and consumable limits Learn how limits are enforced # Upgrade your plan Source: https://docs.bizzyco.ai/admin-guide/billing/upgrade Compare tiers and switch your subscription from the upgrade page The upgrade page at **`/billing/upgrade`** is the conversion entry point for changing plans. Every paid plan transition — Free → Starter, Starter → Pro, switching billing intervals — starts here. ## Prerequisites * You must be an **Owner** or **Admin** to change the subscription * Open the page from anywhere in the app at `/billing/upgrade`, or from **Settings > Account > Billing > Upgrade plan** ## What the page shows The upgrade page is a full-screen, no-sidebar layout designed to make the choice clear: * **Trial banner** at the top if your account is currently trialing — shows trial end date and a reminder to add a payment method before it ends * **Tier cards** for Free, Starter, Pro, and Enterprise with prices, included resource limits, and key features * **Billing-interval toggle** for Monthly vs. Annual (annual saves about 17%, equivalent to two months free) * **Plan comparison** table for a side-by-side view of features and limits * **FAQ** covering proration, cancellation, and downgrade behavior The card matching your **recommended next tier** is highlighted: | Current tier | Recommended next | | ------------ | -------------------------------- | | Free | Starter | | Starter | Pro | | Pro | Enterprise | | Enterprise | None — contact sales for changes | ## Choose a plan Click the **Upgrade** (or **Switch to**) button on a tier card. Where you go next depends on your current state: | Current state | Where the button takes you | | --------------------------- | ----------------------------------------------------------------------------------------------------- | | Free | Stripe Checkout — enter payment details and confirm | | Trialing | Stripe Customer Portal (subscription confirm) — review proration and confirm | | Paid (downgrade or upgrade) | Stripe Customer Portal (subscription confirm) — review proration and confirm | | Enterprise | Redirected back to **Settings > Account > Billing** — Enterprise plans require sales-assisted changes | After payment or confirmation, Stripe sends you back to Bizzy; the new tier takes effect immediately. ### Trials The Starter plan includes a **30-day free trial** — no payment method required up front. Pro and Enterprise plans do not include trials; you can start with the Starter trial and upgrade to Pro at any point during or after it. When your Starter trial ends: * If you've added a payment method, billing begins automatically * If you haven't, the account drops back to Free and any over-Free-tier objects become read-only (see [Limits](/admin-guide/billing/limits)) ## Frequently asked questions Yes. Stripe credits the unused portion of your current period and charges the prorated amount for the new tier on the same invoice. You see the exact line items in the portal before confirming. Yes — pick a lower tier on the upgrade page. Bizzy runs a [pre-validation check](/admin-guide/billing/portal#downgrade-pre-validation) first; if your current usage exceeds the target tier's limits, you'll see a list of what to reduce before the downgrade can proceed. Yes. Cancel from the [Stripe Customer Portal](/admin-guide/billing/portal). Your plan stays active until the end of the current billing period, then drops back to Free. Credits roll over and don't expire. Current-period overage usage continues to bill at your prior tier's overage rate; the new tier's rate applies starting next cycle. ## Next steps Compare tier features in detail Tax info, subscription history, and confirmations # Usage and metrics Source: https://docs.bizzyco.ai/admin-guide/billing/usage Track resource counts, monthly consumable usage, and overage costs from the billing dashboard The usage dashboard shows your account's consumption against its plan in real time. Bizzy tracks two kinds of usage: **account objects** (countable things you create and delete) and **consumables** (monthly allowances that reset on your billing anniversary). To open the dashboard: 1. Navigate to **Settings > Account > Billing** 2. Scroll to the **Usage** section ## Account objects Account objects have hard limits per tier. When you reach a limit you can't create more of that object until you delete one or upgrade your plan. | Object | Free | Starter | Pro | Enterprise | | ------------------------ | ---: | ------: | --: | ---------: | | **Seats** (team members) | 1 | 3 | 10 | Unlimited | | **Businesses** | 1 | 3 | 10 | Unlimited | | **Agents** | 3 | 10 | 50 | Unlimited | | **MCP Servers** | 2 | 5 | 20 | Unlimited | | **Automations** | 5 | 25 | 100 | Unlimited | Each object's card on the dashboard shows your current count, the included plan limit, and a progress bar. Additional seats can be purchased on Starter, Pro, and Enterprise plans without changing tier. See [Pricing](/admin-guide/billing/pricing) for per-seat pricing. ## Consumables Consumables are metered usage that accrues during the billing period and resets on your billing-cycle anniversary date. | Consumable | Free | Starter | Pro | Enterprise | | ----------------- | ------: | --------: | ---------: | ---------: | | **LLM tokens** | 100,000 | 1,000,000 | 10,000,000 | Unlimited | | **API calls** | 1,000 | 10,000 | 100,000 | Unlimited | | **MCP calls** | 500 | 5,000 | 50,000 | Unlimited | | **Storage** | 100 MB | 1 GB | 10 GB | Unlimited | | **Email sends** | 100 | 1,000 | 10,000 | Unlimited | | **SMS** | 50 | 500 | 5,000 | Unlimited | | **Voice minutes** | 30 | 300 | 3,000 | Unlimited | Each consumable card shows: * The included allocation * Current period usage and a progress bar * The per-tier overage rate * Live overage cost so far this period (if any) ### Allocation header colors The progress bar color tracks your usage percentage: | Usage | Color | What it means | | ------------- | ------ | ------------------------------------------ | | Below 80% | Green | Healthy — well within plan | | 80% – 99% | Yellow | Approaching the included allocation | | 100% or above | Red | Allocation exhausted — overage rates apply | You also receive `usage_warning` notifications at 90% and `usage_limit_reached` at 100%. See [Notifications](/admin-guide/notifications) to configure delivery channels. ## Overage rates Once a consumable passes 100% of its allocation, additional usage bills against your [credit balance](/admin-guide/billing/credits) at the per-tier rate below. | Consumable | Unit | Free | Starter | Pro | Enterprise | | ----------------- | ---------- | -----: | ------: | ------: | ---------: | | **LLM tokens** | per 10,000 | \$0.50 | \$0.40 | \$0.30 | Custom | | **API calls** | per 100 | \$0.03 | \$0.02 | \$0.01 | Custom | | **MCP calls** | per 100 | \$0.03 | \$0.02 | \$0.01 | Custom | | **Storage** | per 1 GB | \$0.25 | \$0.15 | \$0.10 | Custom | | **Email sends** | per 100 | \$0.15 | \$0.10 | \$0.05 | Custom | | **SMS** | per 10 | \$0.15 | \$0.10 | \$0.075 | Custom | | **Voice minutes** | per 10 | \$0.30 | \$0.20 | \$0.15 | Custom | All tiers — including Free — can purchase credits and pay overages. Enterprise overage pricing is set in your contract. Overage cost is rounded up by unit. For example, sending 110 emails when 100 are included on the Starter plan ($0.10 per 100) bills as one full overage unit = $0.10, not \$0.01. ## How usage is counted | Object or consumable | Counted at | | ------------------------------------------------ | ------------------------------------------------------------------------ | | **Seats** | Every accepted invitation; revoked when a member is removed | | **Businesses, Agents, MCP Servers, Automations** | When the object is created (counter restored on delete) | | **LLM tokens** | Every token billed by the upstream model — input plus output | | **API calls** | Every authenticated request to the public REST API | | **MCP calls** | Every authenticated tool invocation against the MCP server | | **Storage** | Sum of bytes across all uploaded files (recomputed on upload and delete) | | **Email sends** | Every outbound email; received emails are not counted | | **SMS** | Every outbound SMS segment; inbound messages are not counted | | **Voice minutes** | Live + recorded call minutes per leg, rounded up to the nearest minute | ## Next steps Top up your balance or enable auto-recharge What happens at warning thresholds and after a downgrade # Admin Guide Source: https://docs.bizzyco.ai/admin-guide/index Administer your Bizzy organization, billing, security, and integrations The Admin Guide covers everything you do as an account or organization admin: shape your team, run billing, secure access, and connect external services. ## Where to start Set up your organization, invite team members, and define roles Subscriptions, credits, usage tracking, and the Stripe portal Passkeys, two-factor authentication, and API keys Connect Stripe and other external services ## Account-wide settings Configure in-app and email alerts for billing, usage, and integrations Name, avatar, timezone, language, and password ## Looking for something else? * End-user features (inbox, contacts, agents, automations) live in the [User Guide](/user-guide) * Programmatic access to Bizzy is in the [API Reference](/api-reference/introduction) * AI agent integration is covered in the [MCP Server](/mcp-server/introduction) docs # Integrations Source: https://docs.bizzyco.ai/admin-guide/integrations/index Connect external services to Bizzy Integrations let Bizzy exchange data with the systems you already use. Each integration is configured at the right scope — payments at the Business level, mailbox connections at the email-address level, and so on. ## Available integrations Sync customers and transactions between a Business and a Stripe account Connect Gmail or Microsoft 365 mailboxes for inbound and outbound email Verify or register domains used for sending email Provision Telnyx numbers for SMS and voice Connecting a service usually requires the **Owner** or **Admin** role. Check each integration's page for specific requirements. # Stripe Connect Source: https://docs.bizzyco.ai/admin-guide/integrations/stripe Connect a Stripe account to a Business and sync customers and transactions into Bizzy Stripe Connect links a Stripe account to a Business in Bizzy so customers and transactions sync between the two systems. You configure it from your organization's settings — each Business can connect to one Stripe account. ## Prerequisites * You must be an **Owner** or **Admin** to connect, disconnect, or change sync settings * The Business you want to connect must already exist in Bizzy (see [Business profile](/user-guide/businesses)) * You need an existing Stripe account with permission to authorize OAuth connections ## Connect Stripe To connect a Business to Stripe: 1. Navigate to **Settings > Integrations > Stripe** (at `/{orgSlug}/settings/integrations/stripe`) 2. Click **Connect Stripe** 3. You're redirected to Stripe's authorization page — sign in if needed and approve the connection 4. Stripe sends you back to the integration page with a success message When the connection completes, Bizzy automatically: * Sets the sync mode to **One-Way** (Stripe → Bizzy) * Triggers an initial full inbound sync of customers and transactions The connected account's name, email, and connection date appear at the top of the page once linked. The first connection's initial sync runs in the background. Larger Stripe accounts may take several minutes; the page shows the most recent full-sync timestamp when complete. ## Sync modes Stripe Connect supports three sync modes. You can switch between them at any time without disconnecting. | Mode | Direction | What syncs | When | | ----------- | --------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | **Off** | None | Nothing — connection stays linked but no data moves | N/A | | **One-Way** | Stripe → Bizzy | Customers, charges, invoices from Stripe | Real-time via webhooks; full sync on enable from Off (if >7 days stale) or via **Sync Now** | | **Two-Way** | Both directions | Inbound from Stripe (as One-Way) plus outbound: customer name, email, and phone edits in Bizzy push to Stripe | Inbound real-time; outbound triggered by edits in Bizzy | To change modes: 1. On the Stripe integration page, find the **Sync mode** card 2. Select the new mode 3. Confirm in the dialog that explains what will happen Switching to **Two-Way** does not bulk-push existing Bizzy customers to Stripe. Only future edits sync outbound. Inbound sync from Stripe remains complete in both One-Way and Two-Way. ### Manual full sync Use **Sync Now** on the integration page to re-run a full inbound sync without changing modes. This is useful after bulk changes in Stripe (e.g., importing customers there) or to recover from a long offline period. When sync mode was Off for more than 7 days and you re-enable it, Bizzy runs a full inbound sync automatically to catch up. ## Customer mapping Bizzy tries to link Stripe customers to existing Bizzy customers automatically by **normalized email address** during initial sync. The matching rules: | Result | Behavior | | ---------------------------------------- | -------------------------------------------------------------- | | Exactly one Bizzy customer matches | Auto-linked | | Multiple Bizzy customers share the email | Marked **ambiguous** — requires manual resolution | | No Bizzy customer matches | Left unlinked — a new customer is created on first transaction | ### Manage mappings Click **Manage Customer Mapping** on the Stripe integration page (or visit `/{orgSlug}/settings/integrations/stripe/customer-mapping`) to review and edit links. The customer-mapping table shows each Stripe customer alongside its current link status. Filter by **All**, **Unlinked**, **Ambiguous**, or **Linked** to focus on what needs attention. For each row you can: * **Link** — Open the customer picker, search Bizzy customers by name or email, and link manually * **Unlink** — Remove the existing link without deleting either customer * **Auto-link by email** — Bulk action at the top of the page; runs the same email-matching rule against all unlinked and ambiguous customers visible on the current page and reports a summary Pages of Stripe customers are pulled directly from Stripe's API with cursor-based pagination. Run the auto-link bulk action page-by-page if you have a large backlog. ## Sync errors When inbound or outbound sync fails for a specific customer or transaction, Bizzy records the error and surfaces it in a **Sync errors** card on the main integration page. Each error row shows: * The entity that failed * The error message * How many times it has been retried * The timestamp of the last attempt For each error you can click **Retry** to re-run the sync for that single entity. On success, the error row is removed; on failure, the attempt count increments. The **Clear all** button at the top of the card removes all error rows but **does not retry them**. Use it to acknowledge errors you've decided to ignore. ## Disconnecting To disconnect Stripe from a Business: 1. On the Stripe integration page, click **Disconnect Stripe** 2. Confirm in the dialog Disconnecting: * Stops all future inbound and outbound sync * Preserves all customers and transactions already imported into Bizzy * Leaves the Business in a clean state — you can connect a different Stripe account afterward ### Connection revoked from Stripe If you (or another Stripe admin) revoke Bizzy's access from the Stripe Dashboard directly, Bizzy detects the revocation the next time the integration page loads and shows a banner explaining the connection is no longer valid. Click the **Disconnect** button in the banner to clean up the broken connection record, then reconnect when ready. ## Limitations * **One Business per Stripe account.** Each Business connects to a single Stripe account; Stripe accounts cannot be shared across multiple Businesses * **Two-Way is forward-only.** Switching to Two-Way pushes future Bizzy edits to Stripe but does not back-fill historical edits * **Ambiguous matches require human review.** Auto-link skips any Stripe customer whose email matches multiple Bizzy customers * **Stripe rate limits.** Initial sync respects Stripe's per-account rate limits and throttles between pages, so very large accounts take longer than a single API page would suggest ## Next steps Work with synced customers in Bizzy Configure the Business that owns the Stripe connection # Notifications Source: https://docs.bizzyco.ai/admin-guide/notifications Receive in-app and email alerts for billing, usage, integrations, and system events Bizzy sends notifications about events that need your attention — billing failures, usage thresholds, lost integration connections, credit balance changes, and more. You receive each notification in the in-app bell and (optionally) by email; preferences are configurable per type and per channel. ## In-app bell The bell icon in the app header shows your unread count. Click it to open a panel with: * The most recent notifications, newest first, each with a relative timestamp ("2 hours ago", or absolute date for older items) * A blue dot next to unread items * A **Clear all** button at the top Clicking any notification marks it read immediately. Real-time updates are pushed over a WebSocket connection to the NotificationHub Durable Object — when that connection drops, the panel falls back to polling so you don't miss anything. ## Notification settings To change which notifications you receive and where: 1. Navigate to **Settings > User > Notifications** 2. Toggle individual notification types on or off per channel 3. Use **Unsubscribe from all emails** at the top to silence non-critical email globally — critical account-related messages (payment failures, security alerts) still send Settings are per-user; each team member configures their own. ### Channels | Channel | Status | | ---------------- | ------------------------------------------------------ | | **In-app (Web)** | Live | | **Email** | Live | | **SMS** | Defined in the data model — not yet wired for delivery | | **Mobile push** | Defined in the data model — not yet wired for delivery | The notification settings page only exposes the live channels (Web and Email). SMS and mobile push settings will appear when their delivery is enabled. ## Notification types Notifications are grouped by category in the settings UI. The full set of types currently emitted: ### Domains | Type | Triggered when | | ------------------------------- | -------------------------------------------------- | | `domain_expiration_warning` | A registered domain is approaching expiration | | `domain_renewal_success` | Auto-renewal completed successfully | | `domain_renewal_failed` | A renewal attempt failed (non-payment reason) | | `domain_renewal_payment_failed` | Renewal failed because the payment method declined | | `domain_registration_succeeded` | A new domain registration completed | | `domain_registration_failed` | A new registration could not complete | ### Email accounts | Type | Triggered when | | ------------------------------- | --------------------------------------------------------------------------- | | `email_address_connection_lost` | A connected email account stopped syncing (token revoked, password changed) | | `email_address_setup_failed` | A new email account couldn't finish setup | | `gmail_connection_lost` | A Google Workspace / Gmail account specifically lost its OAuth grant | ### Email sending (Resend) | Type | Triggered when | | ----------------------------- | ------------------------------------------ | | `resend_setup_initiated` | Resend domain setup has been started | | `resend_verification_success` | A sending domain finished DNS verification | | `resend_verification_failed` | A sending domain failed DNS verification | ### Phone and voice | Type | Triggered when | | ------------------------------ | ---------------------------------------------- | | `phone_number_connection_lost` | A connected number went offline at the carrier | | `phone_number_setup_failed` | A new phone number couldn't finish setup | | `voice_call_error` | A live voice call ended with an error | ### Usage | Type | Triggered when | | ---------------------- | ----------------------------------------------------------------------- | | `usage_warning` | A consumable reaches 90% of its monthly allowance | | `usage_limit_reached` | A consumable reaches 100% of its allowance | | `usage_limit_exceeded` | A consumable goes beyond 100% (overages now apply or service is paused) | ### Billing and payments | Type | Triggered when | | --------------------------- | -------------------------------------------------------------- | | `payment_failure_immediate` | A subscription or top-up payment was declined | | `payment_failure_24h` | 24-hour follow-up if a failed payment hasn't been resolved | | `payment_failure_48h_final` | Final notice — service may be paused if not resolved | | `trial_started` | A new trial has started for your account | | `trial_will_end` | Your trial ends in the next few days | | `trial_ended` | Your trial has ended (converted to paid or downgraded to Free) | ### Credits | Type | Triggered when | | -------------------------------- | ------------------------------------------------------------------------ | | `credit_purchase_success` | A one-time credit purchase completed | | `credit_purchase_failed` | A credit purchase attempt failed | | `credit_balance_low` | Your credit balance dropped below the auto-recharge or default threshold | | `credit_balance_depleted` | Your credit balance reached zero | | `credit_auto_recharge_triggered` | An automatic credit top-up fired | ### System | Type | Triggered when | | -------------- | -------------------------------------------------------------- | | `system_error` | An internal error affected your account and warrants attention | ## Critical notifications A subset of notifications always send by email regardless of your preferences: * Payment failures (`payment_failure_*`) * Credit purchase failures (`credit_purchase_failed`) * Domain renewal payment failures (`domain_renewal_payment_failed`) * System errors (`system_error`) These exist to make sure you can recover from situations that can interrupt service or lose data. ## Next steps Configure auto-recharge to head off `credit_balance_low` alerts Track consumption that drives `usage_*` notifications # Organization Source: https://docs.bizzyco.ai/admin-guide/organization/index Set up your organization, invite team members, and configure roles An **organization** is the workspace your team shares — contacts, agents, automations, businesses, and integrations all live inside it. One Bizzy account can own multiple organizations; team members and billing are tracked at the account level above. ## In this section Create an organization and configure its general and notification settings Invite, remove, and manage seats for your team Owner, Admin, and User capability matrix # Roles & Permissions Source: https://docs.bizzyco.ai/admin-guide/organization/permissions Understand how access control works in Bizzy Bizzy uses a role-based access control system to manage what team members can see and do within your organization. This guide explains the permission model and how to configure access for your team. ## Role Types Every organization member has one of three roles: | Role | Description | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Owner** | Full access to all organization resources and settings. Can manage billing, API keys, and delete the organization. | | **Admin** | Full access to business data. Can invite members and manage integrations. Can view billing and subscription data but cannot modify the subscription or manage API keys. | | **User** | Read-only access to business data (contacts, messages, automations). Full access to their own user resources (files, preferences). Cannot access organization settings. | Each organization must have at least one Owner. Ownership can be transferred but not removed entirely. ## Permission Model Bizzy's permission system is built on three core concepts: ### 1. Actions Every permission check evaluates one of three actions: | Action | HTTP Methods | Description | | -------- | ---------------- | -------------------------- | | `read` | GET | View resources | | `write` | POST, PUT, PATCH | Create or modify resources | | `delete` | DELETE | Remove resources | ### 2. Resources Resources are organized hierarchically using dot notation. For example: ``` contacts contacts.emails contacts.phones contacts.tags ``` ### 3. Inheritance Permissions flow from parent to child resources. If you grant `read` access to `contacts`, that permission automatically applies to `contacts.emails`, `contacts.phones`, and all other child resources—unless explicitly overridden. ## Role Permissions ### Owner Permissions Owners have unrestricted access to all resources: | Resource Category | Read | Write | Delete | | ---------------------- | ---- | ----- | ------ | | Organization settings | Yes | Yes | Yes | | Members & invites | Yes | Yes | Yes | | API keys | Yes | Yes | Yes | | Billing & subscription | Yes | Yes | Yes | | All business data | Yes | Yes | Yes | ### Admin Permissions Admins have full data access with limited administrative capabilities: | Resource Category | Read | Write | Delete | | ---------------------- | ---- | ----- | ------ | | Organization settings | Yes | No | No | | Members | Yes | No | No | | Invites | Yes | Yes | Yes | | Connections | Yes | No | No | | Workflows | Yes | Yes | Yes | | API keys | No | No | No | | Billing & subscription | Yes | No | No | | Contacts & customers | Yes | Yes | Yes | | Messages | Yes | Yes | Yes | | Automations | Yes | Yes | Yes | | Files & folders | Yes | Yes | Yes | ### User Permissions Users have read-only access to organization data with full control over their own resources: | Resource Category | Read | Write | Delete | | ---------------------------------------- | ---- | ----- | ------ | | Organization settings | No | No | No | | Members & invites | No | No | No | | API keys | No | No | No | | Contacts, customers, businesses, domains | Yes | No | No | | Messages, automations, email templates | Yes | No | No | | Tasks | Yes | No | No | | RAG resources & embeddings | Yes | No | No | | Files & folders | Yes | Yes | No | | Own user profile | Yes | Yes | Yes | | Own notifications | Yes | Yes | Yes | ## Resource Categories The permission system covers these top-level resources: ### Contact and customer data * `contacts` — Contact records (children: `emails`, `phones`, `addresses`) * `customers` — Customer relationships (children: `transactions`) * `businesses` — Business entities (children: `offerings`, `onlinePresences`, `physicalPresences`, `profiles`) * `domains` — Verified and registered domains (children: `domainContacts`, `domainRegistrations`) ### Communication * `messages` — Conversation threads (children: `attachments`, `contacts`) * `incomingMessages` — Inbound message records (children: `attachments`, `contacts`) * `outgoingMessages` — Outbound message records (children: `attachments`, `contacts`) * `emailTemplates` — Reusable email templates ### Tasks and automations * `tasks` — Tasks (children: `assignees`, `activity`) * `automations` — Plain-English automations ### Files and knowledge * `files`, `folders` — Uploaded files and the folder tree * `resources`, `embeddings` — RAG-indexed assets used by agents ### Organization administration * `organization` — Org-level settings, with children: * `members` — Team membership * `invites` — Pending invitations * `connections` — Integration connections (Stripe, etc.) * `subscriptions` — Billing and subscription * `workflows` — Internal workflow registry * `apiKeys` — Owner-only API key management ### User-level resources * `userNotifications` — Personal notification preferences and history * `userProfiles` — Personal profile (name, avatar, timezone, language) ## API Key Permissions API keys have their own independent permission system — they do **not** inherit the permissions of the user that created them. When you create a key, you grant it specific resource access and restrict it to specific actions. This means a User-role team member can still create an API key with broader permissions than they themselves have, provided their role allows key creation in the first place (currently Owner-only). See [API Key Management](/admin-guide/security/api-keys) for details. ## Best Practices ### Principle of Least Privilege Assign the minimum role needed for each team member: * Use **User** role for team members who only need to view data * Use **Admin** role for managers who need to edit data and invite members * Reserve **Owner** role for account administrators ### Regular Access Reviews Periodically review your organization's members: * Remove inactive members promptly * Verify role assignments match current responsibilities * Check for any unused API keys ### Separation of Duties For sensitive operations, consider: * Limiting Owner role to 1-2 trusted administrators * Using separate API keys for different integrations * Enabling audit logging to track changes ## Next Steps Learn how to invite and manage team members Create API keys with custom permissions # Organization Setup Source: https://docs.bizzyco.ai/admin-guide/organization/setup Create and configure your Bizzy organization An organization is the primary workspace in Bizzy where your team collaborates on business communications. All data—contacts, messages, automations—is scoped to your organization. ## Creating an Organization When you sign up for Bizzy, you automatically create your first organization. Each organization includes: * **Name**: A display name for your organization (e.g., "Acme Corp") * **Slug**: A unique identifier used in URLs and API calls (auto-generated) * **Owner**: The user who created the organization (you) Your account tier determines how many organizations you can create. Most plans support a single organization, while enterprise tiers allow multiple organizations for managing separate business units. ## Organization Settings Access your organization settings from **Settings > Organization** in the dashboard. ### General Settings | Setting | Description | | ----------------- | ---------------------------------------------------------------------------- | | Organization Name | Display name shown throughout the app | | Slug | Unique identifier used in URLs and API references (read-only after creation) | | Time Zone | Default time zone for scheduling and reports | ### Notification Settings Configure which team members receive notifications for different event types. Notifications can be customized by role: * **Owner notifications**: Critical alerts, billing, security events * **Admin notifications**: Team changes, integration status, system alerts * **User notifications**: Assignment updates, task reminders ## Account Limits Your organization operates within your account's resource limits: | Resource | Description | | ------------- | ------------------------------------- | | Organizations | Number of organizations per account | | Seats | Maximum team members per organization | | Connections | Email provider connections | | API Keys | Active API keys | Contact support to upgrade your account limits or discuss enterprise options for multi-organization setups. ## Multi-Organization Support Enterprise accounts can create multiple organizations to: * Separate business units or brands * Isolate client data for agencies * Maintain development and production environments Each organization has its own: * Team members and roles * Email connections and integrations * Contacts, customers, and business data * API keys Users can belong to multiple organizations and switch between them from the account menu. ## Next Steps Invite team members to your organization Configure access control for your team # User Management Source: https://docs.bizzyco.ai/admin-guide/organization/users Invite, manage, and remove team members in your organization Manage who has access to your Bizzy organization by inviting team members, assigning roles, and controlling seat allocation. ## Prerequisites * You must be an **Owner** or **Admin** to manage users * Available seats in your organization ## Inviting Team Members To invite a new team member: 1. Navigate to **Settings > Organization > Members** 2. Click **Invite Member** 3. Enter the invitee's email address 4. Select a role: **Admin** or **User** (Owners cannot be invited—ownership must be transferred) 5. Click **Send Invite** The invitee receives an email with a unique invitation link. They must create a Bizzy account (or sign in to an existing one) to join your organization. Invitations expire after 7 days by default. You can resend or revoke invitations from the pending invites list. ### Invitation Statuses | Status | Description | | -------- | -------------------------------- | | Pending | Invite sent, awaiting acceptance | | Accepted | User has joined the organization | | Expired | Invite link has expired (7 days) | | Revoked | Invite was manually cancelled | ## Managing Team Members ### Viewing Members The Members page displays all organization members with: * Name and email * Role (Owner, Admin, User) * Join date * Status ### Changing Roles Only Owners can change member roles: 1. Find the member in the list 2. Click the role dropdown 3. Select the new role You cannot demote yourself. An organization must always have at least one Owner. ### Role Capabilities | Action | Owner | Admin | User | | --------------------------- | ----- | ----- | --------- | | View organization data | Yes | Yes | Yes | | Manage contacts & customers | Yes | Yes | Read-only | | Send messages | Yes | Yes | No | | Invite members | Yes | Yes | No | | Remove members | Yes | No | No | | Change member roles | Yes | No | No | | Manage API keys | Yes | No | No | | Billing & subscription | Yes | No | No | | Delete organization | Yes | No | No | See [Roles & Permissions](/admin-guide/organization/permissions) for detailed permission information. ## Removing Members Only Owners can remove members from the organization. To remove a member: 1. Navigate to **Settings > Organization > Members** 2. Find the member to remove 3. Click the **Remove** button (trash icon) 4. Confirm the removal Removing a member revokes their access immediately. Their data and activity history remain in the organization for audit purposes. ### What Happens When a Member is Removed * Immediate loss of organization access * Active sessions are terminated * Personal API keys are revoked * Email connections remain active (organization-owned) * Assigned tasks may need reassignment ## Seat Management Your organization has a maximum number of seats based on your subscription plan. ### Checking Seat Usage View your current seat allocation in **Settings > Organization > Members**: * **Used seats**: Active members * **Available seats**: Remaining capacity * **Pending invites**: Reserved but not yet accepted ### Seat Limits | Scenario | Behavior | | ------------------------ | --------------------------------------- | | At seat limit | Cannot send new invites | | Invite accepted at limit | Invite fails, user notified | | Member removed | Seat freed immediately | | Pending invite | Reserves a seat until expiry/revocation | To add more seats, upgrade your subscription plan in **Settings > Billing**. ## Transferring Ownership Organization ownership can be transferred to another Admin: 1. Navigate to **Settings > Organization > Members** 2. Find the Admin to promote 3. Click **Transfer Ownership** 4. Confirm the transfer After transfer: * The new Owner has full control * You become an Admin * This action cannot be undone without the new Owner's consent ## Next Steps Understand permission scopes for each role Create API keys for programmatic access # API Key Management Source: https://docs.bizzyco.ai/admin-guide/security/api-keys Create and manage API keys for programmatic access to Bizzy API keys allow external applications and scripts to access your Bizzy organization programmatically. This guide covers creating, configuring, and securing your API keys. This guide covers API keys for REST API access. AI agents (Claude, Cursor, Windsurf, etc.) connect through the [MCP server](/mcp-server/introduction), which uses its own authentication flow rather than API keys. ## Prerequisites * You must be an **Owner** to manage API keys * Admins and Users cannot create, view, or revoke API keys ## Creating an API Key To create a new API key: 1. Navigate to **Settings > Security > API Keys** 2. Click **Create API Key** 3. Enter a descriptive name (e.g., "Production CRM Integration") 4. Configure permissions (see below) 5. Optionally set an expiration date 6. Click **Create** The full API key is displayed only once after creation. Copy it immediately and store it securely. You cannot retrieve the full key later. ### API Key Format Bizzy API keys are prefixed with `sk_` followed by a long random secret: ``` sk_a1b2c3... ``` * `sk_` - Indicates a secret key * Followed by a unique random string For security, Bizzy stores only a hash of each key — never the key itself. After creation, the full key is shown once; the dashboard thereafter displays a masked preview (the `sk_` prefix plus the last four characters, e.g. `sk_a1b…c3d4`) so you can identify a key without exposing it. ## Setting Permissions API keys support fine-grained permissions that control which resources the key can access and what actions it can perform. ### Permission Structure Each permission specifies: | Component | Description | Example | | --------- | --------------------------- | ------------------------- | | Resource | What the key can access | `contacts`, `messages` | | Action | What operations are allowed | `read`, `write`, `delete` | ### Common Permission Patterns **Read-Only Access** ```json theme={null} { "contacts": { "read": true, "write": false, "delete": false }, "customers": { "read": true, "write": false, "delete": false } } ``` **Full Contact Management** ```json theme={null} { "contacts": { "read": true, "write": true, "delete": true } } ``` **Messaging Only** ```json theme={null} { "messages": { "read": true, "write": true, "delete": false } } ``` ### Permission Inheritance Permissions cascade to child resources. Granting access to `contacts` automatically includes: * `contacts.emails` * `contacts.phones` * `contacts.addresses` * `contacts.tags` * `contacts.notes` You can override child permissions to restrict access further. ## Key Expiration Set an expiration date to automatically disable API keys after a certain period: | Use Case | Recommended Expiration | | ----------------------- | ------------------------------- | | Temporary integrations | 7-30 days | | Contractor access | Project duration | | Production integrations | 90-365 days | | Internal tools | No expiration (rotate manually) | Expired keys return a `401 Unauthorized` error. Create a new key before the old one expires to avoid service interruption. ## Monitoring Key Usage Track API key activity from the API Keys dashboard: | Metric | Description | | --------- | ------------------------------------------------ | | Key | Masked preview (`sk_…last4`) to identify the key | | Last Used | Timestamp of the most recent API call | | Created | When the key was created | | Expires | Expiration date (if set) | | Status | Active, Expired, or Revoked | Use the "Last Used" timestamp to identify unused keys that should be revoked. ## Revoking Keys To revoke an API key: 1. Navigate to **Settings > Security > API Keys** 2. Find the key to revoke 3. Click **Revoke** 4. Confirm the action Revoked keys cannot be restored. Any application using the revoked key will immediately lose access. ### When to Revoke Revoke API keys immediately when: * A key may have been compromised * An employee with key access leaves the organization * An integration is decommissioned * A key hasn't been used in 90+ days ## Security Best Practices ### Key Storage * **Never** commit API keys to version control * Use environment variables or secret management services * Restrict file permissions on configuration files containing keys ```bash Environment Variable theme={null} export BIZZY_API_KEY="sk_live_abc123..." ``` ```typescript TypeScript theme={null} const apiKey = process.env.BIZZY_API_KEY; ``` ```python Python theme={null} import os api_key = os.environ.get('BIZZY_API_KEY') ``` ### Key Rotation Regularly rotate API keys to limit exposure from potential leaks: 1. Create a new key with the same permissions 2. Update your application to use the new key 3. Verify the new key works in production 4. Revoke the old key Recommended rotation schedule: | Environment | Rotation Frequency | | --------------- | ------------------ | | Production | Every 90 days | | Development | Every 30 days | | After incidents | Immediately | ### Principle of Least Privilege Grant only the permissions each integration needs: * Read-only keys for reporting and analytics * Resource-specific keys for focused integrations * Separate keys for separate applications ### Audit Regularly Review your API keys monthly: * Remove unused keys (no activity in 90+ days) * Verify permissions match current requirements * Check expiration dates and rotate as needed ## Troubleshooting ### Common Errors | Error | Cause | Solution | | ----------------------- | ------------------------ | --------------------------------------- | | `401 Unauthorized` | Invalid or expired key | Check key value and expiration | | `403 Forbidden` | Insufficient permissions | Verify key has required resource/action | | `429 Too Many Requests` | Rate limit exceeded | Implement backoff and retry logic | ### Debugging Permission Issues If your API key returns `403 Forbidden`: 1. Check the error response for the required permission 2. Compare against your key's configured permissions 3. Update the key or create a new one with correct permissions ## Next Steps Learn how to use the Bizzy API Understand API authentication methods # Security Source: https://docs.bizzyco.ai/admin-guide/security/index Configure security settings in Bizzy Manage API keys and other security settings for your Bizzy organization. ## Key Management Bizzy uses **API Keys** for REST API access from backend services, scripts, and integrations. API key management requires the **Owner** role. Create keys for REST API integrations AI agents (Claude, Cursor, Windsurf, etc.) connect through the [MCP server](/mcp-server/introduction), which uses its own authentication flow rather than API keys. ## Security Best Practices * **Principle of least privilege**: Grant only the permissions each key needs * **Separate keys per integration**: Create dedicated keys for each service or agent * **Regular audits**: Review and revoke unused keys monthly * **Secure storage**: Never commit keys to version control; use environment variables # Passkeys Source: https://docs.bizzyco.ai/admin-guide/security/passkeys Sign in with biometrics or a hardware key using WebAuthn passkeys Passkeys let you sign in to Bizzy without a password using your device's biometrics (Touch ID, Face ID, Windows Hello) or a hardware security key. Passkeys are phishing-resistant and don't require remembering or rotating a shared secret. ## Prerequisites * A device or browser that supports WebAuthn (every current major browser does) * A signed-in Bizzy account — passkeys are added to your existing account, not used to create one ## Add a passkey 1. Navigate to **Settings > User > Security** 2. In the **Passkeys** card, click **Add passkey** 3. Your browser prompts you to choose a device — phone biometric, platform authenticator (Touch ID / Windows Hello), or a security key 4. Complete the device prompt The new passkey appears in the list with an auto-generated name (`Passkey #1`, `Passkey #2`, etc.) and the date it was added. Add as many passkeys as you have devices — each one is registered to that specific device. You can register passkeys even if your account uses email-and-password sign-in. Passkeys are an additional sign-in method, not a replacement. ## Rename or delete a passkey In the **Passkeys** card: * Click the **pencil** icon to rename a passkey (max 64 characters) — useful for distinguishing "Work laptop" from "Personal phone" * Click the **trash** icon to delete a passkey, then confirm Deleted passkeys cannot be restored — register a new one if you need access from that device again. ## Sign in with a passkey On the sign-in page: * **Conditional UI (autofill).** If your browser supports it, your saved passkey appears as a sign-in option directly in the email field's autofill menu — pick it, complete the device prompt, and you're in * **Manual button.** Click **Sign in with a passkey** to invoke the device picker without typing your email You can sign in with a passkey from any device that has one registered to your account. ## Limitations * **Last-used timestamp not yet tracked.** The passkey list shows the date a passkey was added but not when it was last used to sign in * **Per-device.** Passkeys are bound to the device that created them and don't sync across browsers unless you use a synced passkey provider (iCloud Keychain, Google Password Manager, 1Password, etc.) ## Next steps Add an extra factor with TOTP and backup codes Programmatic access for external integrations # Two-factor authentication Source: https://docs.bizzyco.ai/admin-guide/security/two-factor Protect your account with TOTP codes and recovery backup codes Two-factor authentication (2FA) requires a one-time code from an authenticator app each time you sign in. Bizzy uses TOTP (time-based one-time passwords), the same standard used by Google Authenticator, 1Password, Authy, and most other authenticator apps. ## Prerequisites * A signed-in Bizzy account with email-and-password sign-in (your password is required to enable 2FA) * An authenticator app installed on your phone or password manager ## Enable two-factor authentication 1. Navigate to **Settings > User > Security** 2. In the **Two-factor authentication** card, click **Enable two-factor authentication** 3. Enter your current password to confirm 4. Scan the displayed QR code with your authenticator app — or enter the secret manually if you can't scan 5. Enter the 6-digit code your app generates to verify the setup 6. Save the **backup codes** displayed on the next screen, then click **Done** Backup codes are shown **only once**. Save them in a password manager or other secure location before clicking Done. You'll need them if you ever lose access to your authenticator app. ### Backup codes Each backup code can be used once in place of a TOTP code. Use them when you don't have your authenticator app handy — for example, after losing or wiping a phone. To generate a fresh set: 1. In the **Two-factor authentication** card, click **Regenerate backup codes** 2. Enter your current password 3. Save the new codes — the previous set is invalidated immediately ## Sign in with two-factor authentication When 2FA is enabled, sign-in requires two steps: 1. Enter your email and password 2. Enter the 6-digit code from your authenticator app (or a one-time backup code) You're prompted on every new session — existing sessions stay valid until they expire normally. ## Disable two-factor authentication 1. Navigate to **Settings > User > Security** 2. In the **Two-factor authentication** card, click **Disable 2FA** 3. Enter your current password to confirm Disabling clears your TOTP secret and all unused backup codes. ## Limitations * **Self-serve only.** 2FA is per-user; Bizzy does not yet support organization-wide 2FA enforcement * **Active sessions list not yet available.** You can't currently view or revoke individual signed-in sessions from the security settings page — clearing browser cookies or changing your password ends all sessions ## Recovering a locked-out account If you've lost access to both your authenticator app and your backup codes, contact support — there is no self-serve path to disable 2FA without one of those factors. ## Next steps Sign in with biometrics or a hardware key Programmatic access for integrations # User profile Source: https://docs.bizzyco.ai/admin-guide/user-profile Manage your name, avatar, timezone, and language preferences Your user profile is per-account, not per-organization — settings here apply everywhere you sign in. Each team member maintains their own profile. ## Where to find it Navigate to **Settings > User > Profile**. ## Editable fields | Field | Notes | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Profile picture** | Upload JPG, PNG, GIF, or WebP up to 10 MB. Drag-and-drop or pick from disk. Used in @-mentions, comments, and the team-members list | | **First name** | Optional, free-form | | **Last name** | Optional, free-form | | **Timezone** | IANA timezone (e.g., `America/Los_Angeles`). Determines display of timestamps across the app. Defaults to `America/Los_Angeles` | | **Language** | UI language. Currently supported: English (en), Spanish (es), French (fr), German (de), Italian (it), Japanese (ja), Korean (ko), Chinese (zh), Portuguese (pt), Russian (ru), Arabic (ar), Hindi (hi). Defaults to `en` | Changes save when you click **Save** at the bottom of the form. Language affects the web UI only. Email content and AI agent output use the locale they were authored in. ## Change your password Password changes live on the security settings page, not the profile page. 1. Navigate to **Settings > User > Security** 2. In the **Password** card, enter your current password 3. Enter and confirm a new password 4. Click **Update password** Password requirements: at least 8 characters with at least one uppercase letter, one lowercase letter, and one number. This option is only visible if your account uses email-and-password sign-in. Accounts that sign in only with a third-party provider (Google, Microsoft) manage credentials at the provider. ## Email verification Your email address is verified when you first sign up: 1. Click the verification link in the email Bizzy sends after signup 2. You're automatically signed in after verification If you didn't receive the email, request a new one from the sign-in page. ## Account deletion Self-serve account deletion isn't currently available — contact support to delete your account and associated data. ## Next steps Configure how you receive alerts Add 2FA to your account # Docs MCP server Source: https://docs.bizzyco.ai/agent-resources/docs-mcp Mintlify-hosted MCP server for these docs. # llms.txt Source: https://docs.bizzyco.ai/agent-resources/llms Index of these docs in the llms.txt format. # llms-full.txt Source: https://docs.bizzyco.ai/agent-resources/llms-full Full body of these docs in the llms.txt format. # MCP server Source: https://docs.bizzyco.ai/agent-resources/mcp Connect AI agents to your Bizzy organization. # Authentication Source: https://docs.bizzyco.ai/api-reference/authentication Learn how to authenticate with the Bizzy API The Bizzy API uses API keys to authenticate requests. You can create and manage API keys from your organization settings in the dashboard. ## Creating an API Key 1. Sign in to the [Bizzy Dashboard](https://www.bizzyco.ai/home) 2. Navigate to **Settings** > **API Keys** 3. Click **Create API Key** 4. Give your key a descriptive name (e.g., "Production Server" or "Development") 5. Select the permission scopes your key needs 6. Click **Create** and copy your key immediately Your API key is only shown once when created. Store it securely - you won't be able to see it again. If you lose your key, you'll need to create a new one. ## Using Your API Key Include your API key in the `Authorization` header of every request using the Bearer token format: ``` Authorization: Bearer your-api-key ``` ```bash cURL theme={null} curl https://api.bizzyco.ai/v1/contacts \ -H "Authorization: Bearer sk_live_abc123..." ``` ```typescript TypeScript theme={null} const response = await fetch('https://api.bizzyco.ai/v1/contacts', { headers: { Authorization: 'Bearer sk_live_abc123...', }, }); const { data } = await response.json(); ``` ```python Python theme={null} import requests response = requests.get( 'https://api.bizzyco.ai/v1/contacts', headers={ 'Authorization': 'Bearer sk_live_abc123...', } ) data = response.json()['data'] ``` ## Permission Scopes API keys are scoped to specific permissions that control what resources they can access. When creating a key, grant only the permissions your integration needs. ### Available Scopes | Resource | Actions | Description | | -------------- | ------------------- | ---------------------------------------- | | `contacts` | read, write, delete | Manage contacts and their details | | `customers` | read, write, delete | Manage customer records | | `businesses` | read, write, delete | Manage business profiles | | `messages` | read, write, delete | Access email, SMS, and voice messages | | `automations` | read, write, delete | Configure automation workflows | | `domains` | read, write, delete | Manage custom domains | | `users` | read, write, delete | Manage user profiles and settings | | `organization` | read, write, delete | Manage organization settings and members | | `api_keys` | read, write, delete | Manage API keys and their permissions | | `resources` | read, write, delete | Access shared resources and analytics | ### Permission Inheritance Permissions follow a hierarchical model. Granting access to a parent resource also grants access to its child resources: * `contacts` includes `contacts.emails`, `contacts.phones`, `contacts.addresses`, `contacts.tags`, `contacts.notes` * `customers` includes `customers.contacts` * `businesses` includes `businesses.details`, `businesses.tags`, `businesses.contacts`, `businesses.addresses` * `messages` includes `messages.email`, `messages.sms`, `messages.voice` * `automations` includes `automations.actions` * `domains` includes `domains.dns`, `domains.verification` * `users` includes `users.profile`, `users.settings` * `organization` includes `organization.settings`, `organization.billing` * `resources` includes `resources.analytics` ### HTTP Methods and Permissions | HTTP Method | Required Permission | | ----------- | ------------------- | | GET | `read` | | POST | `write` | | PUT, PATCH | `write` | | DELETE | `delete` | ## Authentication Errors If authentication fails, you'll receive a `401 Unauthorized` response: ```json theme={null} { "error": { "code": "UNAUTHORIZED", "message": "Invalid or missing API key" } } ``` Common causes: * Missing `Authorization` header * Invalid or revoked API key * Malformed Bearer token (missing "Bearer " prefix) If your key lacks permission for a specific action, you'll receive a `403 Forbidden` response: ```json theme={null} { "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "Missing write permission for contacts", "details": { "required": { "resource": "contacts", "action": "write" }, "hint": "Contact your administrator to request additional permissions" } } } ``` ## Security Best Practices Use environment variables or a secrets manager to store your API keys. Add `.env` files to your `.gitignore`. ```bash theme={null} # .env (never commit this file) BIZZY_API_KEY=sk_live_abc123... ``` ```typescript theme={null} // Use environment variables const apiKey = process.env.BIZZY_API_KEY; ``` Create different API keys for development, staging, and production. This limits the blast radius if a key is compromised. Follow the principle of least privilege. Only grant the specific permissions your integration needs. A read-only dashboard doesn't need write access. Periodically create new API keys and deprecate old ones. This limits the window of exposure if a key is leaked. Review your API key activity in the dashboard regularly. Revoke any keys showing suspicious activity immediately. ## Server-Side Only API keys should only be used in server-side code. Never expose your API key in client-side JavaScript, mobile apps, or any code that runs in the browser. If you need to access the Bizzy API from a client application, implement a backend proxy that handles authentication on behalf of your users. # Get automation execution Source: https://docs.bizzyco.ai/api-reference/automation-executions/get-automation-execution /api-reference/openapi.json get /v1/automations/{id}/executions/{executionId} Get a specific execution for an automation # List automation executions Source: https://docs.bizzyco.ai/api-reference/automation-executions/list-automation-executions /api-reference/openapi.json get /v1/automations/{id}/executions List all executions for a specific automation with pagination # Create automation Source: https://docs.bizzyco.ai/api-reference/automations/create-automation /api-reference/openapi.json post /v1/automations Create a new automation # Delete automation Source: https://docs.bizzyco.ai/api-reference/automations/delete-automation /api-reference/openapi.json delete /v1/automations/{id} Delete an automation (soft delete) # Get automation Source: https://docs.bizzyco.ai/api-reference/automations/get-automation /api-reference/openapi.json get /v1/automations/{id} Get a specific automation by ID # List automations Source: https://docs.bizzyco.ai/api-reference/automations/list-automations /api-reference/openapi.json get /v1/automations List all automations with pagination support # Partially update automation Source: https://docs.bizzyco.ai/api-reference/automations/partially-update-automation /api-reference/openapi.json patch /v1/automations/{id} Partially update an existing automation. Only provided fields will be updated. # Update automation Source: https://docs.bizzyco.ai/api-reference/automations/update-automation /api-reference/openapi.json put /v1/automations/{id} Update an existing automation. Note: This endpoint accepts partial updates (same behavior as PATCH). All fields are optional. # Create business offering Source: https://docs.bizzyco.ai/api-reference/business-offerings/create-business-offering /api-reference/openapi.json post /v1/businesses/{id}/offerings Create a new offering for a business # Delete business offering Source: https://docs.bizzyco.ai/api-reference/business-offerings/delete-business-offering /api-reference/openapi.json delete /v1/businesses/{id}/offerings/{offeringId} Delete an offering from a business # Get business offering Source: https://docs.bizzyco.ai/api-reference/business-offerings/get-business-offering /api-reference/openapi.json get /v1/businesses/{id}/offerings/{offeringId} Get a specific offering for a business # List business offerings Source: https://docs.bizzyco.ai/api-reference/business-offerings/list-business-offerings /api-reference/openapi.json get /v1/businesses/{id}/offerings List all offerings for a specific business with pagination # Update business offering Source: https://docs.bizzyco.ai/api-reference/business-offerings/update-business-offering /api-reference/openapi.json put /v1/businesses/{id}/offerings/{offeringId} Update an existing offering for a business # Create business online presence Source: https://docs.bizzyco.ai/api-reference/business-online-presences/create-business-online-presence /api-reference/openapi.json post /v1/businesses/{id}/online-presences Create a new online presence for a business # Delete business online presence Source: https://docs.bizzyco.ai/api-reference/business-online-presences/delete-business-online-presence /api-reference/openapi.json delete /v1/businesses/{id}/online-presences/{onlinePresenceId} Delete an online presence from a business # Get business online presence Source: https://docs.bizzyco.ai/api-reference/business-online-presences/get-business-online-presence /api-reference/openapi.json get /v1/businesses/{id}/online-presences/{onlinePresenceId} Get a specific online presence for a business # List business online presences Source: https://docs.bizzyco.ai/api-reference/business-online-presences/list-business-online-presences /api-reference/openapi.json get /v1/businesses/{id}/online-presences List all online presences for a specific business with pagination # Update business online presence Source: https://docs.bizzyco.ai/api-reference/business-online-presences/update-business-online-presence /api-reference/openapi.json put /v1/businesses/{id}/online-presences/{onlinePresenceId} Update an existing online presence for a business # Create business physical presence Source: https://docs.bizzyco.ai/api-reference/business-physical-presences/create-business-physical-presence /api-reference/openapi.json post /v1/businesses/{id}/physical-presences Create a new physical presence for a business # Delete business physical presence Source: https://docs.bizzyco.ai/api-reference/business-physical-presences/delete-business-physical-presence /api-reference/openapi.json delete /v1/businesses/{id}/physical-presences/{physicalPresenceId} Delete a physical presence from a business # Get business physical presence Source: https://docs.bizzyco.ai/api-reference/business-physical-presences/get-business-physical-presence /api-reference/openapi.json get /v1/businesses/{id}/physical-presences/{physicalPresenceId} Get a specific physical presence for a business # List business physical presences Source: https://docs.bizzyco.ai/api-reference/business-physical-presences/list-business-physical-presences /api-reference/openapi.json get /v1/businesses/{id}/physical-presences List all physical presences for a specific business with pagination # Update business physical presence Source: https://docs.bizzyco.ai/api-reference/business-physical-presences/update-business-physical-presence /api-reference/openapi.json put /v1/businesses/{id}/physical-presences/{physicalPresenceId} Update an existing physical presence for a business # Get business profile Source: https://docs.bizzyco.ai/api-reference/business-profile/get-business-profile /api-reference/openapi.json get /v1/businesses/{id}/profile Get the profile for a specific business # Update business profile Source: https://docs.bizzyco.ai/api-reference/business-profile/update-business-profile /api-reference/openapi.json put /v1/businesses/{id}/profile Update the profile for a business # Get business Source: https://docs.bizzyco.ai/api-reference/businesses/get-business /api-reference/openapi.json get /v1/businesses/{id} Get a specific business by ID # List businesses Source: https://docs.bizzyco.ai/api-reference/businesses/list-businesses /api-reference/openapi.json get /v1/businesses List all businesses with pagination support # Partially update business Source: https://docs.bizzyco.ai/api-reference/businesses/partially-update-business /api-reference/openapi.json patch /v1/businesses/{id} Partially update an existing business. Only provided fields will be updated. # Update business Source: https://docs.bizzyco.ai/api-reference/businesses/update-business /api-reference/openapi.json put /v1/businesses/{id} Update an existing business. Note: This endpoint accepts partial updates (same behavior as PATCH). # Create contact address Source: https://docs.bizzyco.ai/api-reference/contact-addresses/create-contact-address /api-reference/openapi.json post /v1/contacts/{id}/addresses Create a new address for a contact # Delete contact address Source: https://docs.bizzyco.ai/api-reference/contact-addresses/delete-contact-address /api-reference/openapi.json delete /v1/contacts/{id}/addresses/{addressId} Delete an address from a contact # Get contact address Source: https://docs.bizzyco.ai/api-reference/contact-addresses/get-contact-address /api-reference/openapi.json get /v1/contacts/{id}/addresses/{addressId} Get a specific address for a contact # List contact addresses Source: https://docs.bizzyco.ai/api-reference/contact-addresses/list-contact-addresses /api-reference/openapi.json get /v1/contacts/{id}/addresses List all addresses for a specific contact with pagination # Update contact address Source: https://docs.bizzyco.ai/api-reference/contact-addresses/update-contact-address /api-reference/openapi.json put /v1/contacts/{id}/addresses/{addressId} Update an existing address for a contact # Create contact email Source: https://docs.bizzyco.ai/api-reference/contact-emails/create-contact-email /api-reference/openapi.json post /v1/contacts/{id}/emails Create a new email for a contact # Delete contact email Source: https://docs.bizzyco.ai/api-reference/contact-emails/delete-contact-email /api-reference/openapi.json delete /v1/contacts/{id}/emails/{emailId} Delete an email from a contact # List contact emails Source: https://docs.bizzyco.ai/api-reference/contact-emails/list-contact-emails /api-reference/openapi.json get /v1/contacts/{id}/emails List all emails for a specific contact with pagination # Update contact email Source: https://docs.bizzyco.ai/api-reference/contact-emails/update-contact-email /api-reference/openapi.json put /v1/contacts/{id}/emails/{emailId} Update an existing email for a contact # Create contact phone number Source: https://docs.bizzyco.ai/api-reference/contact-phone-numbers/create-contact-phone-number /api-reference/openapi.json post /v1/contacts/{id}/phone-numbers Create a new phone number for a contact # Delete contact phone number Source: https://docs.bizzyco.ai/api-reference/contact-phone-numbers/delete-contact-phone-number /api-reference/openapi.json delete /v1/contacts/{id}/phone-numbers/{phoneNumberId} Delete a phone number from a contact # List contact phone numbers Source: https://docs.bizzyco.ai/api-reference/contact-phone-numbers/list-contact-phone-numbers /api-reference/openapi.json get /v1/contacts/{id}/phone-numbers List all phone numbers for a specific contact with pagination # Update contact phone number Source: https://docs.bizzyco.ai/api-reference/contact-phone-numbers/update-contact-phone-number /api-reference/openapi.json put /v1/contacts/{id}/phone-numbers/{phoneNumberId} Update an existing phone number for a contact # Create contact Source: https://docs.bizzyco.ai/api-reference/contacts/create-contact /api-reference/openapi.json post /v1/contacts Create a new contact # Delete contact Source: https://docs.bizzyco.ai/api-reference/contacts/delete-contact /api-reference/openapi.json delete /v1/contacts/{id} Delete a contact (soft delete) # Get contact Source: https://docs.bizzyco.ai/api-reference/contacts/get-contact /api-reference/openapi.json get /v1/contacts/{id} Get a specific contact by ID with full details # List contacts Source: https://docs.bizzyco.ai/api-reference/contacts/list-contacts /api-reference/openapi.json get /v1/contacts List all contacts with full details and pagination support # Partially update contact Source: https://docs.bizzyco.ai/api-reference/contacts/partially-update-contact /api-reference/openapi.json patch /v1/contacts/{id} Partially update an existing contact. Only provided fields will be updated. # Update contact Source: https://docs.bizzyco.ai/api-reference/contacts/update-contact /api-reference/openapi.json put /v1/contacts/{id} Update an existing contact. Note: This endpoint accepts partial updates (same behavior as PATCH). # Create customer transaction Source: https://docs.bizzyco.ai/api-reference/customer-transactions/create-customer-transaction /api-reference/openapi.json post /v1/customers/{id}/transactions Create a new transaction for a customer # Delete customer transaction Source: https://docs.bizzyco.ai/api-reference/customer-transactions/delete-customer-transaction /api-reference/openapi.json delete /v1/customers/{id}/transactions/{transactionId} Delete a specific transaction for a customer (soft delete) # Get customer transaction Source: https://docs.bizzyco.ai/api-reference/customer-transactions/get-customer-transaction /api-reference/openapi.json get /v1/customers/{id}/transactions/{transactionId} Get a specific transaction for a customer # List customer transactions Source: https://docs.bizzyco.ai/api-reference/customer-transactions/list-customer-transactions /api-reference/openapi.json get /v1/customers/{id}/transactions List all transactions for a specific customer with pagination # Partially update customer transaction Source: https://docs.bizzyco.ai/api-reference/customer-transactions/partially-update-customer-transaction /api-reference/openapi.json patch /v1/customers/{id}/transactions/{transactionId} Partially update a specific transaction for a customer. Only provided fields will be updated. # Update customer transaction Source: https://docs.bizzyco.ai/api-reference/customer-transactions/update-customer-transaction /api-reference/openapi.json put /v1/customers/{id}/transactions/{transactionId} Update a specific transaction for a customer. Note: This endpoint accepts partial updates (same behavior as PATCH). All fields are optional. # Create customer Source: https://docs.bizzyco.ai/api-reference/customers/create-customer /api-reference/openapi.json post /v1/customers Create a new customer # Delete customer Source: https://docs.bizzyco.ai/api-reference/customers/delete-customer /api-reference/openapi.json delete /v1/customers/{id} Delete a customer (soft delete) # Get customer Source: https://docs.bizzyco.ai/api-reference/customers/get-customer /api-reference/openapi.json get /v1/customers/{id} Get a specific customer by ID # List customers Source: https://docs.bizzyco.ai/api-reference/customers/list-customers /api-reference/openapi.json get /v1/customers List all customers with pagination support # Partially update customer Source: https://docs.bizzyco.ai/api-reference/customers/partially-update-customer /api-reference/openapi.json patch /v1/customers/{id} Partially update an existing customer. Only provided fields will be updated. # Update customer Source: https://docs.bizzyco.ai/api-reference/customers/update-customer /api-reference/openapi.json put /v1/customers/{id} Update an existing customer. Note: This endpoint accepts partial updates (same behavior as PATCH). All fields are optional. # Create domain contact Source: https://docs.bizzyco.ai/api-reference/domain-contacts/create-domain-contact /api-reference/openapi.json post /v1/domains/{id}/contacts Create a new contact for a domain # Delete domain contact Source: https://docs.bizzyco.ai/api-reference/domain-contacts/delete-domain-contact /api-reference/openapi.json delete /v1/domains/{id}/contacts/{contactId} Delete a specific contact for a domain (soft delete) # Get domain contact Source: https://docs.bizzyco.ai/api-reference/domain-contacts/get-domain-contact /api-reference/openapi.json get /v1/domains/{id}/contacts/{contactId} Get a specific contact for a domain # List domain contacts Source: https://docs.bizzyco.ai/api-reference/domain-contacts/list-domain-contacts /api-reference/openapi.json get /v1/domains/{id}/contacts List all contacts for a specific domain with pagination # Partially update domain contact Source: https://docs.bizzyco.ai/api-reference/domain-contacts/partially-update-domain-contact /api-reference/openapi.json patch /v1/domains/{id}/contacts/{contactId} Partially update a specific contact for a domain. Only provided fields will be updated. # Update domain contact Source: https://docs.bizzyco.ai/api-reference/domain-contacts/update-domain-contact /api-reference/openapi.json put /v1/domains/{id}/contacts/{contactId} Update a specific contact for a domain. Note: This endpoint accepts partial updates (same behavior as PATCH). # Create domain registration Source: https://docs.bizzyco.ai/api-reference/domain-registrations/create-domain-registration /api-reference/openapi.json post /v1/domains/{id}/registrations Create a new registration for a domain # Delete domain registration Source: https://docs.bizzyco.ai/api-reference/domain-registrations/delete-domain-registration /api-reference/openapi.json delete /v1/domains/{id}/registrations/{registrationId} Delete a specific registration for a domain (soft delete) # Get domain registration Source: https://docs.bizzyco.ai/api-reference/domain-registrations/get-domain-registration /api-reference/openapi.json get /v1/domains/{id}/registrations/{registrationId} Get a specific registration for a domain # List domain registrations Source: https://docs.bizzyco.ai/api-reference/domain-registrations/list-domain-registrations /api-reference/openapi.json get /v1/domains/{id}/registrations List all registrations for a specific domain with pagination # Partially update domain registration Source: https://docs.bizzyco.ai/api-reference/domain-registrations/partially-update-domain-registration /api-reference/openapi.json patch /v1/domains/{id}/registrations/{registrationId} Partially update a specific registration for a domain. Only provided fields will be updated. # Update domain registration Source: https://docs.bizzyco.ai/api-reference/domain-registrations/update-domain-registration /api-reference/openapi.json put /v1/domains/{id}/registrations/{registrationId} Update a specific registration for a domain. Note: This endpoint accepts partial updates (same behavior as PATCH). # Create domain Source: https://docs.bizzyco.ai/api-reference/domains/create-domain /api-reference/openapi.json post /v1/domains Create a new domain # Delete domain Source: https://docs.bizzyco.ai/api-reference/domains/delete-domain /api-reference/openapi.json delete /v1/domains/{id} Delete a domain (soft delete) # Get domain Source: https://docs.bizzyco.ai/api-reference/domains/get-domain /api-reference/openapi.json get /v1/domains/{id} Get a specific domain by ID # List domains Source: https://docs.bizzyco.ai/api-reference/domains/list-domains /api-reference/openapi.json get /v1/domains List all domains with pagination support # Partially update domain Source: https://docs.bizzyco.ai/api-reference/domains/partially-update-domain /api-reference/openapi.json patch /v1/domains/{id} Partially update an existing domain. Only provided fields will be updated. # Update domain Source: https://docs.bizzyco.ai/api-reference/domains/update-domain /api-reference/openapi.json put /v1/domains/{id} Update an existing domain. Note: This endpoint accepts partial updates (same behavior as PATCH). All fields are optional. # Errors Source: https://docs.bizzyco.ai/api-reference/errors Understand Bizzy API error codes and responses The Bizzy API uses conventional HTTP status codes and returns detailed error information in JSON format to help you handle errors gracefully. ## Error Response Format All error responses follow a consistent structure: ```json theme={null} { "error": { "code": "ERROR_CODE", "message": "A human-readable description of the error", "details": { // Additional context (optional) } } } ``` | Field | Type | Description | | --------- | ------ | ------------------------------------------------------- | | `code` | string | A machine-readable error code for programmatic handling | | `message` | string | A human-readable description of what went wrong | | `details` | object | Additional context about the error (optional) | ## HTTP Status Codes | Status | Meaning | When It Occurs | | ------ | --------------------- | ------------------------------------------------------ | | `200` | OK | Request succeeded | | `201` | Created | Resource was created successfully | | `204` | No Content | Request succeeded with no response body (e.g., DELETE) | | `400` | Bad Request | Invalid request format or parameters | | `401` | Unauthorized | Missing or invalid API key | | `403` | Forbidden | Valid API key but insufficient permissions | | `404` | Not Found | Resource doesn't exist | | `429` | Too Many Requests | Rate limit exceeded | | `500` | Internal Server Error | Something went wrong on our end | | `503` | Service Unavailable | Temporary service outage | ## Error Codes Reference ### Authentication Errors | Code | Status | Description | | -------------------------- | ------ | ---------------------------------- | | `UNAUTHORIZED` | 401 | Invalid or missing API key | | `INSUFFICIENT_PERMISSIONS` | 403 | API key lacks required permissions | ```json theme={null} { "error": { "code": "UNAUTHORIZED", "message": "Invalid or missing API key" } } ``` ### Validation Errors | Code | Status | Description | | ------------------ | ------ | ----------------------------------- | | `VALIDATION_ERROR` | 400 | Request body failed validation | | `INVALID_INPUT` | 400 | Invalid query parameters or input | | `MISSING_QUERY` | 400 | Required query parameter is missing | Validation errors include details about which fields failed. `details` is a tree mirroring the request body: each node has an `errors` array (issues at that path), and object nodes additionally have a `properties` map keyed by field name. The top-level `errors` array carries issues that apply to the request as a whole. ```json theme={null} { "error": { "code": "VALIDATION_ERROR", "message": "Invalid request body", "details": { "errors": [], "properties": { "email": { "errors": ["Invalid email address"] }, "name": { "errors": [ "Too small: expected string to have >=1 characters" ] } } } } } ``` ### Resource Errors | Code | Status | Description | | --------------------- | ------ | -------------------------------- | | `NOT_FOUND` | 404 | Requested resource doesn't exist | | `INVALID_MESSAGE_ID` | 400 | Invalid message ID format | | `INVALID_CONTACT_ID` | 400 | Invalid contact ID format | | `INVALID_BUSINESS_ID` | 400 | Invalid business ID format | ```json theme={null} { "error": { "code": "NOT_FOUND", "message": "Contact not found" } } ``` ### Rate Limiting Errors | Code | Status | Description | | --------------------- | ------ | ----------------- | | `RATE_LIMIT_EXCEEDED` | 429 | Too many requests | ```json theme={null} { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please retry after 60 seconds", "details": { "retryAfter": 60 } } } ``` ### Server Errors | Code | Status | Description | | --------------------- | ------ | ------------------------------- | | `INTERNAL_ERROR` | 500 | Unexpected server error | | `SERVICE_UNAVAILABLE` | 503 | Service temporarily unavailable | ```json theme={null} { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } ``` ## Handling Errors ### Basic Error Handling ```typescript TypeScript theme={null} async function makeRequest() { const response = await fetch('https://api.bizzyco.ai/v1/contacts', { headers: { 'Authorization': `Bearer ${apiKey}`, }, }); if (!response.ok) { const { error } = await response.json(); switch (response.status) { case 401: throw new Error('Invalid API key'); case 403: throw new Error(`Permission denied: ${error.message}`); case 404: throw new Error('Resource not found'); case 429: throw new Error('Rate limited - retry later'); default: throw new Error(error.message || 'Request failed'); } } return response.json(); } ``` ```python Python theme={null} import requests def make_request(): response = requests.get( 'https://api.bizzyco.ai/v1/contacts', headers={'Authorization': f'Bearer {api_key}'} ) if not response.ok: error = response.json().get('error', {}) if response.status_code == 401: raise Exception('Invalid API key') elif response.status_code == 403: raise Exception(f"Permission denied: {error.get('message')}") elif response.status_code == 404: raise Exception('Resource not found') elif response.status_code == 429: raise Exception('Rate limited - retry later') else: raise Exception(error.get('message', 'Request failed')) return response.json() ``` ### Retry with Exponential Backoff For transient errors (429, 500, 503), implement retry logic with exponential backoff: ```typescript TypeScript theme={null} async function fetchWithRetry( url: string, options: RequestInit, maxRetries = 3 ): Promise { let lastError: Error; for (let attempt = 0; attempt < maxRetries; attempt++) { try { const response = await fetch(url, options); // Don't retry client errors (except rate limiting) if (response.ok || (response.status >= 400 && response.status < 500 && response.status !== 429)) { return response; } // For rate limiting, use Retry-After header if available if (response.status === 429) { const retryAfter = response.headers.get('Retry-After'); const delay = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, attempt) * 1000; await new Promise(resolve => setTimeout(resolve, delay)); continue; } // For server errors, use exponential backoff if (response.status >= 500) { const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s await new Promise(resolve => setTimeout(resolve, delay)); continue; } return response; } catch (error) { lastError = error as Error; const delay = Math.pow(2, attempt) * 1000; await new Promise(resolve => setTimeout(resolve, delay)); } } throw lastError!; } ``` ```python Python theme={null} import time import requests def fetch_with_retry(url, headers, max_retries=3): last_error = None for attempt in range(max_retries): try: response = requests.get(url, headers=headers) # Don't retry client errors (except rate limiting) if response.ok or (400 <= response.status_code < 500 and response.status_code != 429): return response # For rate limiting, use Retry-After header if available if response.status_code == 429: retry_after = response.headers.get('Retry-After') delay = int(retry_after) if retry_after else (2 ** attempt) time.sleep(delay) continue # For server errors, use exponential backoff if response.status_code >= 500: delay = 2 ** attempt # 1s, 2s, 4s time.sleep(delay) continue return response except requests.RequestException as e: last_error = e delay = 2 ** attempt time.sleep(delay) raise last_error ``` ## Best Practices Use the `code` field for programmatic error handling, not the `message`. Error messages may change, but error codes remain stable. Include the request ID from response headers (`X-Request-ID`) when logging errors to help with debugging and support requests. Walk the `details` tree (each node's `errors` array, recursing into `properties`) to show specific field errors to your users rather than generic error messages. # Create access link Source: https://docs.bizzyco.ai/api-reference/file-access-links/create-access-link /api-reference/openapi.json post /v1/files/{id}/access-links Create a new access link for a file # List access links Source: https://docs.bizzyco.ai/api-reference/file-access-links/list-access-links /api-reference/openapi.json get /v1/files/{id}/access-links List all access links for a specific file with pagination # Delete file Source: https://docs.bizzyco.ai/api-reference/files/delete-file /api-reference/openapi.json delete /v1/files/{id} Delete a file from storage and database # Download file Source: https://docs.bizzyco.ai/api-reference/files/download-file /api-reference/openapi.json get /v1/files/{id}/download Download the file content # Download file via access link Source: https://docs.bizzyco.ai/api-reference/files/download-file-via-access-link /api-reference/openapi.json get /v1/files/public/{token} Download a file using a public access link token. No authentication required. # Get file Source: https://docs.bizzyco.ai/api-reference/files/get-file /api-reference/openapi.json get /v1/files/{id} Get a specific file by ID with full details # List files Source: https://docs.bizzyco.ai/api-reference/files/list-files /api-reference/openapi.json get /v1/files List all files with full details and pagination support # Search files Source: https://docs.bizzyco.ai/api-reference/files/search-files /api-reference/openapi.json get /v1/files/search Full-text search files by name, description, or content # Update file Source: https://docs.bizzyco.ai/api-reference/files/update-file /api-reference/openapi.json put /v1/files/{id} Update an existing file metadata # Upload file Source: https://docs.bizzyco.ai/api-reference/files/upload-file /api-reference/openapi.json post /v1/files/upload Upload a new file. Uses multipart form data with the file and optional metadata. # Create folder Source: https://docs.bizzyco.ai/api-reference/folders/create-folder /api-reference/openapi.json post /v1/folders Create a new folder # Delete folder Source: https://docs.bizzyco.ai/api-reference/folders/delete-folder /api-reference/openapi.json delete /v1/folders/{id} Delete a folder. Subfolders will be cascade deleted. Files in the folder will have their folderId set to null. # Get folder Source: https://docs.bizzyco.ai/api-reference/folders/get-folder /api-reference/openapi.json get /v1/folders/{id} Get a specific folder by ID with full details (including file/subfolder counts) # List folders Source: https://docs.bizzyco.ai/api-reference/folders/list-folders /api-reference/openapi.json get /v1/folders List all folders with full details (including file/subfolder counts) and pagination support # Update folder Source: https://docs.bizzyco.ai/api-reference/folders/update-folder /api-reference/openapi.json put /v1/folders/{id} Update an existing folder # Introduction Source: https://docs.bizzyco.ai/api-reference/introduction Learn the basics of the Bizzy API The Bizzy API provides programmatic access to your business communication data, including messages, contacts, customers, and businesses. Use it to build integrations, automate workflows, and extend Bizzy's capabilities. **Quick reference for AI agents:** ```json theme={null} { "baseUrl": "https://api.bizzyco.ai/v1", "auth": "Authorization: Bearer ", "responseEnvelope": { "data": "T", "meta": { "pagination": { "limit": 10, "offset": 0, "hasMore": true } } }, "errorEnvelope": { "error": { "message": "string", "code": "string", "details": "object|undefined" } }, "pagination": ["limit (1-100)", "offset (>=0)", "sortOrder (asc|desc)"], "ids": "UUIDv4", "timestamps": "ISO 8601 UTC" } ``` ## Base URL All API requests should be made to: ``` https://api.bizzyco.ai/v1 ``` Do not include a trailing slash in the base URL. Endpoints are appended directly, e.g., `https://api.bizzyco.ai/v1/contacts`. The API is versioned, with `v1` being the current stable version. When breaking changes are introduced, a new version will be released. ## Request Format The API accepts JSON-encoded request bodies and returns JSON-encoded responses. ```bash cURL theme={null} curl -X POST https://api.bizzyco.ai/v1/messages \ -H "Authorization: Bearer sk_live_abc123..." \ -H "Content-Type: application/json" \ -d '{"to": "user@example.com", "subject": "Hello"}' ``` ```typescript TypeScript theme={null} const response = await fetch('https://api.bizzyco.ai/v1/messages', { method: 'POST', headers: { Authorization: 'Bearer sk_live_abc123...', 'Content-Type': 'application/json', }, body: JSON.stringify({ to: 'user@example.com', subject: 'Hello', }), }); const data = await response.json(); ``` ```python Python theme={null} import requests response = requests.post( 'https://api.bizzyco.ai/v1/messages', headers={ 'Authorization': 'Bearer sk_live_abc123...', 'Content-Type': 'application/json', }, json={ 'to': 'user@example.com', 'subject': 'Hello', } ) data = response.json() ``` ### Required Headers | Header | Value | Description | | --------------- | ------------------ | ------------------------------------------ | | `Authorization` | `Bearer ` | Your API key for authentication | | `Content-Type` | `application/json` | Required for POST, PUT, and PATCH requests | ### Response Headers Every API response includes these headers: | Header | Description | | -------------- | ------------------------------------------------------------------------------------- | | `X-Request-ID` | Unique identifier for the request. Include this when contacting support for debugging | Rate limit response headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`) are not yet emitted. See [Rate Limits](/api-reference/rate-limits) for the current enforcement behavior. ## Shared conventions Every endpoint in the API follows the same conventions for response shape, pagination, errors, timestamps, and IDs. Once you've learned them here, you can skim the resource-specific reference pages without rediscovering them each time. ### Response envelope All successful responses wrap the payload in a `data` field: ```json theme={null} { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "subject": "Hello", "status": "sent", "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z" } } ``` List endpoints add a `meta.pagination` block: ```json theme={null} { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "subject": "Hello", "status": "sent" }, { "id": "550e8400-e29b-41d4-a716-446655440001", "subject": "Follow-up", "status": "draft" } ], "meta": { "pagination": { "limit": 10, "offset": 0, "total": 42, "hasMore": true } } } ``` `hasMore` is computed server-side. `total` is included when the underlying query can provide it cheaply; otherwise it is omitted and you should rely on `hasMore` to know when to stop paginating. The request identifier is returned in the `X-Request-ID` response header, not in the body. When `total` is omitted, `hasMore` is inferred from whether the page returned exactly `limit` items. This means a page that happens to fill exactly to `limit` will report `hasMore: true` even if it is the last page — your next request will simply return an empty `data` array. Always stop paginating when you receive an empty page, not just when `hasMore` becomes `false`. ### Pagination List endpoints accept three query parameters: | Parameter | Default | Accepted values | Description | | ----------- | ------- | --------------- | ---------------------------------------- | | `limit` | 10 | 1–100 | Number of items to return | | `offset` | 0 | ≥ 0 | Number of items to skip | | `sortOrder` | `desc` | `asc` \| `desc` | Sort direction, typically by `createdAt` | The API is offset-based; cursor-based pagination is not available today. ```bash theme={null} curl "https://api.bizzyco.ai/v1/contacts?limit=20&offset=40&sortOrder=asc" \ -H "Authorization: Bearer sk_live_abc123..." ``` ### Error responses Errors use a single consistent shape: ```json theme={null} { "error": { "message": "Validation failed", "code": "VALIDATION_ERROR", "details": { "errors": [], "properties": { "email": { "errors": ["Invalid email address"] } } } } } ``` `details` is present on validation errors and omitted otherwise. Validation errors are returned as a tree mirroring the request body: each node has an `errors` array (issues that apply at that path), and object nodes additionally have a `properties` map keyed by field name. The top-level `errors` array carries issues that apply to the request as a whole. Status codes you'll see: | Status | Meaning | | ------ | -------------------------------------------------------- | | `400` | Validation error or malformed request | | `401` | Missing or invalid API key | | `402` | Insufficient credits for the requested operation | | `403` | API key lacks the permissions required for this endpoint | | `404` | Resource does not exist (or is soft-deleted) | | `500` | Unexpected server error | | `503` | Temporarily unavailable (e.g., database outage) | See [Error Handling](/api-reference/errors) for the full list of error codes. ### Soft deletes `DELETE` endpoints perform soft deletes: the record is retained with a `deletedAt` timestamp set. Soft-deleted records are filtered out of list and get responses — there is currently no query flag to include them. If you need to recover a record, contact support. ### Timestamps and IDs * **Timestamps** are ISO 8601 UTC strings, e.g., `2024-01-15T09:30:00Z`. Every resource returns `createdAt` and `updatedAt`, plus a nullable `deletedAt`. * **Identifiers** are UUID v4 strings (for example, `550e8400-e29b-41d4-a716-446655440000`). Every resource uses `id` as its primary key, and foreign keys follow the `Id` convention (`contactId`, `businessId`, etc.). ## SDKs Official SDKs for TypeScript and Python are coming soon. In the meantime, you can use the REST API directly with any HTTP client. ## OpenAPI Specification The Bizzy API is documented using OpenAPI 3.1. You can access the specification at: ``` https://api.bizzyco.ai/v1/openapi.json ``` Use this to generate client libraries, import into API tools like Postman, or explore the API programmatically. ## Next Steps Learn how to create and use API keys Understand error responses and codes # Get message attachment Source: https://docs.bizzyco.ai/api-reference/message-attachments/get-message-attachment /api-reference/openapi.json get /v1/messages/{id}/attachments/{attachmentId} Get a specific attachment for a message # List message attachments Source: https://docs.bizzyco.ai/api-reference/message-attachments/list-message-attachments /api-reference/openapi.json get /v1/messages/{id}/attachments List all attachments for a specific message # Get message contact Source: https://docs.bizzyco.ai/api-reference/message-contacts/get-message-contact /api-reference/openapi.json get /v1/messages/{id}/contacts/{contactId} Get a specific contact association for a message # List message contacts Source: https://docs.bizzyco.ai/api-reference/message-contacts/list-message-contacts /api-reference/openapi.json get /v1/messages/{id}/contacts List all contacts associated with a specific message # Delete message Source: https://docs.bizzyco.ai/api-reference/messages/delete-message /api-reference/openapi.json delete /v1/messages/{id} Delete a message (soft delete) # Get archived messages count Source: https://docs.bizzyco.ai/api-reference/messages/get-archived-messages-count /api-reference/openapi.json get /v1/messages/archived/count Get the count of archived messages # Get message Source: https://docs.bizzyco.ai/api-reference/messages/get-message /api-reference/openapi.json get /v1/messages/{id} Get a specific message by ID # Get messages by contact Source: https://docs.bizzyco.ai/api-reference/messages/get-messages-by-contact /api-reference/openapi.json get /v1/messages/contacts/{contactId}/messages Get all messages associated with a specific contact # Get messages by email address Source: https://docs.bizzyco.ai/api-reference/messages/get-messages-by-email-address /api-reference/openapi.json get /v1/messages/email-address/{emailAddressId}/messages Get all messages associated with a specific email address # Get messages by phone number Source: https://docs.bizzyco.ai/api-reference/messages/get-messages-by-phone-number /api-reference/openapi.json get /v1/messages/phone-number/{phoneNumberId}/messages Get all messages associated with a specific phone number # Get messages by thread Source: https://docs.bizzyco.ai/api-reference/messages/get-messages-by-thread /api-reference/openapi.json get /v1/messages/thread/{threadId} Get all messages in a specific thread # Get snoozed messages count Source: https://docs.bizzyco.ai/api-reference/messages/get-snoozed-messages-count /api-reference/openapi.json get /v1/messages/snoozed/count Get the count of snoozed messages # List archived messages Source: https://docs.bizzyco.ai/api-reference/messages/list-archived-messages /api-reference/openapi.json get /v1/messages/archived List all archived messages with pagination support # List incoming messages Source: https://docs.bizzyco.ai/api-reference/messages/list-incoming-messages /api-reference/openapi.json get /v1/messages/incoming List all incoming messages with pagination support # List messages Source: https://docs.bizzyco.ai/api-reference/messages/list-messages /api-reference/openapi.json get /v1/messages List all messages with pagination support # List outgoing messages Source: https://docs.bizzyco.ai/api-reference/messages/list-outgoing-messages /api-reference/openapi.json get /v1/messages/outgoing List all outgoing messages with pagination support # List snoozed messages Source: https://docs.bizzyco.ai/api-reference/messages/list-snoozed-messages /api-reference/openapi.json get /v1/messages/snoozed List all snoozed messages with pagination support # Update message Source: https://docs.bizzyco.ai/api-reference/messages/update-message /api-reference/openapi.json patch /v1/messages/{id} Update a message read status. Only readAt, archivedAt, and snoozedUntil fields are allowed. # Rate Limits Source: https://docs.bizzyco.ai/api-reference/rate-limits Understand API rate limits and how to handle them The Bizzy API enforces rate limits to ensure fair usage and maintain service stability for all users. Rate limits vary by subscription tier. ## Rate Limits by Tier | Tier | Requests per Minute | Burst Limit | | ---------- | ------------------- | ----------- | | Free | 10 | 15 | | Starter | 30 | 45 | | Pro | 100 | 150 | | Enterprise | Custom | Custom | **Burst limits** allow temporary spikes above your per-minute limit. For example, a Pro tier user (100 req/min) can make up to 150 requests in a short burst. However, sustained traffic above your base rate limit will result in throttling. Burst capacity refills as your request rate drops below the limit. ## Rate Limit Headers Rate limit response headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `Retry-After`) are not yet emitted. Planned for a future release — until then, track your own request rate client-side and detect throttling by the `429` status code alone. ## Handling Rate Limits When you exceed your rate limit, the API returns a `429 Too Many Requests` response: ```json theme={null} { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please try again later." } } ``` No `Retry-After` header is returned today, so use exponential backoff when retrying. ### Implementing Rate Limit Handling ```typescript TypeScript theme={null} async function fetchWithRateLimit( url: string, options: RequestInit, attempt = 0, ): Promise { const response = await fetch(url, options); if (response.status === 429) { const backoffMs = Math.min(60_000, 1_000 * 2 ** attempt); console.log(`Rate limited. Waiting ${backoffMs}ms before retry...`); await new Promise(resolve => setTimeout(resolve, backoffMs)); return fetchWithRateLimit(url, options, attempt + 1); } return response; } ``` ```python Python theme={null} import time import requests def fetch_with_rate_limit(url, headers, attempt=0): response = requests.get(url, headers=headers) if response.status_code == 429: backoff_s = min(60, 2 ** attempt) print(f'Rate limited. Waiting {backoff_s}s before retry...') time.sleep(backoff_s) return fetch_with_rate_limit(url, headers, attempt + 1) return response ``` ## Best Practices Instead of making requests as fast as possible, implement a queue that spreads requests evenly across your rate limit window. ```typescript theme={null} class RequestQueue { private queue: Array<() => Promise> = []; private processing = false; private requestsPerSecond: number; constructor(requestsPerMinute: number) { this.requestsPerSecond = requestsPerMinute / 60; } async add(fn: () => Promise): Promise { return new Promise((resolve, reject) => { this.queue.push(async () => { try { resolve(await fn()); } catch (e) { reject(e); } }); this.process(); }); } private async process() { if (this.processing) return; this.processing = true; while (this.queue.length > 0) { const fn = this.queue.shift()!; await fn(); await new Promise(r => setTimeout(r, 1000 / this.requestsPerSecond) ); } this.processing = false; } } ``` When you receive a 429 response, don't immediately retry. Implement exponential backoff starting at 1 second (e.g., 1s, 2s, 4s, 8s, capped at 60s). Reduce API calls by caching responses that don't change frequently. This is especially useful for reference data like contact lists or business details. Where available, use batch endpoints to perform multiple operations in a single request instead of making separate calls. ## Increasing Your Limits If you consistently need higher rate limits: 1. **Upgrade your plan** - Higher tiers include increased rate limits 2. **Contact sales** - Enterprise plans include custom rate limits tailored to your needs View pricing and upgrade options # List task activity Source: https://docs.bizzyco.ai/api-reference/task-activity/list-task-activity /api-reference/openapi.json get /v1/tasks/{id}/activity Get the activity history for a specific task showing all changes, assignments, and status updates # Assign user to task Source: https://docs.bizzyco.ai/api-reference/task-assignees/assign-user-to-task /api-reference/openapi.json post /v1/tasks/{id}/assignees Assign a user to a task # List task assignees Source: https://docs.bizzyco.ai/api-reference/task-assignees/list-task-assignees /api-reference/openapi.json get /v1/tasks/{id}/assignees List all users assigned to a specific task # Unassign user from task Source: https://docs.bizzyco.ai/api-reference/task-assignees/unassign-user-from-task /api-reference/openapi.json delete /v1/tasks/{id}/assignees/{userId} Remove a user assignment from a task # Create task Source: https://docs.bizzyco.ai/api-reference/tasks/create-task /api-reference/openapi.json post /v1/tasks Create a new task # Delete task Source: https://docs.bizzyco.ai/api-reference/tasks/delete-task /api-reference/openapi.json delete /v1/tasks/{id} Delete a task (soft delete) # Get task Source: https://docs.bizzyco.ai/api-reference/tasks/get-task /api-reference/openapi.json get /v1/tasks/{id} Get a specific task by ID with full details and assignees # List tasks Source: https://docs.bizzyco.ai/api-reference/tasks/list-tasks /api-reference/openapi.json get /v1/tasks List all tasks with full details, assignees, and pagination support. Supports filtering by status, category, urgency, importance, assignee, and due date. # Partially update task Source: https://docs.bizzyco.ai/api-reference/tasks/partially-update-task /api-reference/openapi.json patch /v1/tasks/{id} Partially update an existing task. Only provided fields will be updated. # Search tasks Source: https://docs.bizzyco.ai/api-reference/tasks/search-tasks /api-reference/openapi.json get /v1/tasks/search Search tasks using full-text search across title, description, and metadata # Update task Source: https://docs.bizzyco.ai/api-reference/tasks/update-task /api-reference/openapi.json put /v1/tasks/{id} Update an existing task. Note: This endpoint accepts partial updates (same behavior as PATCH). # Agents Source: https://docs.bizzyco.ai/get-started/concepts/agents What agents are, how they differ from automations, and how you control them Bizzy has two kinds of AI worker: **agents** and **automations**. They look similar from a distance — both use LLMs, both can call tools, both can read your data and act on it — but they answer different questions, and using them interchangeably is the most common source of confusion for new users. Read this page, then read [Automations](/get-started/concepts/automations). Together they give you a clear sense of which one to reach for. ## Agents vs. Automations at a Glance | | **Agent** | **Automation** | | ------------------ | ------------------------------------------------------------- | ----------------------------------------------------------- | | **Triggered by** | A person chatting with it (or another workflow invoking it) | A platform event — new message, new contact, schedule, etc. | | **Shape** | A conversational LLM loop that calls tools to get things done | A rule that says "when X happens, do Y" | | **Has memory of?** | Yes — every turn of the conversation | No — each execution is fresh | | **Best for** | Open-ended help, research, multi-turn judgement | Routine, event-driven work that should just happen | A useful intuition: an **automation** is a tireless junior employee waiting for the inbox to ping. An **agent** is a colleague you can ask things of. The two cooperate. An automation can invoke an agent as one of its steps when the work needs more nuance than rules can capture — for example, "when a new email arrives, ask the support agent to draft a reply." ## What is an Agent? An agent is a configured persona that runs an LLM loop. When you create an agent you decide: * **Name and system prompt** — who the agent is and how it should behave. * **Model** — which LLM powers it. * **Tools it has access to** — and at what permission level. * **Step budget** — `maxSteps` caps how many tool calls a single response can make. The default is **5**. * **LLM parameters** — temperature, top-p, frequency/presence penalties, and so on, for power users. When a person (or another workflow) sends the agent a message, it runs an agentic loop: read the message, choose a tool to call, get the result, choose another tool, until it's done or it hits its step budget. Each agent runs inside its own Cloudflare **Durable Object**, which keeps the conversation state warm for the duration. ## Tool Permissions Tools are the only way an agent affects the world — read your contacts, send an email, create a task, search files. Bizzy gives you granular control over each tool, with three levels: | Level | Behaviour | | ----------- | --------------------------------------------------------------------------------------------------- | | **`allow`** | Agent calls the tool automatically, no prompt | | **`ask`** | Agent must request approval before each call; you see what it wants to do and can approve or reject | | **`deny`** | Tool is hidden from the agent entirely | Sensible defaults are applied for you: **read-style tools default to `allow`** (an agent should be able to look things up without asking permission), **write- and delete-style tools default to `ask`** (anything that mutates state should pause for a human). You can override any of these per agent. ## Conversations Every chat with an agent is recorded as an **agent conversation** — a thread you can revisit, share, or audit later. Each conversation has: * A **status**: `active`, `completed`, `timeout`, or `error`. * A **source**: `web` (the dashboard chat UI), `api`, or `mcp` (a Model Context Protocol client like Claude Desktop or Cursor). * The full transcript, including tool calls, tool results, and any approval decisions. Conversations are how you scale review of AI work without watching every step in real time. You can browse the conversation history of any agent and see exactly what it did and why. ## How an Agent Runs ```mermaid theme={null} graph TD A[User sends message] --> B[Durable Object resumes conversation] B --> C{LLM decides:
tool call or reply?} C -->|tool| D[Permission check] D -->|allow| E[Run tool] D -->|ask| F[Pause for approval] F --> E E --> C C -->|reply| G[Stream reply to user] G --> H[Conversation persisted] ``` The loop is bounded — `maxSteps` is a hard cap on tool calls per turn — and is interruptible. If a permission prompt comes back denied, or if you pause the conversation, the agent stops cleanly. ## When to Use Which Reach for an **agent** when: * You want to ask follow-up questions in a conversation. * The work needs judgement, not just rules — "summarise this account's recent activity," "draft a polite refund refusal." * You want a human in the loop on writes. Reach for an **automation** when: * The trigger is an event you can describe — "a new email arrives," "a customer signs up." * You want it to run forever, untouched, until you tell it to stop. * The behaviour is predictable enough that you don't need to chat about it. When in doubt: if you'd ever consider hitting "send" yourself before the action happens, you probably want an agent. If the action should *always* happen the moment the trigger fires, you probably want an automation. ## Related Topics The other half of this story Build your first agent in the web app Configure allow / ask / deny for each tool Browse and audit past chats # Automations Source: https://docs.bizzyco.ai/get-started/concepts/automations How AI-powered automations work in Bizzy Automations are how Bizzy turns your inbox from a task list into a system that works for you. Instead of manually processing every message, you define rules in plain English and let AI handle the routine work. ## What Are Automations? An **automation** is a workflow that runs when something happens in Bizzy. Every automation has three parts: 1. **Trigger** — the event that starts the automation (e.g., a new email arrives) 2. **Instructions** — what you want the AI to do, written in natural language 3. **Permissions** — what actions the automation is allowed to take What makes Bizzy automations different from traditional "if this, then that" rules is the **AI layer**. Instead of rigid conditions and fixed responses, you describe what you want in plain English and the AI interprets each situation individually. ## Automations vs. Agents Bizzy has two kinds of AI worker, and they're easy to confuse. **Automations** are event-triggered: a message arrives, a contact is created, a schedule fires, and the automation runs without anyone being there. **Agents** are conversational: you (or another workflow) chat with them, and they call tools to get things done across multiple turns. A useful intuition: an automation is a junior employee waiting for the inbox to ping. An agent is a colleague you can ask things of. Automations *can* invoke an agent as one of their steps when the work needs more nuance than rules can capture — for example, "when a new email arrives, ask the support agent to draft a reply." If you'd ever want to hit "send" yourself before the action happens, reach for an [agent](/get-started/concepts/agents). If the action should *always* happen the moment the trigger fires, reach for an automation. ## How Automations Work When an event occurs — say a new email arrives — Bizzy checks if any active automations match that trigger. If so, the AI reads the incoming content, evaluates your instructions, and takes action. Here's the flow: 1. **Event occurs** — A new email, contact creation, or other trigger event happens 2. **Trigger matches** — Bizzy identifies automations listening for this event 3. **AI processes** — The AI reads the content and interprets your instructions 4. **Action taken** — The AI performs the appropriate action (reply, create contact, etc.) 5. **Result logged** — The execution is recorded so you can review what happened The AI doesn't follow a decision tree — it understands context. An instruction like "if this looks like a support request, send an acknowledgment" works because the AI can evaluate whether an email is a support request, even if the sender doesn't use the word "support." ## The Power of Natural Language Instructions Traditional automation tools require you to define exact conditions: "if subject contains 'help' OR subject contains 'support' OR subject contains 'issue'..." This is brittle and misses edge cases. Bizzy automations use AI instructions instead: ``` When a new email arrives: 1. If it looks like a support request, send a friendly acknowledgment 2. If it's a sales inquiry, tag the contact as "Lead" 3. If it's a newsletter or automated notification, do nothing ``` The AI handles the ambiguity. It understands that "My login isn't working" is a support request even though it doesn't contain the word "support." ## What Can Automations Do? Automations can take a range of actions depending on their permissions: * **Send replies** — Compose and send email responses * **Create and update contacts** — Add new contacts or update existing ones * **Manage messages** — Archive, label, or categorize incoming messages * **Send notifications** — Alert team members about important messages * **Create tasks** — Generate follow-up tasks from incoming requests ## Automation Lifecycle Automations have a lifecycle with different states: | Status | Meaning | | ------------- | ------------------------------------------------- | | **Active** | Running and processing events as they occur | | **Paused** | Temporarily disabled — can be resumed at any time | | **Completed** | Finished after reaching an execution limit | | **Expired** | Past its configured expiration date | You can pause an automation at any time without losing its configuration. This is useful when you want to temporarily stop processing while you refine your instructions. ## Automations and Permissions Automations run with the permissions that were set when they were created. They cannot perform actions beyond their granted permissions. This means: * An automation with read-only message access can analyze emails but not reply * An automation without contact permissions cannot create or modify contacts * Permissions are checked on every execution, not just at creation time This design ensures automations stay within the boundaries you define, even as the AI interprets instructions flexibly. ## Related Topics Step-by-step guide to building an automation Build a working AI-powered support workflow from scratch The conversational counterpart — when to reach for one instead # Businesses Source: https://docs.bizzyco.ai/get-started/concepts/businesses How Bizzy models the businesses you run inside one organization In Bizzy, your **organization** is your account — the container for users, billing, and data. Inside that account, you run one or more **businesses**. The distinction matters: most plans support multiple businesses per organization, and each business has its own profile, products, locations, and Stripe connection. If you operate a single business, the difference is mostly invisible — your one business sits inside your one organization, and you rarely think about it. If you operate several (an agency with multiple service lines, a holding company with separate brands, or a contractor who runs both a roofing and a solar business under one team), the multi-business model is the spine of how Bizzy organizes everything else. ## What a Business Is A business represents a real-world commercial entity. It has: * A **profile** — name, industries, description, and a flexible field for whatever else you need to record. * A set of **offerings** — the products and services it sells. * **Online presences** — websites, social accounts, marketplace listings. * **Physical presences** — locations, addresses, service areas. * An optional **Stripe connection** — its own connected Stripe account for payments. A business is the customer-facing identity Bizzy grounds itself in: when an agent drafts a reply or an automation composes an email on your behalf, the business profile, offerings, and presences tell the AI *which* business it's speaking for. Records like contacts, customers, and messages live at the organization level today; business-level scoping for agents and automations is on the roadmap. ## Business vs. Organization The two concepts are easy to conflate. The short version: | | **Organization** | **Business** | | --------------------- | ---------------------------- | ------------------------------------------------ | | **What it is** | Your Bizzy account | A commercial entity you run inside the account | | **Holds** | Users, billing, settings | Profile, offerings, presences, Stripe | | **How many you have** | One per account | One or more | | **Used for** | Access control, subscription | Customer-facing identity, payments, AI grounding | The organization is the *container*. The business is the *thing the world sees*. ## Profile The business profile is what your AI grounds itself in when it speaks on your behalf. It includes: * **Name** — the public-facing name. * **Industries** — one or more industries (e.g. roofing, HVAC, professional services). * **Description** — a free-form pitch the AI can lean on when drafting messages. * **Custom data** — a flexible field for anything else you want recorded. When an agent writes an email or an automation drafts a reply, it reads the business profile to stay on-brand and on-topic. ## Offerings An **offering** is something the business sells. It's tagged as either a **product** (something tangible or fixed) or a **service** (something delivered). Each offering has a name and description; together they define what the business actually does. Offerings power AI features that need to know your catalogue — for example, when an inbound message asks "do you do gutter cleaning?" the agent needs to know whether the answer is yes. ## Presences Presences answer the question "where is this business in the world?" — both digitally and physically. **Online presences** capture the digital footprint: a primary website, social media profiles, marketplace listings, review pages. Each entry has a type, provider, URL, and description. **Physical presences** capture the bricks-and-mortar side: an office, a warehouse, a service area. Each entry has a name, description, and address. Together they let agents and automations answer location-aware questions — "what's your address?", "do you serve this zip code?", "what's your Yelp page?" — with truthful, current data. ## Stripe Connect Each business can connect **its own** Stripe account through Stripe Connect. The connection lives at the business level, not the organization level — meaning two businesses inside the same organization can independently link to two different Stripe accounts, with separate customers, invoices, and sync schedules. Once connected, Bizzy keeps the business's customers and transactions in sync with its Stripe account. The connection has three sync modes: * **`off`** — Stripe is not connected, or sync is disabled. * **`one_way`** — data flows from Stripe into Bizzy only (a read-only mirror). * **`two_way`** — data flows in both directions. You can switch modes and trigger manual syncs from the business settings page. ## Putting It Together ```mermaid theme={null} graph TD O[Organization] --> B1[Business: Acme Roofing] O --> B2[Business: Acme Solar] B1 --> P1[Profile] B1 --> O1[Offerings] B1 --> N1[Online Presences] B1 --> H1[Physical Presences] B1 --> S1[Stripe Account] B2 --> P2[Profile] B2 --> O2[Offerings] B2 --> N2[Online Presences] B2 --> H2[Physical Presences] B2 --> S2[Stripe Account] ``` One organization. Two businesses. Two Stripe accounts. Two distinct profiles, catalogues, and footprints. One team running both. ## Related Topics Edit name, industries, and description Manage your product and service catalogue Online and physical locations Link a Stripe account to a business # Contacts, Customers & Businesses Source: https://docs.bizzyco.ai/get-started/concepts/contacts Understand how Bizzy organizes people and business relationships Bizzy provides three ways to organize the people and companies you work with: **Contacts**, **Customers**, and **Businesses**. Each serves a different purpose, and understanding the distinction helps you get the most from the platform. ## Overview | Type | What It Represents | Example | | ------------ | ----------------------------------------- | ------------------------------------------------------- | | **Contact** | An individual person you communicate with | John Smith, [jane@example.com](mailto:jane@example.com) | | **Customer** | A business relationship with a person | John Smith as a buyer | | **Business** | A company or organization | Acme Corporation | ## Contacts A **contact** represents an individual person. Contacts are the core of Bizzy's data model — they're the link between people and the messages you exchange with them. Every contact can have multiple email addresses and phone numbers, each with labels like "work" or "personal." When Bizzy receives a message, it matches the sender's email to an existing contact, linking the message to that person's history automatically. This means you can open any contact and see every conversation you've had with them, across all channels. Contacts are also created automatically when you receive emails from new senders, so your address book grows organically as you communicate. ## Customers A **customer** represents a business relationship. While a contact is just a person in your address book, a customer indicates they have a commercial relationship with you — they've bought something, signed up for a service, or are in your sales pipeline. Customers can have **transactions** associated with them — records of purchases, payments, or other financial events. This gives you a financial history tied to a person, separate from your communication history. ### When to Use Customers * Someone makes a purchase or payment * You want to track an ongoing client relationship * You need to record transaction history * You're building a sales pipeline ## Businesses A **business** represents a company or organization. Where contacts track individuals and customers track financial relationships, businesses track company-level information: industry, offerings, online presence, and physical locations. Businesses can be connected to contacts (people who work there) and customers (commercial relationships), giving you both the company-level and individual views. ## How They Work Together These three types form a hierarchy that mirrors real business relationships: ``` Business: Acme Corporation ├── Contact: John Smith (Sales Manager) │ └── Customer: John Smith (purchased in 2024) ├── Contact: Jane Doe (CEO) └── Contact: Bob Wilson (Support) ``` In this example: * **Acme Corporation** is tracked as a business with its company information * **John**, **Jane**, and **Bob** are contacts (individuals) * **John** is also a customer because he's made purchases ## Choosing the Right Type The general rule: * **Start with contacts.** Every person you communicate with should be a contact. Bizzy creates these automatically from email senders. * **Add customer records for buyers.** When someone makes a purchase or becomes a client, create a customer record to track the financial relationship. * **Add businesses for companies.** When you need to track company-level information — their products, locations, or team — create a business and link relevant contacts to it. ## Related Topics Add, edit, and organize your contacts How contacts link to your communications # Credits & Billing Source: https://docs.bizzyco.ai/get-started/concepts/credits How Bizzy meters compute, charges for it, and protects you when you exceed your plan Bizzy charges for two things: **what you can build** (capacity) and **what you do with it** (usage). Both are denominated in credits, and both are governed by the **tier** your account is on. This page explains the model so the line items on your bill have a story behind them. ## What is a Credit? A **credit** is the unit of measurement for usage on top of your plan. **One credit equals one cent of overage cost.** Credits accumulate against your account when you exceed the allowances bundled into your tier; you settle them up by paying for credit packs (or letting auto-recharge do it for you). Inside your tier, you don't think about credits — you have an allowance and you use it. You only feel credits when you go past it. ## Tiers There are four tiers: * **Free** — try the platform, hard caps on capacity. * **Starter** — entry-level paid plan. * **Professional** — full-featured plan for active users. * **Enterprise** — custom limits, support SLA, negotiated pricing. Each tier defines two things: how much capacity you have (the **account objects**) and how much usage is included before overages kick in (the **consumables**). ## Account Objects (Capacity) Account objects are *how much you can have* — hard caps that don't accumulate. Five of them: | Object | What it limits | | --------------- | -------------------------------------------------------- | | **Businesses** | Number of businesses you can run inside the organization | | **Seats** | Number of users with access | | **Agents** | Number of AI agents you can configure | | **MCP Servers** | Number of MCP credentials/servers | | **Automations** | Number of active automations | If you hit the cap, you can't create more without upgrading. We don't bill overages for capacity — we just stop the meter. ## Consumables (Usage) Consumables are *how much you can do* — meters that reset on each billing cycle. Seven of them: | Consumable | What it counts | | ----------------- | -------------------------------------------------------- | | **API Calls** | Calls to the public API | | **MCP Calls** | Calls to your MCP server | | **LLM Tokens** | Language model tokens consumed by agents and automations | | **Email Sends** | Outbound emails | | **SMS** | SMS messages, sent and received | | **Voice Minutes** | Voice call minutes | | **Storage** | Bytes stored in your file library | Inside your tier's allowance, these are free. Past it, every increment is billed at your tier's overage rate. ## Tier-Based Overage Rates Higher tiers get cheaper marginal usage: | Consumable | Free | Starter | Professional | | -------------------------- | ------ | ------- | ------------ | | **LLM Tokens** (per 10k) | \$0.50 | \$0.40 | \$0.30 | | **API Calls** (per 100) | \$0.03 | \$0.02 | \$0.01 | | **MCP Calls** (per 100) | \$0.03 | \$0.02 | \$0.01 | | **Email Sends** (per 100) | \$0.15 | \$0.10 | \$0.05 | | **SMS** (per 10) | \$0.15 | \$0.10 | \$0.075 | | **Voice Minutes** (per 10) | \$0.30 | \$0.20 | \$0.15 | | **Storage** (per GB) | \$0.25 | \$0.15 | \$0.10 | Enterprise rates are negotiated separately. ## How LLM Usage Becomes Credits The most common source of overage in active accounts is the **LLM Tokens** meter — every message your agents and automations send to a model counts. The relationship is direct: 1. Each LLM call records the input and output tokens consumed. 2. Tokens roll up into the `llmTokens` consumable on your account. 3. Once you cross your tier's included token allowance, additional tokens are billed at your tier's overage rate (e.g., \$0.30 per 10k on Professional). 4. The dollar charge is converted into credits — \$1 of overage = 100 credits. In other words: **credits are how the bill arrives**, not how the meter ticks. ## Recharging There are two ways to top up: * **Credit packs.** One-time purchases at $10, $20, $50, or $100. Use them when you know you have a busy month coming. * **Auto-recharge.** When your credit balance dips below a threshold, Bizzy tops it up automatically — the default top-up is **\$20**. Turn it on once and you stop thinking about it. Both buy the same credits; only the trigger differs. ## When You Downgrade — Soft Disable Bizzy never deletes your work because you change tiers. If you downgrade to a tier whose **account-object** caps are below your current usage, the platform doesn't throw away your extra agents, automations, or seats — it **soft-disables** them. Soft-disabled means: * Marked `isActive = false` and stamped with `disabledReason = 'tier_downgrade'`. * Newest entries are disabled first; **the organization owner is never disabled**. * The data is intact — it just can't run. * Move back up a tier (or remove other items) and you can re-activate them with one click; the platform verifies you're under the cap before allowing it. This is deliberate: downgrade decisions get reversed all the time, and losing the work each time would be punitive. ## Related Topics Detailed tier comparison See your current usage Buy credit packs and configure auto-recharge View, download, and pay invoices in-app # Files & Knowledge Source: https://docs.bizzyco.ai/get-started/concepts/files How Bizzy ingests, indexes, and retrieves your files for agents Bizzy lets you upload files — contracts, invoices, product sheets, runbooks — and makes them searchable by your agents. This page covers what happens between "I dropped a PDF in" and "my agent quoted the right paragraph back to me." ## What is a File? A **file** is any artefact you've uploaded to your organization. Each file: * Lives in **R2** (Cloudflare's object store). * Belongs to an organization, optionally inside a **folder**. * Has metadata — filename, content type, size, tags, description. * Has an **indexing status** that tracks where it is in the retrieval pipeline. Today, the indexing pipeline understands four formats end-to-end: **PDF**, **PNG**, **JPEG**, and **WebP** (via OCR), plus inline **Markdown**. Other formats can still be uploaded and shared via public links — they simply aren't indexed for retrieval. ## Folders Files can be grouped into folders. Folders are useful for two reasons: 1. **Organisation.** Same as folders anywhere — group what belongs together. 2. **Agent access control.** Each file (and each folder) carries an `agentAccessEnabled` flag. Set the flag on a folder to "off" and your agents will not see anything in it during retrieval, even if a query would otherwise match. This matters more than it sounds: it's how you separate, say, your public sales collateral from internal HR documents when both are in the same organization. ## The Indexing Pipeline When a file is uploaded, an asynchronous workflow takes it from raw bytes to retrievable knowledge: ```mermaid theme={null} graph LR A[Upload to R2] --> B[Parse] B --> C[Chunk] C --> D[Embed] D --> E[Index] E --> F[(pgvector)] ``` 1. **Upload** — the file is written to R2; a database record is created. 2. **Parse.** PDFs and images are run through Mistral OCR, which produces structured **markdown** per page. Markdown files skip OCR and are read inline. 3. **Chunk.** The structural markdown chunker splits the document along its natural seams: it walks H1 → H2 → H3 → H4 → H5 → H6 → blank-line paragraphs → sentences → words, in that order, picking the deepest split that keeps chunks within size bounds. Targets are **800 tokens** per chunk, with a **1,200-token cap** and a **\~100-token overlap** with the previous chunk so context isn't lost at boundaries. Code fences are kept intact. 4. **Embed.** Each chunk is sent to OpenAI's `text-embedding-3-small` (1536-dimensional vectors), in batches. 5. **Index.** Chunks land in PostgreSQL with `pgvector` for vector search and a tsvector column for keyword search. A file's `indexingStatus` walks through `pending → indexing → indexed`. If a file isn't indexable (unsupported format, too large, parser failure) the status ends in `skipped`, `excluded`, or `failed` — visible on the file's detail view so you know it's not searchable. ## How Agents Retrieve Files (RAG) When an agent needs information from your files, it doesn't just do a vector search. Pure embedding search is good at recall on fuzzy queries but bad at exact-term matches; pure keyword search is the opposite. Bizzy uses **hybrid retrieval** — both, then fused. ```mermaid theme={null} graph TD Q[Agent query] --> E[EmbeddingRetriever
top 50] Q --> B[BM25Retriever
top 50] E --> F[Reciprocal Rank Fusion] B --> F F --> R[Top 10 chunks → agent] ``` Two retrievers run **in parallel**: * **EmbeddingRetriever** — embeds the query, runs an approximate-nearest-neighbour search in pgvector, returns the top 50 chunks by cosine similarity. * **BM25Retriever** — runs a `ts_rank_cd` keyword search against the chunk text, returns the top 50 chunks. Their two ranked lists are then **fused with Reciprocal Rank Fusion** (the standard k=60 formula): a chunk's final score sums `1 / (60 + rank)` across both rankings. The top 10 fused chunks go back to the agent. Two important guarantees, enforced in SQL on every retrieval: * Only chunks from the agent's own organization are returned. * Files (and folders) with `agentAccessEnabled = false`, or with `indexingStatus ≠ indexed`, or that have been soft-deleted, are silently excluded. Your agent never sees what you've told it not to see. ## What it Costs Two consumables on your account meter file usage: * **`storage`** — the total bytes you have stored in R2. * **`text-embedding-3-small`** — embedding calls made during indexing. Both count against your tier's allowance and are charged at the relevant overage rate beyond that. See the [Credits](/get-started/concepts/credits) page for how the meters and tiers fit together. ## Related Topics How to add files in the web app Re-index files, exclude folders, troubleshoot How agents use files at runtime What storage and embeddings cost # Core Concepts Source: https://docs.bizzyco.ai/get-started/concepts/index Understand the fundamental concepts behind Bizzy Before diving deeper into Bizzy, it helps to understand the key concepts that shape how the platform works. This section covers the building blocks of Bizzy: how data is organized, how communication flows, how AI does work for you, and how it all gets paid for. ## Key Concepts Multi-tenancy, members, and access People you communicate with and people who buy from you Multiple businesses inside one organization Email, SMS, and other channels in one inbox Work tracking and the Eisenhower priority matrix File ingestion, RAG indexing, and retrieval Conversational AI workers — and how they differ from automations Event-triggered AI workflows Tiers, consumables, overage rates, and credits ## How It All Fits Together Bizzy is built around a simple hierarchy: ```mermaid theme={null} graph TD A[Organization] --> B[Members] A --> Bus[Businesses] A --> D[Contacts] A --> E[Customers] A --> G[Automations] A --> Ag[Agents] A --> Tk[Tasks] A --> Fl[Files] Bus --> C[Email Addresses
& Phone Numbers] D --> H[Messages] E --> I[Transactions] B[Members
users with access] Bus[Businesses
commercial entities you run] C[Email & Phone
channels for sending and receiving] D[Contacts
people you communicate with] E[Customers
buyers and ongoing relationships] G[Automations
event-triggered workflows] Ag[Agents
conversational AI workers] Tk[Tasks
work to be done] Fl[Files
indexed documents agents can search] H[Messages
communications with contacts] I[Transactions
sales and purchases] ``` **Organizations** are the top-level container. Everything else belongs to an organization and is isolated from other organizations. **Members** are users with access to the organization. Each member has a role that determines their permissions. **Businesses** are the commercial entities you run *inside* the organization. Most accounts have one; agencies and holding companies often have several. Each business has its own profile, offerings, locations, and Stripe connection. **Email Addresses** and **Phone Numbers** are the connected channels Bizzy uses to send and receive communications — Google or Microsoft accounts for email, Telnyx numbers for SMS and voice. **Contacts** represent the individuals you communicate with. **Customers** are contacts you have a commercial relationship with. **Messages** are the communications themselves, grouped into threads. **Tasks** are units of work — created by you, by automations, or by agents — and surface on your home page through the Eisenhower priority matrix. **Files** are documents you upload. Once indexed, they become a knowledge base that agents can search via hybrid retrieval (vector + keyword). **Agents** are conversational AI workers you chat with: configured persona, tool access, conversation history. **Automations** are event-triggered workflows that run on their own. Most users mix them up at first — see the [Agents](/get-started/concepts/agents) page for when to reach for which. **Credits** are how usage on top of your plan is metered and billed. They don't appear in the hierarchy because they're not data — they're the meter that runs over everything. ## Start Learning If you're new, read these in order: Start here — how access and data isolation works The people side of the platform The most important distinction in Bizzy How tiers, consumables, and overages work # Messages & Threads Source: https://docs.bizzyco.ai/get-started/concepts/messages How Bizzy organizes communications across channels Bizzy unifies your business communications into a single inbox. This page explains how messages are organized, what channels are supported, and how threading works. ## Message Basics A **message** is any communication sent or received through Bizzy. Each message has: | Property | Description | | ---------------- | -------------------------------------- | | **Direction** | Incoming (received) or outgoing (sent) | | **Timestamp** | When the message was sent or received | | **Sender** | Who sent the message | | **Recipient(s)** | Who received the message | | **Content** | The message body and any attachments | | **Thread ID** | Groups related messages together | ## Supported Channels Bizzy supports multiple communication channels: | Channel | Description | Status | | ------------- | -------------------------- | ----------- | | **Email** | Gmail, Outlook, Office 365 | Available | | **SMS** | Text messages via Telnyx | Available | | **WhatsApp** | WhatsApp Business messages | Coming soon | | **Signal** | Signal messenger | Coming soon | | **Telegram** | Telegram messages | Coming soon | | **Voicemail** | Transcribed voicemails | Coming soon | Email is the primary channel. Connect your Google or Microsoft account from the **Email Addresses** page to start receiving messages. ## Email Messages Email messages include additional properties: | Property | Description | | --------------- | ---------------------------------- | | **Subject** | Email subject line | | **To/CC/BCC** | Recipients and their visibility | | **Headers** | Technical email headers | | **Labels** | Gmail labels or Outlook categories | | **Attachments** | Files attached to the email | ### Email Features * **HTML rendering** - Emails display with full formatting * **Attachment preview** - View images and documents inline * **Reply/Forward** - Respond directly from Bizzy * **Labels sync** - Gmail labels and Outlook categories are synced ## Threads A **thread** is a group of related messages. Threading helps you follow conversations without losing context. ### How Threading Works Bizzy groups messages into threads based on: 1. **Email headers** - The `In-Reply-To` and `References` headers 2. **Subject matching** - Messages with the same subject 3. **Participants** - Messages between the same people When you click a message in your inbox, you see the entire thread—all related messages in chronological order. ### Thread View The thread view shows: * All messages in the conversation * Newest messages at the bottom * Sender information for each message * Timestamps * Attachments You can reply from the thread view, and your response will be part of the same conversation. ## Inbox Organization Messages are organized into four views: ### Inbox Your main inbox shows messages that need attention: * Unread messages * Messages you haven't archived * Recent conversations ### Sent Messages you've sent, organized by date. ### Snoozed Messages you've temporarily hidden. Snoozed messages reappear at a time you choose: * Later today * Tomorrow * Next week * Custom date/time Snoozing is useful for messages you can't deal with right now but don't want to forget. ### Archived Messages you've filed away. Archived messages are: * Removed from your inbox * Still searchable * Still accessible in the Archived view * Not deleted ## Message Actions From any message, you can: | Action | Keyboard | Description | | ------------- | -------- | ----------------------- | | **Reply** | `R` | Send a response | | **Reply All** | `A` | Reply to all recipients | | **Forward** | `F` | Send to someone else | | **Archive** | `E` | Move to archived | | **Snooze** | `H` | Hide temporarily | | **Delete** | `#` | Move to trash | ## Searching Messages Find messages using the search bar in the header. You can search by: * **Content** - Words in the message body * **Sender** - Email address or name * **Subject** - Email subject line * **Date** - Messages from a specific time period * **Attachments** - Messages with files Example searches: * `from:john@example.com` - Messages from John * `subject:invoice` - Messages with "invoice" in the subject * `has:attachment` - Messages with attachments * `after:2024-01-01` - Messages after a specific date * `before:2024-12-31` - Messages before a specific date * `from:john has:attachment` - Combine multiple filters ## Message and Contact Linking Messages are automatically linked to contacts: 1. When a message arrives, Bizzy checks the sender's email 2. If a contact exists with that email, the message is linked 3. Click the contact name to see their full profile This means you can: * View all messages with a contact from their profile * See contact details directly from a message * Quickly create contacts from message senders ## Related Topics Detailed email management guide How contacts work with messages # Organizations Source: https://docs.bizzyco.ai/get-started/concepts/organizations How multi-tenancy and team access work in Bizzy Organizations are the foundation of Bizzy's data model. Every piece of data — contacts, messages, automations — belongs to an organization. This page explains what organizations are, why they exist, and how they shape the way you use Bizzy. ## What is an Organization? An organization is a container that holds all your Bizzy data. Think of it as a workspace that can represent: * Your company * A department or team * A personal account * A client you manage Each organization is completely isolated from others. Data in one organization cannot be accessed from another, even by the same user. ## Why Organizations? Organizations exist to solve a fundamental problem: keeping different contexts separate while letting the right people collaborate within each one. | Benefit | Description | | ----------------------- | ----------------------------------------------------------- | | **Data isolation** | Keep different businesses or clients completely separate | | **Team collaboration** | Share access with colleagues while controlling permissions | | **Resource management** | Connect different email accounts to different organizations | | **Billing separation** | Each organization can have its own subscription | For example, a freelancer managing three clients can create a separate organization for each — keeping contacts, messages, and automations completely isolated. A single company would typically use one organization with multiple members. ## Members and Roles Organizations can have multiple members. Each member has a role that determines what they can do: | Role | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------- | | **Owner** | Full access to everything, including billing, API keys, and member management. Every organization has at least one owner. | | **Admin** | Can manage data and invite members, but cannot access billing or API keys. | | **User** | Read-only access to organization data. Can manage their own profile and files. | This hierarchy follows the principle of least privilege — most team members only need the User or Admin role. See [Roles & Permissions](/admin-guide/organization/permissions) for the full permission matrix. ## Organization Scope Everything in Bizzy is scoped to an organization: * **Contacts and customers** belong to an organization * **Messages** are received and sent through the organization's connected resources * **Automations** run within the organization's context * **API keys** and **MCP server access** grant access to a single organization's data If you belong to multiple organizations, you can switch between them from the header. Each switch changes your entire view to that organization's data. ## How Organizations Relate to Accounts Your Bizzy **account** is your personal identity — your login credentials. **Organizations** are workspaces you belong to. The relationship works like this: * One account can belong to multiple organizations * One organization can have multiple accounts (members) * Billing is managed at the account level, covering all organizations under it * Your subscription tier determines how many organizations you can create ## Related Topics Create and configure an organization Invite members, assign roles, and manage access Full permission matrix for each role # Tasks Source: https://docs.bizzyco.ai/get-started/concepts/tasks How tasks work in Bizzy and the priority matrix that powers your home page A **task** is a unit of work tracked inside Bizzy — something that needs doing, by someone, at some point. Tasks can be created by you, by an agent, or by an automation, and they all surface in the same place: the priority matrix on your home page. ## Anatomy of a Task | Property | Description | | --------------- | -------------------------------------------------------------------------------------------------- | | **Title** | Short summary of what needs doing | | **Description** | Optional longer detail | | **Status** | Where the task is in its lifecycle | | **Importance** | How significant the task is — `low`, `medium`, `high` | | **Urgency** | How time-sensitive the task is — `low`, `medium`, `high` | | **Category** | Type of work — bug fix, feature request, meeting, planning, research, review, documentation, other | | **Due date** | Optional deadline | | **Assignees** | Members of the organization responsible for the task | ### Status Lifecycle Tasks move through a small set of states: ``` backlog → todo → in_progress → in_review → done ↘ cancelled ``` You can jump between states freely — the order is suggestive, not enforced. ## The Eisenhower Priority Matrix Bizzy uses the **Eisenhower matrix** as the model for prioritising work. The idea, popularised by Dwight Eisenhower's "what is important is seldom urgent and what is urgent is seldom important," is to plot tasks on two axes — urgency and importance — and act differently in each quadrant. | | Important | Not important | | -------------- | ----------------- | ----------------- | | **Urgent** | **Q1 — Do First** | **Q3 — Delegate** | | **Not urgent** | **Q2 — Schedule** | **Q4 — Don't Do** | Bizzy maps each task to a quadrant using a deliberately strict rule. Only `high` counts as **urgent** or **important** — `low` and `medium` are treated equally as "not". And tasks with `null` urgency or `null` importance are routed straight to Q1, regardless of the other axis, so unclassified work can't slip past you without being triaged. * **Q1 — Do First.** Urgent and important. The fire-fighting quadrant. * **Q2 — Schedule.** Important but not urgent. Where deep work belongs — block time for it. * **Q3 — Delegate.** Urgent but not important. Hand off if you can; otherwise batch. * **Q4 — Don't Do.** Neither urgent nor important. Cut, archive, or politely ignore. ## The Home Page Widget Your organization home page leads with the priority matrix widget. It pulls together up to **50 tasks** plus up to **25 unread messages** and groups them into the four quadrants, sorted by due date and then creation time. You can flip between a 2×2 grid and a flat list, and act on items inline without leaving the page. Messages appear in the matrix because in a communications-driven business, an unread email is often a task in disguise. Treating both as items on the same grid means the AI's triage of incoming mail flows directly into your work queue. ## Where Tasks Come From Tasks are first-class entities — anything that produces work can produce a task: * **People.** You create tasks manually for things you need to track. * **Automations.** A rule like "when a customer asks for a refund, create a task for the billing team" emits a task. * **Agents.** When an agent is given the `createTask` tool and decides a follow-up is required, it can create one. Tasks created this way are flagged so you can audit them. Assignees are members of your organization. A task can have multiple assignees — useful for things one person owns but several people need to follow. ## Related Topics How to create, edit, and triage tasks in the web app Tour of the home-page priority matrix How automations create tasks for you How agents work with tasks # Welcome to Bizzy Source: https://docs.bizzyco.ai/get-started/index The AI-powered platform for unified business communications Bizzy brings all your business communications into one intelligent platform. Manage emails, contacts, customers, and automate workflows with AI—all from a single dashboard. ## What is Bizzy? Bizzy is a unified business communication platform that helps teams: * **Centralize communications** - Manage emails from multiple providers (Google, Microsoft) in one inbox * **Organize contacts** - Keep track of contacts, customers, and business relationships * **Automate workflows** - Create intelligent automations triggered by incoming messages * **Leverage AI** - Use AI agents to process, categorize, and respond to communications Whether you're a solo professional or part of a larger team, Bizzy helps you stay organized and responsive. ## Key Features View and manage emails from all your connected accounts in one place. Organize with folders, labels, and smart filters. Store contact details, track customer relationships, and link communications to the right people. Create workflows that trigger automatically based on incoming messages, saving time on repetitive tasks. Deploy AI agents that can read, categorize, and help manage your communications intelligently. ## Choose Your Path **New to Bizzy?** Start with the quickstart guide to connect your first email and explore the platform. **Managing a team?** Learn how to set up your organization, invite members, and configure integrations. **Building integrations?** Explore the API reference to programmatically access your data. ## Getting Help If you need assistance: * **Documentation** - Browse the guides in the sidebar for detailed instructions * **Support** - Email us at [support@bizzyco.ai](mailto:support@bizzyco.ai) * **Status** - Check [status.bizzyco.ai](https://status.bizzyco.ai) for system status ## Next Steps Set up your account and connect your email Build an AI-powered support workflow from scratch Learn your way around the dashboard # Platform Overview Source: https://docs.bizzyco.ai/get-started/overview Navigate the Bizzy dashboard and discover key features This guide introduces you to the Bizzy platform interface, helping you find your way around and understand where to access different features. ## Dashboard Layout The Bizzy dashboard is organized into three main areas: 1. **Sidebar** - Navigation menu on the left for accessing different sections 2. **Main Content** - The central area where you work with messages, contacts, and other data 3. **Header** - Top bar with organization switcher, search, and account settings ## Sidebar Navigation The sidebar provides quick access to all major features. Here's what each section does: ### Home Your dashboard landing page. For new organizations this is also where the **Setup checklist** card lives — a seven-step walkthrough (business profile, email, domain, phone, contact, automation, team invite) that auto-completes as you create each entity and silently disappears once every task is done or dismissed. ### Inbox Your unified email inbox. This is where you'll spend most of your time managing communications. | View | Description | | ------------ | ----------------------------------------------------- | | **Inbox** | Unread and active messages requiring attention | | **Sent** | Messages you've sent | | **Snoozed** | Messages you've temporarily hidden to deal with later | | **Archived** | Messages you've filed away for reference | Click any message thread to open the full conversation. The thread view shows all related messages in chronological order. ### Contacts Manage your contact database. Store names, email addresses, phone numbers, and notes about the people you communicate with. * View all contacts in a searchable list * Click a contact to see their full profile and communication history * Create, edit, and delete contacts ### Email Addresses Manage the email accounts Bizzy sends and receives on behalf of. Connect Google (Gmail) or Microsoft (Outlook / Office 365) via OAuth, or create an address on a verified custom domain. From this page you can view sync status, pause or disconnect an account, and update provider settings. ### Phone Numbers Buy and manage phone numbers via Telnyx for SMS. The page shows connected numbers, their messaging capabilities, and recording and routing settings. ### Domains Manage custom email domains for your organization. This section handles: * Domain registration and verification * DNS configuration * WHOIS contact management Domain management is typically handled by administrators. See the [Organization Setup](/admin-guide/organization/setup) guide for details. ### Automations Create and manage automated workflows that respond to incoming messages. * View all automations and their status (active, paused, completed) * Create new automations with triggers, conditions, and actions * Monitor automation execution history ### Agents AI agents that can help process and respond to communications. * View configured agents * Monitor agent activity and conversations * Configure agent behavior and permissions ### Files Upload, store, and manage files within Bizzy. * Upload documents and attachments * Generate shareable links * Organize files into folders ## Header Bar The header bar at the top of the screen provides: ### Organization Switcher If you belong to multiple organizations, click the organization name in the header to switch between them. Each organization has its own: * Contacts and customers * Email resources * Automations and settings * Team members ### Search Use the search bar to quickly find: * Messages by content or sender * Contacts by name or email * Files by name ### Account Menu Click your profile icon to access: * Profile settings (name, email, timezone) * Organization settings * Sign out ## Working with Messages ### Thread View When you click a message in the inbox, it opens in thread view: * All messages in the conversation are shown chronologically * You can reply directly from the thread * Related contacts are linked automatically ### Message Actions From any message, you can: * **Reply** - Send a response * **Archive** - Move to archived messages * **Snooze** - Hide temporarily and resurface later * **Delete** - Remove permanently ## Mobile Access Bizzy is a responsive web application that works on tablets and mobile devices. While there's no dedicated mobile app, you can: * Access the full platform from your mobile browser * Add Bizzy to your home screen for app-like experience * Receive notifications if enabled in your browser For the best experience on mobile, use a modern browser like Chrome or Safari. ## Keyboard Shortcuts Speed up your workflow with keyboard shortcuts: | Shortcut | Action | | ------------ | ------------------ | | `G` then `I` | Go to Inbox | | `G` then `C` | Go to Contacts | | `G` then `S` | Go to Sent | | `/` | Focus search | | `?` | Show all shortcuts | ## Next Steps Learn about organizations, contacts, and messages Connect email and manage your inbox # Quickstart Source: https://docs.bizzyco.ai/get-started/quickstart Get up and running with Bizzy in 5 minutes This guide walks you through setting up Bizzy and connecting your first email account. By the end, you'll have a working inbox ready to manage your business communications. ## Prerequisites Before you begin, you'll need: * A Google or Microsoft email account to connect * A modern web browser (Chrome, Firefox, Safari, or Edge) ## Step 1: Create Your Account Go to [bizzyco.ai](https://www.bizzyco.ai) and click **Get Started** or **Sign In**. Create an account using your email address or sign in with Google/Microsoft. If you signed up with email, check your inbox for a verification link and click it to confirm your account. ## Step 2: Create an Organization Organizations are how Bizzy groups users and data. Every account needs at least one organization. After signing in for the first time, you'll be prompted to create an organization. Enter a name (e.g., your company name or "Personal"). Click **Create** to finish. You'll be taken to your new organization's dashboard. You can create multiple organizations later if you need to separate work and personal communications, or manage different businesses. ## Step 3: Work Through the Setup Checklist Your new organization's home page shows a **Setup checklist** card with the seven steps that turn a blank workspace into a working AI-powered inbox: 1. Complete your business profile 2. Connect your email 3. Add a custom domain 4. Connect a phone number 5. Add your first contact 6. Set up your first automation 7. Invite your teammates Each task auto-completes when you do the thing it asks for (for example, connecting an email provider completes "Connect your email"). When every task is complete or dismissed, the card silently disappears from the home page. You don't have to complete all seven today — this quickstart walks through the two that unlock the rest of the platform: connecting email and adding a contact. Everything else can wait until you need it. ## Step 4: Connect Your Email The **Connect your email** task is the first CTA on the checklist. On the home page, click **Connect email** on the Setup checklist. This takes you to the **Email Addresses** page. Click **Connect email** and select your provider (Google or Microsoft). You'll be redirected to Google or Microsoft to authorize Bizzy. Review the permissions and click **Allow** or **Accept**. Bizzy begins syncing your recent emails. This takes a few minutes depending on your inbox size. Bizzy uses OAuth — your credentials are never seen or stored. You can revoke access at any time from your provider's security settings. Once the email address is created, the **Connect your email** checklist task auto-completes. ## Step 5: Explore Your Inbox Once your email is connected, your messages appear in the inbox. Click **Inbox** in the sidebar to view your messages. Messages are organized into threads. Click any thread to view the full conversation. Use the tabs to switch between **Inbox**, **Sent**, **Snoozed**, and **Archived** messages. ## Step 6: Add Your First Contact Back on the home page, the next expanded task is **Add your first contact**. Click **Add contact** on the Setup checklist to jump to the **Contacts** page. Click **Add Contact** and fill in the details: name, email, phone number, and any notes. Click **Save**. The **Add your first contact** task auto-completes, and the home checklist moves the next incomplete task into the expanded slot. ## What's Next? You've successfully set up Bizzy! The next step is to see what makes Bizzy different — AI-powered automations. Build a working AI-powered support workflow from scratch — the best way to see Bizzy in action Understand how organizations, contacts, and automations fit together Learn your way around all the features in the dashboard Add colleagues to your organization ## First Steps Checklist Use this checklist to make sure you've completed the basics: * [ ] Created your Bizzy account * [ ] Set up your first organization * [ ] Completed the **Connect your email** setup task * [ ] Explored the inbox and viewed messages * [ ] Completed the **Add your first contact** setup task Need help? Contact us at [support@bizzyco.ai](mailto:support@bizzyco.ai) or check the rest of this documentation for detailed guides. # Tutorial: Handle Your First Support Email with AI Source: https://docs.bizzyco.ai/get-started/tutorial Build a working AI-powered support workflow from scratch in Bizzy In this tutorial, you'll set up Bizzy to automatically handle incoming support emails using AI. By the end, you'll have a working automation that acknowledges support requests, extracts key details, and saves the sender as a contact — all without you lifting a finger. This is how Bizzy is designed to work: you connect your communications, tell the AI what to do in plain English, and let it handle the rest. ## What you'll build You'll create a complete support email workflow that: 1. Detects incoming emails that look like support requests 2. Sends an immediate, personalized acknowledgment to the sender 3. Saves the sender as a contact if they're new By the end, you'll understand how Bizzy's core features — email, contacts, and automations — work together. ## Prerequisites * A Google or Microsoft email account you can use for testing * A modern web browser (Chrome, Firefox, Safari, or Edge) ## Step 1: Create your account and organization First, let's get you set up on Bizzy. Go to [bizzyco.ai](https://www.bizzyco.ai) and click **Get Started**. Create an account using your email or sign in with Google/Microsoft. After signing in, you'll be prompted to create an organization. Enter a name — this can be your company name, or something like "My Business" if you're just exploring. Click **Create**. You're now on your organization's dashboard. This is your home base — everything you do in Bizzy happens within this organization. The **Setup checklist** card lists the seven steps that get a new org ready; we'll complete two of them (connect your email, create an automation) as part of this tutorial. ## Step 2: Connect your email The **Connect your email** task is the first CTA on the Setup checklist. On the home page, click **Connect email** on the Setup checklist. This takes you to the **Email Addresses** page. Click **Connect email** and select your provider (Google or Microsoft). You'll be redirected to your provider to authorize Bizzy. Review the permissions and click **Allow** (Google) or **Accept** (Microsoft). Bizzy begins syncing your recent emails. This takes a few minutes depending on your inbox size. The address appears on the **Email Addresses** page with a sync indicator. Bizzy uses OAuth — it never sees or stores your email password. You can revoke access at any time from your provider's settings. Once the email address is created, the **Connect your email** setup task auto-completes. Once sync completes, click **Inbox** in the sidebar. You should see your recent emails. Take a moment to click through a few threads — this is the unified inbox where all your connected accounts appear together. ## Step 3: Create your first automation Now for the interesting part. You'll tell Bizzy to watch for incoming emails and respond to them using AI. Click **Automations** in the sidebar, then click **Create Automation**. Enter a descriptive name: **Support Email Auto-Acknowledgment**. Good names make it easy to find and manage your automations later. For the trigger event, enter: **New email received**. This tells Bizzy to run the automation every time an email arrives. This is where you tell the AI what to do — in plain English. Paste the following into the instructions field: ``` When a new email arrives: 1. If the email looks like a support request or question about our services, send a friendly acknowledgment reply: - Thank them for reaching out - Confirm we received their message - Let them know we'll respond within 24 hours - Keep the tone warm and professional - Keep the reply under 100 words - Sign off with "Best regards" and "The Support Team" 2. If the email is clearly not a support request (newsletters, marketing, automated notifications), do nothing. ``` Click **Save**. The automation is enabled by default and starts working immediately. Saving also auto-completes the **Set up your first automation** task on the home checklist. ## Step 4: Test it Let's see your automation in action. From a different email account (or ask a friend), send an email to the address you connected. Write something that looks like a support request, for example: > Subject: Help with my account > > Hi, I'm having trouble logging in to my dashboard. I keep getting an "invalid credentials" error even though I'm sure my password is correct. Can you help? Wait a minute or two, then check the **Inbox** in Bizzy. You should see: * The incoming support email in your inbox * An outgoing reply that the AI generated and sent automatically Click the thread to see the full conversation. The AI's reply should be a friendly acknowledgment that follows your instructions — thanking the sender, confirming receipt, and setting expectations. If the automation didn't trigger, check a few things: Is the automation enabled? (Look for the toggle on the Automations page.) Did the email finish syncing? Give it another minute and check the automation's execution history for any errors. ## Step 5: Check the results Let's verify everything worked end-to-end. Go to **Automations**, click your automation, and look at the execution history. You should see a successful execution with details about what the AI did. Click **Contacts** in the sidebar. If the sender was new, Bizzy may have automatically created a contact record for them. Click the contact to see their profile and the linked message history. ## What you've accomplished You've built a working AI-powered support workflow. Here's what's happening behind the scenes every time an email arrives: 1. Bizzy receives the email through your connected account 2. The automation detects a new message and triggers 3. The AI reads the email and evaluates your instructions 4. If it's a support request, the AI composes and sends a reply 5. The sender and message are linked in your contact database This is the core loop of Bizzy: **connect → automate → let AI handle it**. Every feature builds on this pattern. ## Next steps Now that you've seen Bizzy in action, here are some ways to go further: Learn how to fine-tune triggers, add conditions, and write better AI instructions Learn how organizations, contacts, messages, and automations fit together Organize your contacts with labels, notes, and detailed profiles Give AI assistants like Claude direct access to your Bizzy data # Authentication Source: https://docs.bizzyco.ai/mcp-server/authentication How AI agents authenticate to the Bizzy MCP server The Bizzy MCP server is a protected resource. Clients authenticate using **OAuth 2.1 with PKCE and Dynamic Client Registration (RFC 7591)**, following the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization). Modern MCP clients — Claude Desktop, Claude Code, Cursor, Windsurf, and the MCP Inspector — run the entire flow automatically. As an end user you only need to: 1. Point the client at `https://mcp.bizzyco.ai`. 2. Sign in to Bizzy when the consent screen opens in your browser. 3. Approve the consent screen, choosing which tool categories the client may use. The rest of this page describes the flow in detail for client developers and for anyone debugging a connection. ## How the flow works ``` Client → /mcp (or /sse) (no token) Server → 401 + WWW-Authenticate Client → /.well-known/oauth-protected-resource/mcp (route-scoped; host-level also available) Client → /.well-known/oauth-authorization-server Client → POST /oauth/register (Dynamic Client Registration) Client → /oauth/authorize (browser, with PKCE code_challenge) User → consent screen Server → redirect with auth code Client → POST /oauth/token (code + code_verifier) Server → access_token (+ refresh_token if offline_access) Client → /mcp or /sse (Authorization: Bearer ) ``` The handshake is plain OAuth 2.1; no Bizzy-specific extensions are involved. ## Discovery The server publishes two host-derived metadata documents. A client discovers everything else from these. | Endpoint | Purpose | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `/.well-known/oauth-protected-resource` | RFC 9728 protected-resource metadata. Lists the authorization server. | | `/.well-known/oauth-authorization-server` | RFC 8414 authorization-server metadata. Lists `/oauth/register`, `/oauth/authorize`, `/oauth/token`, supported scopes, and PKCE methods. | You can fetch them directly: ```bash theme={null} curl -s https://mcp.bizzyco.ai/.well-known/oauth-protected-resource | jq curl -s https://mcp.bizzyco.ai/.well-known/oauth-authorization-server | jq ``` ## 401 response shape A request to `/mcp` or `/sse` without a valid Bearer token returns HTTP `401` with a `WWW-Authenticate` header pointing back to a route-scoped protected-resource metadata URL on the same host: ```http theme={null} HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer realm="OAuth", resource_metadata="https://mcp.bizzyco.ai/.well-known/oauth-protected-resource/mcp", error="invalid_token", error_description="Missing or invalid access token" Content-Type: application/json {"error":"invalid_token","error_description":"Missing or invalid access token"} ``` The 401 — not a JSON-RPC error envelope — is the canonical signal that the client should run discovery and the OAuth flow. The `resource_metadata` URL is route-scoped (`/mcp` and `/sse` advertise their own metadata documents); a host-level document is also available at `/.well-known/oauth-protected-resource` for clients that prefer it. ## Dynamic Client Registration Clients register themselves at `POST /oauth/register` per RFC 7591. Registration is open (no admin approval required) but rate-limited to **10 requests per 60 seconds per IP**, so clients should cache the returned `client_id` (and any `client_secret`) and reuse it across launches rather than re-registering every time. Prefer the OS credential store (Keychain on macOS, Credential Manager on Windows, libsecret on Linux) over a plaintext file on disk, especially for `client_secret` values. ## PKCE The server requires PKCE on every authorization request and only accepts the `S256` code-challenge method. Plain PKCE is rejected — clients that send `code_challenge_method=plain` will fail the authorize step. ## Scopes Two scopes are advertised: | Scope | Required | Purpose | | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mcp` | Yes | Access to the MCP transport endpoints. | | `offline_access` | No | Issues a refresh token alongside the access token. Request only for persistent or background clients; omit for interactive one-shot use, since the 90-day refresh token is a longer-lived credential. | During consent the user also chooses which tool categories the client may call. The set of tools advertised over `tools/list` is filtered against that selection on every request. ## Token lifetime | Token | TTL | Notes | | ------------- | ------- | -------------------------------------------------------------- | | Access token | 60 min | Bearer token presented on `/mcp` and `/sse`. | | Refresh token | 90 days | Issued only when `offline_access` was granted; rotated on use. | Access tokens are refreshed via `POST /oauth/token` with `grant_type=refresh_token`. Refresh tokens rotate on every use per OAuth 2.1. ## Rate limits on the transport Once authenticated, `/mcp` and `/sse` are rate-limited to **100 requests per 60 seconds per (user, client)**. A throttled response is HTTP `429` with a JSON-RPC error body (`code: -32004`, `message: "Rate limit exceeded"`) and a `Retry-After` header. The server does not emit `X-RateLimit-*` headers. ## Reference * [MCP authorization spec (2025-06-18)](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization) * [RFC 9728 — OAuth 2.0 Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728) * [RFC 8414 — OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) * [RFC 7591 — Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) # Connection Guide Source: https://docs.bizzyco.ai/mcp-server/connection Connect AI agents to the Bizzy MCP server This guide covers how to connect AI agents to the Bizzy MCP server, including the available transports and troubleshooting common issues. ## Connection URL The MCP server is available at: ``` https://mcp.bizzyco.ai ``` ## Authentication Modern MCP clients (Claude Desktop, Claude Code, Cursor, Windsurf) handle OAuth 2.1 + PKCE automatically — point them at the connection URL above and they walk you through sign-in and consent. See [Authentication](/mcp-server/authentication) for the full flow. ## Transports The MCP server supports two transports: * **Streamable HTTP** — `https://mcp.bizzyco.ai/mcp`. The current MCP transport; recommended for new clients. * **Server-Sent Events (SSE)** — `https://mcp.bizzyco.ai/sse`. Kept for compatibility with clients that implement the earlier SSE transport. Pick whichever your client supports; you do not need to configure both. ## Health Check Verify the MCP server is available before connecting: ```bash theme={null} curl https://mcp.bizzyco.ai/health ``` Response: ```json theme={null} { "status": "ok" } ``` The health check endpoint doesn't require authentication. Use it to verify connectivity before attempting to establish an authenticated connection. ## Troubleshooting **Possible causes:** * Network connectivity issues * Firewall blocking outbound HTTPS * Incorrect URL **Solutions:** 1. Verify network connectivity: `curl https://mcp.bizzyco.ai/health` 2. Check firewall rules allow outbound HTTPS (port 443) 3. Ensure you're using `https://` not `http://` A 401 is the canonical signal that your client needs to run (or re-run) the OAuth flow. The `WWW-Authenticate` header on the response points to a route-scoped protected-resource metadata URL (e.g. `/.well-known/oauth-protected-resource/mcp`), which a spec-compliant client uses to start discovery. **Solutions:** 1. Confirm your client supports OAuth 2.1 + PKCE + Dynamic Client Registration. Most current MCP clients do. 2. Make sure you completed the consent screen in your browser. If you cancelled it, retry the connection from your client. 3. If the client looks stuck after a successful consent, remove and re-add the Bizzy server in the client so it re-registers via DCR. 4. See [Authentication](/mcp-server/authentication) for the full handshake. **Possible causes:** * Insufficient permissions for the requested tool * Monthly call limit exceeded * Account suspended **Solutions:** 1. Check the error message for details 2. Check your usage in the dashboard 3. Upgrade your plan if you've hit the monthly limit **Possible causes:** * Too many requests in a short period * Exceeding 100 requests per 60 seconds per (user, client) **Solutions:** 1. Implement request queuing or throttling 2. Use exponential backoff when retrying 3. Wait for the duration in the `Retry-After` response header before retrying **Possible causes:** * Network instability * Idle timeout * Server maintenance **Solutions:** 1. Implement automatic reconnection logic 2. Send periodic ping messages to keep the connection alive 3. Check [status.bizzyco.ai](https://status.bizzyco.ai) for service issues ## Session Management MCP connections are stateful. Each connection receives a unique session ID that persists for the duration of the connection. * **Session IDs** are generated automatically on connection * **Sessions expire** after extended idle periods * **Reconnections** create new sessions - previous session state is not preserved Design your agent to be stateless where possible. Don't rely on server-side session state persisting between tool calls. ## Next Steps Explore the complete list of MCP tools See examples of MCP integrations # Claude Desktop Source: https://docs.bizzyco.ai/mcp-server/integrations/claude Connect Bizzy to Claude Desktop using MCP This guide walks you through connecting the Bizzy MCP server to Claude Desktop, allowing Claude to access your contacts, messages, and other business data directly. ## Prerequisites Before you begin, ensure you have: * [Claude Desktop](https://claude.ai/download) installed * A Bizzy account ## Connect Claude Desktop ships with native support for streamable-HTTP MCP servers and runs the OAuth 2.1 + PKCE handshake for you. The custom-connector UI used below requires a recent Claude Desktop build — if you don't see **Connectors** under **Settings**, install the latest version from [claude.ai/download](https://claude.ai/download). 1. Open Claude Desktop and go to **Settings → Connectors → Add custom connector**. 2. Paste the Bizzy MCP URL as the server URL: ``` https://mcp.bizzyco.ai ``` 3. Click **Connect**. Claude Desktop opens a browser tab on `https://mcp.bizzyco.ai/oauth/authorize`. 4. Sign in to Bizzy (if you aren't already), then review the consent screen — choose which tool categories Claude Desktop may use, and decide whether to grant `offline_access` for a long-lived refresh token. 5. Approve. The browser hands control back to Claude Desktop and the connector goes green. See [Authentication](/mcp-server/authentication) if you want to understand the OAuth handshake in detail. ## Verification Once the connection is working: 1. Open a new conversation in Claude Desktop 2. Ask Claude: "What Bizzy tools do you have access to?" 3. Claude should list the available tools based on your permissions ## Example Prompts Once connected, you can ask Claude to interact with your Bizzy data: | Task | Example Prompt | | ----------------- | -------------------------------------------------------------------------------------- | | Find a contact | "Find the contact information for John Smith" | | Search messages | "Show me recent messages about the project proposal" | | View conversation | "What's the full email thread with [support@example.com](mailto:support@example.com)?" | | Create a contact | "Add a new contact for Jane Doe at [jane@example.com](mailto:jane@example.com)" | ## Troubleshooting **Possible causes:** * The connector wasn't approved in the consent screen * Tool categories were unchecked during consent * The connector is showing red in **Settings → Connectors** **Solutions:** 1. Open **Settings → Connectors** and confirm the Bizzy connector is green. 2. If it's red, click **Reconnect** and re-approve the consent screen. 3. If it's green but Claude can't see specific tools, remove and re-add the connector — during consent, make sure the relevant tool categories are checked. If the consent screen fails to load, check that you can reach `https://mcp.bizzyco.ai/.well-known/oauth-protected-resource` from your machine and that you're signed in to Bizzy in the same browser Claude Desktop opened. If the connector goes red after a successful approval, remove and re-add it — Claude Desktop will register a fresh OAuth client via Dynamic Client Registration. ## Next Steps Explore all available MCP tools Learn about MCP server authentication # Cursor IDE Source: https://docs.bizzyco.ai/mcp-server/integrations/cursor Connect Bizzy to Cursor using MCP This guide walks you through connecting the Bizzy MCP server to Cursor IDE, allowing Cursor's AI to access your contacts, messages, and other business data while coding. ## Prerequisites Before you begin, ensure you have: * [Cursor IDE](https://cursor.com/) installed * A Bizzy account ## Connect Cursor supports streamable-HTTP MCP servers and runs the OAuth 2.1 + PKCE handshake for you. 1. Add Bizzy to your Cursor MCP config. Use `.cursor/mcp.json` in a project directory, or `~/.cursor/mcp.json` for every project: ```json theme={null} { "mcpServers": { "bizzy": { "url": "https://mcp.bizzyco.ai/mcp" } } } ``` You can also add the server through **File → Preferences → Cursor Settings → MCP**, which writes the same JSON. 2. Restart Cursor. 3. The first time Cursor calls a Bizzy tool — or when you click **Connect** in the MCP settings — Cursor opens a browser tab for OAuth. 4. Sign in to Bizzy and approve the consent screen. Cursor stores the access token and the tools become available in chat. See [Authentication](/mcp-server/authentication) for details on the OAuth handshake. ## Verification To verify the connection is working: 1. Open Cursor's AI chat (Cmd+L or Ctrl+L) 2. Ask: "What Bizzy tools do you have access to?" 3. Cursor should list the available tools ## Example Usage Once connected, you can use Bizzy tools in your development workflow: | Task | Example Prompt | | --------------------- | ---------------------------------------------------- | | Find contact info | "Look up the contact details for our main client" | | Search communications | "Find all messages about the API integration" | | Review history | "Show the conversation history with the design team" | ## Troubleshooting **Possible causes:** * Configuration file in wrong location * Invalid JSON syntax * Cursor not restarted **Solutions:** 1. Verify the configuration file path 2. Validate your JSON syntax 3. Completely restart Cursor (not just reload window) If the OAuth browser tab fails to load, check that you can reach `https://mcp.bizzyco.ai/.well-known/oauth-protected-resource` from your machine. If Cursor shows a stale token error, remove the `bizzy` entry from your `mcp.json`, restart Cursor, and re-add it — that forces a fresh Dynamic Client Registration. See [Authentication](/mcp-server/authentication) for the underlying flow. Cursor currently supports MCP tools but not MCP resources. This means you can call Bizzy tools (like `createContact`, `listMessages`) but cannot access read-only MCP resources that some servers provide. ## Next Steps Explore all available MCP tools Learn about MCP server authentication # Integrations Overview Source: https://docs.bizzyco.ai/mcp-server/integrations/index Connect the Bizzy MCP Server to AI coding tools The Bizzy MCP server integrates with popular AI-powered development tools, allowing you to access your business data directly from your preferred coding environment. ## Supported Tools | Tool | Platform | Configuration | | ------------------------------------------------- | --------------------- | --------------------- | | [Claude Desktop](/mcp-server/integrations/claude) | macOS, Windows | Settings → Connectors | | [Cursor](/mcp-server/integrations/cursor) | macOS, Windows, Linux | `.cursor/mcp.json` | | [Windsurf](/mcp-server/integrations/windsurf) | macOS, Windows, Linux | `mcp_config.json` | ## Authentication Each of the clients listed above runs the OAuth 2.1 + PKCE handshake automatically. Point the client at `https://mcp.bizzyco.ai`, sign in to Bizzy in the browser tab that opens, and approve the consent screen. See [Authentication](/mcp-server/authentication) for the full flow. ## Integration Guides Connect to Anthropic's Claude Desktop app Integrate with Cursor IDE Set up Windsurf with Cascade ## Next Steps See what tools are available Learn about MCP server authentication # Windsurf Source: https://docs.bizzyco.ai/mcp-server/integrations/windsurf Connect Bizzy to Windsurf using MCP This guide walks you through connecting the Bizzy MCP server to Windsurf, allowing Cascade (Windsurf's AI) to access your contacts, messages, and other business data. ## Prerequisites Before you begin, ensure you have: * [Windsurf](https://windsurf.com/) installed * A Bizzy account ## Connect Windsurf supports streamable-HTTP MCP servers and runs the OAuth 2.1 + PKCE handshake for you. 1. Add Bizzy to `~/.codeium/windsurf/mcp_config.json`: ```json theme={null} { "mcpServers": { "bizzy": { "serverUrl": "https://mcp.bizzyco.ai/mcp" } } } ``` Or, from Windsurf, open the Command Palette with `Cmd+Shift+P` (Mac) / `Ctrl+Shift+P` (Windows/Linux), run **Open Windsurf Settings**, navigate to **Cascade → Plugins**, and add Bizzy as a custom MCP plugin pointing at `https://mcp.bizzyco.ai/mcp` — Windsurf writes the same JSON. 2. Restart Windsurf. 3. The first time Cascade uses a Bizzy tool — or when you click **Connect** in the plugin entry — Windsurf opens a browser tab for OAuth. 4. Sign in to Bizzy and approve the consent screen. Cascade then has access to the tools you granted. See [Authentication](/mcp-server/authentication) for details on the OAuth handshake. ## Verification To verify the connection is working: 1. Open Cascade (Windsurf's AI assistant) 2. Ask: "What Bizzy tools do you have access to?" 3. Cascade should list the available tools ## Example Usage Once connected, you can use Bizzy tools in Cascade: | Task | Example Prompt | | --------------------- | ------------------------------------------------ | | Find contact info | "Look up contact information for our vendor" | | Search communications | "Find messages mentioning the deployment issue" | | View thread | "Show the full conversation thread with support" | ## Troubleshooting **Possible causes:** * Configuration file in wrong location * Invalid JSON syntax * Windsurf not restarted **Solutions:** 1. Verify the file is at `~/.codeium/windsurf/mcp_config.json` 2. Validate your JSON syntax 3. Completely restart Windsurf If the OAuth browser tab fails to load, check that you can reach `https://mcp.bizzyco.ai/.well-known/oauth-protected-resource` from your machine. If Cascade shows a stale token error, remove the `bizzy` entry from `~/.codeium/windsurf/mcp_config.json`, restart Windsurf, and re-add it — that forces a fresh Dynamic Client Registration. See [Authentication](/mcp-server/authentication) for the underlying flow. Cascade has a limit of 100 total tools. If you have many MCP servers configured, you may need to disable some tools. **Solution:** 1. Open **Windsurf Settings**, navigate to **Cascade → Plugins** 2. Navigate to the Tools tab 3. Toggle off tools you don't need ## Next Steps Explore all available MCP tools Learn about MCP server authentication # Introduction Source: https://docs.bizzyco.ai/mcp-server/introduction Connect AI agents to Bizzy using the Model Context Protocol The Bizzy MCP Server provides AI agents with direct access to your business communication platform. Using the Model Context Protocol (MCP), agents can manage contacts, customers, messages, automations, and more through a standardized interface. ## What is MCP? The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard that enables AI assistants to interact with external systems through a unified interface. Instead of building custom integrations for each AI platform, MCP provides a single connection point that works with Claude, GPT-based agents, and other MCP-compatible AI systems. MCP uses a client-server architecture where AI agents connect as clients to the Bizzy MCP server. The server exposes tools that agents can discover and invoke to perform actions on your behalf. ## Why Use Bizzy's MCP Server? * **Direct AI Access** - Give your AI agents the ability to read and manage your business data without building custom APIs * **Permission Control** - Fine-grained permissions let you control exactly what each agent can access * **Real-Time Operations** - Agents can create contacts, send messages, manage customers, and automate workflows in real-time * **Standardized Protocol** - Works with any MCP-compatible AI assistant or automation platform ## Available Tools The MCP server provides **106 tools** across 12 resource categories: | Category | Tools | Description | | ------------------- | ----- | ------------------------------------------------------------ | | **Automations** | 7 | Create, update, and inspect automations and their executions | | **Businesses** | 20 | Business profile, offerings, and online/physical presences | | **Contacts** | 20 | Contacts and their emails, phones, and addresses | | **Customers** | 10 | Customer records and customer transactions | | **Domains** | 15 | Domains, domain contacts, and domain registrations | | **Email Addresses** | 2 | List and read connected email addresses | | **Email Templates** | 7 | Manage templates, render previews, and send templated email | | **Files** | 5 | Upload, download, list, search, and delete files | | **Folders** | 2 | Create and list folders | | **Messages** | 6 | Read messages, threads, and attachments; update status | | **Phone Numbers** | 2 | List and read connected phone numbers | | **Tasks** | 10 | Task CRUD, search, and assignee management | ## Use Cases ### AI Assistants Connect Claude Desktop or other AI assistants to Bizzy. Your assistant can then: * Look up contact information during conversations * Create follow-up tasks after meetings * Search through message history * Draft and queue messages for review ### Workflow Automation Build automated workflows that leverage AI decision-making: * Process incoming leads and create customer records * Categorize and route messages to appropriate team members * Generate reports from business data * Trigger automations based on AI analysis ### Custom Integrations Develop custom AI-powered applications that interact with Bizzy: * Build chatbots that can access customer information * Create AI agents that manage your inbox * Integrate with other business tools through AI orchestration ## Transports The MCP server supports two transports. Pick the one your client expects: * **Streamable HTTP** at `/mcp` — the current MCP transport; recommended for new clients. * **Server-Sent Events (SSE)** at `/sse` — kept for compatibility with clients that implement the earlier SSE transport. See the [Connection Guide](/mcp-server/connection) for full URLs and setup details. ## Next Steps Learn how MCP clients authenticate to the server Connect your AI agents to the MCP server # Automation Tools Source: https://docs.bizzyco.ai/mcp-server/tools/automations Create, manage, and inspect organization automations and their executions The Bizzy MCP server provides 7 tools for managing automations and inspecting their execution history. These tools are organized into two categories: automations and executions. ## Automations Core tools for creating, reading, updating, and deleting automations. ### createAutomation Create a new automation with trigger event, conditions, and instructions. **Permission:** `automations:write` **Parameters:** | Name | Type | Required | Description | | -------------- | ----------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Yes | The name of the automation | | `description` | string | No | A description of what the automation does | | `triggerEvent` | string \| null | No | The event type that triggers this automation (e.g., "message", "contact", "customer") | | `condition` | `Record` | No | A key-value map of conditions that must be met for the automation to execute. Values must be strings or booleans (no nesting) | | `instructions` | string | Yes | Natural language instructions describing what the automation should do | | `createdBy` | string (UUID) | No | The user ID who created the automation | | `enabled` | boolean | No | Whether the automation is enabled (defaults to true) | After creation, the automation is generated and evaluated asynchronously. System-managed fields like generated code, evaluation results, group metadata, and execution counters are populated by the platform — do not pass them in here, as they are overwritten or ignored. **Returns:** The created automation object. *** ### getAutomation Get details of a specific automation by ID. **Permission:** `automations:read` **Parameters:** | Name | Type | Required | Description | | -------------- | ------------- | -------- | ------------------------------------ | | `automationId` | string (UUID) | Yes | The ID of the automation to retrieve | **Returns:** The automation object, or `null` if not found. *** ### listAutomations List automations with pagination. **Permission:** `automations:read` **Parameters:** | Name | Type | Required | Default | Description | | -------- | ------ | -------- | ------- | -------------------------------------------- | | `limit` | number | No | 20 | Number of automations to return (1-100) | | `offset` | number | No | 0 | Number of automations to skip for pagination | **Returns:** ```json theme={null} { "automations": [...], "count": 42, "limit": 20, "offset": 0 } ``` *** ### updateAutomation Update an existing automation - all fields are optional except `automationId`. **Permission:** `automations:write` **Parameters:** | Name | Type | Required | Description | | -------------- | ----------------------------------- | -------- | ---------------------------------------------------------------------- | | `automationId` | string (UUID) | Yes | The ID of the automation to update | | `name` | string | No | Update the automation name | | `description` | string | No | Update the description | | `triggerEvent` | string | No | Update the trigger event | | `condition` | `Record` | No | Update the conditions. Values must be strings or booleans (no nesting) | | `instructions` | string | No | Update the instructions | | `createdBy` | string (UUID) | No | Update the creator | | `enabled` | boolean | No | Enable or disable the automation | **Returns:** The updated automation object. *** ### deleteAutomation Delete an automation (soft delete). **Permission:** `automations:delete` **Parameters:** | Name | Type | Required | Description | | -------------- | ------------- | -------- | ---------------------------------- | | `automationId` | string (UUID) | Yes | The ID of the automation to delete | **Returns:** The deleted automation object. *** ## Executions Tools for inspecting individual automation executions and their history. ### getAutomationExecution Get details of a specific automation execution by ID. **Permission:** `automations.executions:read` **Parameters:** | Name | Type | Required | Description | | ------------- | ------------- | -------- | ---------------------------------------------- | | `executionId` | string (UUID) | Yes | The ID of the automation execution to retrieve | **Returns:** The automation execution object, or `null` if not found. *** ### listAutomationExecutions List automation executions with pagination, optionally filtered by automation ID. **Permission:** `automations.executions:read` **Parameters:** | Name | Type | Required | Default | Description | | -------------- | ------------- | -------- | ------- | ------------------------------------------- | | `automationId` | string (UUID) | No | - | Filter executions by automation ID | | `limit` | number | No | 20 | Number of executions to return (1-100) | | `offset` | number | No | 0 | Number of executions to skip for pagination | **Returns:** ```json theme={null} { "executions": [...], "count": 17, "limit": 20, "offset": 0 } ``` *** ## Next Steps Manage contacts and their associated data Learn how MCP clients authenticate to the server # Business Tools Source: https://docs.bizzyco.ai/mcp-server/tools/businesses Manage businesses, profiles, offerings, and online and physical presences The Bizzy MCP server provides 20 tools for managing businesses, their profile, offerings, and online and physical presences. These tools are organized into five categories: businesses, business profile, offerings, online presences, and physical presences. ## Businesses Core tools for reading and updating businesses. Businesses are provisioned with the organization, so there are no `create` or `delete` tools. ### getBusiness Get details for a specific business by ID. **Permission:** `businesses:read` **Parameters:** | Name | Type | Required | Description | | ------------ | ------------- | -------- | ------------------------------ | | `businessId` | string (UUID) | Yes | ID of the business to retrieve | **Returns:** Business object, or `null` if not found. *** ### listBusinesses List all businesses in the organization. **Permission:** `businesses:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | --------------------------------------------- | | `limit` | number | No | 10 | Maximum number of items to return (max: 100) | | `offset` | number | No | 0 | Number of items to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | **Returns:** ```json theme={null} { "businesses": [...], "count": 3, "limit": 10, "offset": 0 } ``` *** ### updateBusiness Update an existing business by ID. **Permission:** `businesses:write` **Parameters:** | Name | Type | Required | Description | | ------ | ------------- | -------- | ---------------------------- | | `id` | string (UUID) | Yes | ID of the business to update | | `name` | string | No | The name of the business | Stripe Connect-related fields on the business record are managed by the Stripe integration — do not pass them in here, as they are overwritten or ignored. **Returns:** The updated business object. *** ## Business Profile Tools for reading and updating the descriptive profile of a business. The profile is created alongside the business, so there is no `create`, `list`, or `delete` tool — there is exactly one profile per business. ### getBusinessProfile Get the detailed profile of a business by ID. **Permission:** `businesses.profiles:read` **Parameters:** | Name | Type | Required | Description | | ------------ | ------------- | -------- | ----------------------------------------------------------------------------- | | `businessId` | string (UUID) | Yes | ID of the business whose profile to retrieve (profile shares the business ID) | **Returns:** Business profile object, or `null` if not found. *** ### updateBusinessProfile Update the profile information of a business. **Permission:** `businesses.profiles:write` **Parameters:** | Name | Type | Required | Description | | ------------- | -------------------------------- | -------- | ------------------------------------------------------ | | `id` | string (UUID) | Yes | The ID of the business profile to update | | `description` | string \| null | No | A new detailed description of the business (optional) | | `industries` | string\[] \| null | No | New industries the business operates in (optional) | | `data` | Record\ \| null | No | Additional business data as key-value pairs (optional) | **Returns:** The updated business profile object. *** ## Offerings Tools for managing the products and services a business offers. ### createBusinessOffering Create a new product or service offering for a business. **Permission:** `businesses.offerings:write` **Parameters:** | Name | Type | Required | Description | | ------------- | --------------- | -------- | -------------------------------------------------------------- | | `businessId` | string (UUID) | Yes | The ID of the business this offering belongs to | | `name` | string | Yes | The name of the offering | | `description` | string \| null | No | A description of the offering (optional) | | `isService` | boolean \| null | No | Whether this is a service (true) or product (false) - optional | **Returns:** The created business offering object. *** ### getBusinessOffering Get details of a specific business offering by ID. **Permission:** `businesses.offerings:read` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | ------------------------------------------- | | `id` | string (UUID) | Yes | The ID of the business offering to retrieve | **Returns:** Business offering object, or `null` if not found. *** ### listBusinessOfferings List all products and services offered by a business. **Permission:** `businesses.offerings:read` **Parameters:** | Name | Type | Required | Default | Description | | ------------ | ------------- | -------- | ------- | -------------------------------------------- | | `businessId` | string (UUID) | Yes | - | The ID of the business to list offerings for | | `limit` | number | No | 100 | Maximum number of results | | `offset` | number | No | 0 | Offset for pagination | **Returns:** ```json theme={null} { "offerings": [...], "count": 12, "limit": 100, "offset": 0 } ``` *** ### updateBusinessOffering Update details of an existing business offering. **Permission:** `businesses.offerings:write` **Parameters:** | Name | Type | Required | Description | | ------------- | --------------- | -------- | -------------------------------------------------------------- | | `id` | string (UUID) | Yes | The ID of the business offering to update | | `name` | string | No | The new name for the offering (optional) | | `description` | string \| null | No | A new description for the offering (optional) | | `isService` | boolean \| null | No | Whether this is a service (true) or product (false) - optional | **Returns:** The updated business offering object. *** ### deleteBusinessOffering Delete a business offering (soft delete). **Permission:** `businesses.offerings:delete` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | ----------------------------------------- | | `id` | string (UUID) | Yes | The ID of the business offering to delete | **Returns:** The deleted business offering object. *** ## Online Presences Tools for managing a business's online presence — websites, social media profiles, marketplace listings, and similar. ### createBusinessOnlinePresence Create a new online presence for a business (website, social media, marketplace, etc.). **Permission:** `businesses.online-presences:write` **Parameters:** | Name | Type | Required | Description | | ------------- | -------------- | -------- | ---------------------------------------------------------------------------------------- | | `businessId` | string (UUID) | Yes | The ID of the business this online presence belongs to | | `name` | string | Yes | The name of the online presence (e.g., "Company Website", "Facebook Page") | | `url` | string \| null | No | The URL of the online presence (optional) | | `description` | string \| null | No | A description of the online presence (optional) | | `type` | string \| null | No | The type of online presence (e.g., "website", "social\_media", "marketplace") (optional) | | `provider` | string \| null | No | The provider or platform (e.g., "facebook", "linkedin", "amazon") (optional) | **Returns:** The created business online presence object. *** ### getBusinessOnlinePresence Get details of a specific business online presence by ID. **Permission:** `businesses.online-presences:read` **Parameters:** | Name | Type | Required | Description | | ------------------ | ------------- | -------- | -------------------------------------------------- | | `onlinePresenceId` | string (UUID) | Yes | The ID of the business online presence to retrieve | **Returns:** Business online presence object, or `null` if not found. *** ### listBusinessOnlinePresences List all online presences for a specific business. **Permission:** `businesses.online-presences:read` **Parameters:** | Name | Type | Required | Default | Description | | ------------ | ------------- | -------- | ------- | --------------------------------------------------- | | `businessId` | string (UUID) | Yes | - | The ID of the business to list online presences for | | `limit` | number | No | 100 | Maximum number of results | | `offset` | number | No | 0 | Offset for pagination | **Returns:** ```json theme={null} { "onlinePresences": [...], "count": 4, "limit": 100, "offset": 0 } ``` *** ### updateBusinessOnlinePresence Update an existing business online presence - all fields are optional except onlinePresenceId. **Permission:** `businesses.online-presences:write` **Parameters:** | Name | Type | Required | Description | | ------------------ | -------------- | -------- | ------------------------------------------------ | | `onlinePresenceId` | string (UUID) | Yes | The ID of the business online presence to update | | `name` | string | No | Update the online presence name | | `url` | string \| null | No | Update the URL | | `description` | string \| null | No | Update the description | | `type` | string \| null | No | Update the type of online presence | | `provider` | string \| null | No | Update the provider or platform | **Returns:** The updated business online presence object. *** ### deleteBusinessOnlinePresence Delete a business online presence (soft delete). **Permission:** `businesses.online-presences:delete` **Parameters:** | Name | Type | Required | Description | | ------------------ | ------------- | -------- | ------------------------------------------------ | | `onlinePresenceId` | string (UUID) | Yes | The ID of the business online presence to delete | **Returns:** The deleted business online presence object. *** ## Physical Presences Tools for managing a business's physical locations — offices, stores, warehouses, and similar. ### createBusinessPhysicalPresence Create a new physical location (office, store, warehouse, etc.) for a business. **Permission:** `businesses.physical-presences:write` **Parameters:** | Name | Type | Required | Description | | ------------- | -------------- | -------- | ------------------------------------------------------------------------- | | `businessId` | string (UUID) | Yes | The ID of the business this physical location belongs to | | `name` | string | Yes | The name of the physical location (e.g., "Main Office", "Downtown Store") | | `description` | string \| null | No | A description of the physical location (optional) | | `address` | string \| null | No | The full address of the physical location (optional) | **Returns:** The created business physical presence object. *** ### getBusinessPhysicalPresence Get details of a specific business physical location by ID. **Permission:** `businesses.physical-presences:read` **Parameters:** | Name | Type | Required | Description | | -------------------- | ------------- | -------- | ---------------------------------------------------- | | `physicalPresenceId` | string (UUID) | Yes | The ID of the business physical presence to retrieve | **Returns:** Business physical presence object, or `null` if not found. *** ### listBusinessPhysicalPresences List all physical locations (offices, stores, etc.) for a business. **Permission:** `businesses.physical-presences:read` **Parameters:** | Name | Type | Required | Default | Description | | ------------ | ------------- | -------- | ------- | ----------------------------------------------------- | | `businessId` | string (UUID) | Yes | - | The ID of the business to list physical locations for | | `limit` | number | No | 100 | Maximum number of results | | `offset` | number | No | 0 | Offset for pagination | **Returns:** ```json theme={null} { "physicalPresences": [...], "count": 2, "limit": 100, "offset": 0 } ``` *** ### updateBusinessPhysicalPresence Update an existing business physical location - all fields are optional except physicalPresenceId. **Permission:** `businesses.physical-presences:write` **Parameters:** | Name | Type | Required | Description | | -------------------- | -------------- | -------- | -------------------------------------------------- | | `physicalPresenceId` | string (UUID) | Yes | The ID of the business physical presence to update | | `name` | string | No | Update the physical location name | | `description` | string \| null | No | Update the description | | `address` | string \| null | No | Update the address | **Returns:** The updated business physical presence object. *** ### deleteBusinessPhysicalPresence Delete a business physical location (soft delete). **Permission:** `businesses.physical-presences:delete` **Parameters:** | Name | Type | Required | Description | | -------------------- | ------------- | -------- | -------------------------------------------------- | | `physicalPresenceId` | string (UUID) | Yes | The ID of the business physical presence to delete | **Returns:** The deleted business physical presence object. *** ## Next Steps Manage customers and their relationships with your business Learn how MCP clients authenticate to the server # Contact Tools Source: https://docs.bizzyco.ai/mcp-server/tools/contacts Manage contacts, emails, addresses, and phone numbers The Bizzy MCP server provides 21 tools for managing contacts and their associated data. These tools are organized into four categories: contact management, emails, addresses, and phone numbers. ## Contact Management Core tools for creating, reading, updating, and deleting contacts. ### createContact Create a new contact with name, email, phone, and company information. **Permission:** `contacts:write` **Parameters:** | Name | Type | Required | Description | | -------------- | --------- | -------- | ------------------------------------ | | `firstName` | string | No | The contact's first name | | `lastName` | string | No | The contact's last name | | `name` | string | No | Full display name | | `company` | string | No | Company or organization affiliation | | `jobTitle` | string | No | Job title or role | | `title` | string | No | Honorific or prefix (e.g., Mr, Dr) | | `picture` | string | No | URL to the contact's profile picture | | `notes` | string | No | Internal notes and comments | | `emails` | string\[] | No | Array of email addresses | | `phoneNumbers` | string\[] | No | Array of phone numbers | | `addresses` | object\[] | No | Array of address objects | **Address object:** | Name | Type | Required | Description | | ------------ | ------ | -------- | --------------------- | | `country` | string | Yes | Country | | `city` | string | Yes | City | | `label` | string | No | Label for the address | | `address1` | string | No | Address line 1 | | `address2` | string | No | Address line 2 | | `state` | string | No | State | | `postalCode` | string | No | Postal code | **Returns:** The created contact object with all associated data. *** ### getContact Get details of a specific contact by ID. **Permission:** `contacts:read` **Parameters:** | Name | Type | Required | Description | | ----------- | ------------- | -------- | --------------------------------- | | `contactId` | string (UUID) | Yes | The ID of the contact to retrieve | **Returns:** Contact object with all associated addresses, emails, and phone numbers. *** ### listContacts List contacts in the organization with pagination. **Permission:** `contacts:read` **Parameters:** | Name | Type | Required | Default | Description | | -------- | ------ | -------- | ------- | ----------------------------------------- | | `limit` | number | No | 50 | Number of contacts to return (1-100) | | `offset` | number | No | 0 | Number of contacts to skip for pagination | **Returns:** ```json theme={null} { "contacts": [...], "count": 150, "limit": 50, "offset": 0 } ``` *** ### updateContact Update an existing contact. **Permission:** `contacts:write` **Parameters:** | Name | Type | Required | Description | | ----------- | ------------- | -------- | ------------------------------- | | `contactId` | string (UUID) | Yes | The ID of the contact to update | | `firstName` | string | No | Update the contact's first name | | `lastName` | string | No | Update the contact's last name | | `name` | string | No | Update the full display name | | `company` | string | No | Update the company | | `jobTitle` | string | No | Update the job title | | `title` | string | No | Update the honorific | | `picture` | string | No | Update the profile picture URL | | `notes` | string | No | Update internal notes | **Returns:** The updated contact object. *** ### deleteContact Delete a contact (soft delete). **Permission:** `contacts:delete` **Parameters:** | Name | Type | Required | Description | | ----------- | ------------- | -------- | ------------------------------- | | `contactId` | string (UUID) | Yes | The ID of the contact to delete | **Returns:** The deleted contact object. *** ## Contact Emails Tools for managing email addresses associated with contacts. ### createContactEmail Create a new email address for a contact. **Permission:** `contacts.emails:write` **Parameters:** | Name | Type | Required | Description | | ----------- | ------------- | -------- | -------------------------------- | | `contactId` | string (UUID) | Yes | The ID of the contact | | `email` | string | Yes | The email address | | `label` | string | No | Label (e.g., "work", "personal") | **Returns:** The created contact email object. *** ### getContactEmail Get details of a specific contact email. **Permission:** `contacts.emails:read` **Parameters:** | Name | Type | Required | Description | | --------- | ------------- | -------- | ------------------------------- | | `emailId` | string (UUID) | Yes | The ID of the email to retrieve | **Returns:** Contact email object with all details. *** ### listContactEmails List all email addresses for a specific contact. **Permission:** `contacts.emails:read` **Parameters:** | Name | Type | Required | Description | | ----------- | ------------- | -------- | --------------------- | | `contactId` | string (UUID) | Yes | The ID of the contact | **Returns:** ```json theme={null} { "emails": [...], "count": 3 } ``` *** ### updateContactEmail Update an existing contact email address. **Permission:** `contacts.emails:write` **Parameters:** | Name | Type | Required | Description | | --------- | ------------- | -------- | ----------------------------- | | `emailId` | string (UUID) | Yes | The ID of the email to update | | `email` | string | No | Update the email address | | `label` | string | No | Update the label | **Returns:** The updated contact email object. *** ### deleteContactEmail Delete a contact email address. **Permission:** `contacts.emails:delete` **Parameters:** | Name | Type | Required | Description | | --------- | ------------- | -------- | ----------------------------- | | `emailId` | string (UUID) | Yes | The ID of the email to delete | **Returns:** The deleted contact email object. *** ## Contact Addresses Tools for managing physical addresses associated with contacts. ### createContactAddress Create a new address for a contact. **Permission:** `contacts.addresses:write` **Parameters:** | Name | Type | Required | Description | | ------------ | ------------- | -------- | --------------------- | | `contactId` | string (UUID) | Yes | The ID of the contact | | `country` | string | Yes | Country | | `city` | string | Yes | City | | `label` | string | Yes | Label for the address | | `address1` | string | No | Address line 1 | | `address2` | string | No | Address line 2 | | `state` | string | No | State | | `postalCode` | string | No | Postal code | **Returns:** The created contact address object. *** ### getContactAddress Get details of a specific contact address. **Permission:** `contacts.addresses:read` **Parameters:** | Name | Type | Required | Description | | ----------- | ------------- | -------- | --------------------------------- | | `addressId` | string (UUID) | Yes | The ID of the address to retrieve | **Returns:** Contact address object with all details. *** ### listContactAddresses List all addresses for a specific contact. **Permission:** `contacts.addresses:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------------- | -------- | ------- | ---------------------------- | | `contactId` | string (UUID) | Yes | - | The ID of the contact | | `limit` | number | No | 10 | Maximum number of results | | `offset` | number | No | 0 | Offset for pagination | | `sortOrder` | string | No | "asc" | Sort order ("asc" or "desc") | **Returns:** Array of contact address objects. *** ### updateContactAddress Update an existing contact address. **Permission:** `contacts.addresses:write` **Parameters:** | Name | Type | Required | Description | | ------------ | ------------- | -------- | ------------------------------- | | `addressId` | string (UUID) | Yes | The ID of the address to update | | `country` | string | No | Update the country | | `city` | string | No | Update the city | | `label` | string | No | Update the label | | `address1` | string | No | Update address line 1 | | `address2` | string | No | Update address line 2 | | `state` | string | No | Update the state | | `postalCode` | string | No | Update the postal code | **Returns:** The updated contact address object. *** ### deleteContactAddress Delete a contact address. **Permission:** `contacts.addresses:delete` **Parameters:** | Name | Type | Required | Description | | ----------- | ------------- | -------- | ------------------------------- | | `addressId` | string (UUID) | Yes | The ID of the address to delete | **Returns:** The deleted contact address object. *** ## Contact Phone Numbers Tools for managing phone numbers associated with contacts. ### createContactPhoneNumber Create a new phone number for a contact. **Permission:** `contacts.phoneNumbers:write` **Parameters:** | Name | Type | Required | Description | | ---------------- | ------------- | -------- | ------------------------------ | | `contactId` | string (UUID) | Yes | The ID of the contact | | `phoneNumber` | string | Yes | The phone number | | `countryCode` | string | Yes | Country code | | `nationalNumber` | string | Yes | National number | | `label` | string | Yes | Label (e.g., "mobile", "work") | **Returns:** The created contact phone number object. *** ### getContactPhoneNumber Get details of a specific contact phone number. **Permission:** `contacts.phoneNumbers:read` **Parameters:** | Name | Type | Required | Description | | --------------- | ------------- | -------- | -------------------------------------- | | `phoneNumberId` | string (UUID) | Yes | The ID of the phone number to retrieve | **Returns:** Contact phone number object with all details. *** ### listContactPhoneNumbers List all phone numbers for a specific contact. **Permission:** `contacts.phoneNumbers:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------------- | -------- | ------- | ---------------------------- | | `contactId` | string (UUID) | Yes | - | The ID of the contact | | `limit` | number | No | 10 | Maximum number of results | | `offset` | number | No | 0 | Offset for pagination | | `sortOrder` | string | No | "asc" | Sort order ("asc" or "desc") | **Returns:** Array of contact phone number objects. *** ### updateContactPhoneNumber Update an existing contact phone number. **Permission:** `contacts.phoneNumbers:write` **Parameters:** | Name | Type | Required | Description | | ---------------- | ------------- | -------- | ------------------------------------ | | `phoneNumberId` | string (UUID) | Yes | The ID of the phone number to update | | `phoneNumber` | string | No | Update the phone number | | `countryCode` | string | No | Update the country code | | `nationalNumber` | string | No | Update the national number | | `label` | string | No | Update the label | **Returns:** The updated contact phone number object. *** ### deleteContactPhoneNumber Delete a contact phone number. **Permission:** `contacts.phoneNumbers:delete` **Parameters:** | Name | Type | Required | Description | | --------------- | ------------- | -------- | ------------------------------------ | | `phoneNumberId` | string (UUID) | Yes | The ID of the phone number to delete | **Returns:** The deleted contact phone number object. *** ## Next Steps Manage messages and threads Learn how MCP clients authenticate to the server # Customer Tools Source: https://docs.bizzyco.ai/mcp-server/tools/customers Manage customers and their financial transactions The Bizzy MCP server provides 10 tools for managing customers and their transactions. These tools are organized into two categories: customers and customer transactions. ## Customers Core tools for creating, reading, updating, and deleting customer records. ### createCustomer Create a new customer record with business association and contact information. **Permission:** `customers:write` **Parameters:** | Name | Type | Required | Description | | --------------- | --------------------- | -------- | ------------------------------------------------------ | | `businessId` | string (UUID) | Yes | The ID of the business this customer belongs to | | `type` | string | Yes | Customer type (e.g., individual, business, enterprise) | | `contactId` | string (UUID) \| null | No | Optional reference to an existing contact record | | `name` | string \| null | No | Customer display name | | `email` | string \| null | No | Primary email address | | `phone` | string \| null | No | Primary phone number | | `notes` | string \| null | No | Internal notes and comments about the customer | | `status` | string \| null | No | Customer status (e.g., active, inactive, pending) | | `customerSince` | string \| null | No | Date when the customer relationship began (ISO 8601) | **Returns:** The created customer object. *** ### getCustomer Get a specific customer by ID. **Permission:** `customers:read` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | ---------------------------------- | | `id` | string (UUID) | Yes | The ID of the customer to retrieve | **Returns:** Customer object, or `null` if not found. *** ### listCustomers List all customers for the organization with pagination. **Permission:** `customers:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | --------------------------------------------- | | `limit` | number | No | 10 | Number of customers to return (1-100) | | `offset` | number | No | 0 | Number of customers to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | **Returns:** ```json theme={null} { "customers": [...], "count": 10, "limit": 10, "offset": 0 } ``` *** ### updateCustomer Update an existing customer record. **Permission:** `customers:write` **Parameters:** | Name | Type | Required | Description | | --------------- | --------------------- | -------- | ------------------------------------------------------ | | `id` | string (UUID) | Yes | The ID of the customer to update | | `businessId` | string (UUID) | No | The ID of the business this customer belongs to | | `contactId` | string (UUID) \| null | No | Reference to an existing contact record | | `type` | string | No | Customer type (e.g., individual, business, enterprise) | | `name` | string \| null | No | Customer display name | | `email` | string \| null | No | Primary email address | | `phone` | string \| null | No | Primary phone number | | `notes` | string \| null | No | Internal notes and comments about the customer | | `status` | string \| null | No | Customer status (e.g., active, inactive, pending) | | `customerSince` | string \| null | No | Date when the customer relationship began (ISO 8601) | **Returns:** The updated customer object. *** ### deleteCustomer Delete a customer (soft delete). **Permission:** `customers:delete` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | -------------------------------- | | `id` | string (UUID) | Yes | The ID of the customer to delete | **Returns:** The deleted customer object. *** ## Customer Transactions Tools for recording and managing financial transactions associated with customers. ### createCustomerTransaction Create a new customer transaction to record a financial activity. **Permission:** `customers.transactions:write` **Parameters:** | Name | Type | Required | Description | | ----------------- | -------------- | -------- | ------------------------------------------------------------- | | `customerId` | string (UUID) | Yes | UUID of the customer this transaction belongs to | | `businessId` | string (UUID) | Yes | UUID of the business associated with the transaction | | `amount` | string | Yes | Transaction amount as a string (to handle decimal precision) | | `currency` | string | Yes | Currency code (e.g., USD, EUR) | | `status` | string | Yes | Transaction status (e.g., pending, completed, failed) | | `type` | string | Yes | Transaction type (e.g., purchase, refund, subscription) | | `description` | string \| null | No | Optional description of the transaction | | `transactionDate` | string \| null | No | Optional date when the transaction occurred (ISO 8601 format) | **Returns:** The created customer transaction object. *** ### getCustomerTransaction Get a specific customer transaction by its ID. **Permission:** `customers.transactions:read` **Parameters:** | Name | Type | Required | Description | | --------------- | ------------- | -------- | -------------------------------------------- | | `transactionId` | string (UUID) | Yes | UUID of the customer transaction to retrieve | **Returns:** Customer transaction object, or `null` if not found. *** ### listCustomerTransactions List all transactions for a specific customer with pagination support. **Permission:** `customers.transactions:read` **Parameters:** | Name | Type | Required | Default | Description | | ------------ | ------------- | -------- | ------- | --------------------------------------------------- | | `customerId` | string (UUID) | Yes | - | UUID of the customer whose transactions to retrieve | | `limit` | number | No | 10 | Maximum number of items to return (1-100) | | `offset` | number | No | 0 | Number of items to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | **Returns:** ```json theme={null} { "transactions": [...], "count": 25, "limit": 10, "offset": 0 } ``` *** ### updateCustomerTransaction Update an existing customer transaction - all fields are optional except `transactionId`. **Permission:** `customers.transactions:write` **Parameters:** | Name | Type | Required | Description | | ----------------- | -------------- | -------- | ----------------------------------------------------------------------- | | `transactionId` | string (UUID) | Yes | UUID of the customer transaction to update | | `businessId` | string (UUID) | No | Update the business associated with the transaction | | `amount` | string | No | Update the transaction amount as a string (to handle decimal precision) | | `currency` | string | No | Update the currency code (e.g., USD, EUR) | | `status` | string | No | Update the transaction status (e.g., pending, completed, failed) | | `type` | string | No | Update the transaction type (e.g., purchase, refund, subscription) | | `description` | string \| null | No | Update the description of the transaction | | `transactionDate` | string \| null | No | Update the date when the transaction occurred (ISO 8601 format) | **Returns:** The updated customer transaction object. *** ### deleteCustomerTransaction Delete a customer transaction (soft delete). **Permission:** `customers.transactions:delete` **Parameters:** | Name | Type | Required | Description | | --------------- | ------------- | -------- | ------------------------------------------ | | `transactionId` | string (UUID) | Yes | UUID of the customer transaction to delete | **Returns:** The deleted customer transaction object. *** ## Next Steps Manage contacts that may be linked to customers Learn how MCP clients authenticate to the server # Domain Tools Source: https://docs.bizzyco.ai/mcp-server/tools/domains Manage domains, WHOIS contacts, and domain registrations The Bizzy MCP server provides 15 tools for managing domains and their associated registration data. These tools are organized into three categories: domains, domain contacts, and domain registrations. Domain Contacts on this page are the registrant, admin, and tech contacts attached to a domain registration (WHOIS data). They are distinct from CRM Contacts (people in your address book) — see [Contact Tools](/mcp-server/tools/contacts) for those. ## Domains Tools for managing domain records used for DNS and email. ### createDomain Create a new domain record for DNS and email management. **Permission:** `domains:write` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | --------------------- | -------- | --------- | ----------------------------------------------- | | `domain` | string | Yes | - | The domain name (e.g., example.com) | | `status` | string | No | "pending" | Domain status (e.g., active, pending, inactive) | | `zoneId` | string \| null | No | - | Optional DNS zone ID for the domain | | `createdBy` | string (UUID) \| null | No | - | Optional user ID who created the domain | Verification, registrar, and Resend-related fields are managed by the platform — do not pass them in here, as they are overwritten or ignored. **Returns:** The created domain object. *** ### getDomain Get a specific domain by ID. **Permission:** `domains:read` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | -------------------------------- | | `id` | string (UUID) | Yes | The ID of the domain to retrieve | **Returns:** Domain object, or `null` if not found. *** ### listDomains List all domains for the organization with pagination. **Permission:** `domains:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | --------------------------------------------- | | `limit` | number | No | 10 | Maximum number of items to return (max: 100) | | `offset` | number | No | 0 | Number of items to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | **Returns:** ```json theme={null} { "domains": [...], "count": 12, "limit": 10, "offset": 0 } ``` *** ### updateDomain Update an existing domain record. **Permission:** `domains:write` **Parameters:** | Name | Type | Required | Description | | ----------- | --------------------- | -------- | ----------------------------------------------- | | `id` | string (UUID) | Yes | The ID of the domain to update | | `domain` | string | No | The domain name (e.g., example.com) | | `status` | string | No | Domain status (e.g., active, pending, inactive) | | `zoneId` | string \| null | No | DNS zone ID for the domain | | `createdBy` | string (UUID) \| null | No | User ID who created the domain | **Returns:** The updated domain object. *** ### deleteDomain Delete a domain (soft delete). **Permission:** `domains:delete` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | ------------------------------ | | `id` | string (UUID) | Yes | The ID of the domain to delete | **Returns:** The deleted domain object. *** ## Domain Contacts Tools for managing the registrant, admin, and tech contacts attached to a domain registration. These are WHOIS-style contacts at the domain registrar — not CRM contacts. ### createDomainContact Create a new domain contact for domain registration and administrative purposes. **Permission:** `domain-contacts:write` **Parameters:** | Name | Type | Required | Description | | ------------------ | --------------------- | -------- | -------------------------------------------------------- | | `externalId` | string | Yes | External ID from the domain registrar | | `accountId` | string | Yes | Account ID at the domain registrar | | `label` | string \| null | No | Optional label for the contact (e.g., "Primary Contact") | | `firstName` | string | Yes | First name of the contact | | `lastName` | string | Yes | Last name of the contact | | `organizationName` | string \| null | No | Optional organization/company name | | `jobTitle` | string \| null | No | Optional job title of the contact | | `address1` | string \| null | No | Primary address line | | `address2` | string \| null | No | Secondary address line | | `city` | string \| null | No | City | | `stateProvince` | string \| null | No | State or province | | `postalCode` | string \| null | No | Postal/ZIP code | | `country` | string \| null | No | Country code (e.g., US, CA) | | `email` | string | Yes | Contact email address | | `phone` | string | Yes | Contact phone number | | `createdBy` | string (UUID) \| null | No | Optional user ID who created the contact | **Returns:** The created domain contact object. *** ### getDomainContact Get a specific domain contact by ID. **Permission:** `domain-contacts:read` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | ---------------------------------------- | | `id` | string (UUID) | Yes | The ID of the domain contact to retrieve | **Returns:** Domain contact object, or `null` if not found. *** ### listDomainContacts List all domain contacts for the organization with pagination. **Permission:** `domain-contacts:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | --------------------------------------------- | | `limit` | number | No | 10 | Maximum number of items to return (max: 100) | | `offset` | number | No | 0 | Number of items to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | **Returns:** ```json theme={null} { "domainContacts": [...], "count": 8, "limit": 10, "offset": 0 } ``` *** ### updateDomainContact Update an existing domain contact record. **Permission:** `domain-contacts:write` **Parameters:** | Name | Type | Required | Description | | ------------------ | --------------------- | -------- | ----------------------------------------------- | | `id` | string (UUID) | Yes | The ID of the domain contact to update | | `externalId` | string | No | External ID from the domain registrar | | `accountId` | string | No | Account ID at the domain registrar | | `label` | string \| null | No | Label for the contact (e.g., "Primary Contact") | | `firstName` | string | No | First name of the contact | | `lastName` | string | No | Last name of the contact | | `organizationName` | string \| null | No | Organization/company name | | `jobTitle` | string \| null | No | Job title of the contact | | `address1` | string \| null | No | Primary address line | | `address2` | string \| null | No | Secondary address line | | `city` | string \| null | No | City | | `stateProvince` | string \| null | No | State or province | | `postalCode` | string \| null | No | Postal/ZIP code | | `country` | string \| null | No | Country code (e.g., US, CA) | | `email` | string | No | Contact email address | | `phone` | string | No | Contact phone number | | `createdBy` | string (UUID) \| null | No | User ID who created the contact | **Returns:** The updated domain contact object. *** ### deleteDomainContact Delete a domain contact (soft delete). **Permission:** `domain-contacts:delete` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | -------------------------------------- | | `id` | string (UUID) | Yes | The ID of the domain contact to delete | **Returns:** The deleted domain contact object. *** ## Domain Registrations Tools for managing domain registration records that track ownership, renewal, and registrar metadata. ### createDomainRegistration Create a new domain registration record to track domain ownership and renewal. **Permission:** `domain-registrations:write` **Parameters:** | Name | Type | Required | Description | | ------------------ | --------------------- | -------- | ------------------------------------------------------- | | `state` | string | Yes | Registration state (e.g., registered, pending, expired) | | `externalDomainId` | string | Yes | External domain ID from the registrar | | `externalId` | string | Yes | External registration ID from the registrar | | `autoRenew` | boolean | Yes | Whether auto-renewal is enabled | | `whoisPrivacy` | boolean | Yes | Whether WHOIS privacy is enabled | | `transferLock` | boolean | Yes | Whether domain transfer lock is enabled | | `period` | number | Yes | Registration period in years | | `domainId` | string (UUID) \| null | No | Optional reference to the related domain record | | `createdBy` | string (UUID) \| null | No | Optional user ID who created the registration | **Returns:** The created domain registration object. *** ### getDomainRegistration Get a specific domain registration by ID. **Permission:** `domain-registrations:read` **Parameters:** | Name | Type | Required | Description | | ---------------- | ------------- | -------- | --------------------------------------------- | | `registrationId` | string (UUID) | Yes | The ID of the domain registration to retrieve | **Returns:** Domain registration object, or `null` if not found. *** ### listDomainRegistrations List all domain registrations for the organization with pagination. **Permission:** `domain-registrations:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | --------------------------------------------- | | `limit` | number | No | 10 | Maximum number of items to return (max: 100) | | `offset` | number | No | 0 | Number of items to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | **Returns:** ```json theme={null} { "domainRegistrations": [...], "count": 5, "limit": 10, "offset": 0 } ``` *** ### updateDomainRegistration Update an existing domain registration record - all fields are optional except registrationId. **Permission:** `domain-registrations:write` **Parameters:** | Name | Type | Required | Description | | ------------------ | --------------------- | -------- | ------------------------------------------------------------------ | | `registrationId` | string (UUID) | Yes | The ID of the domain registration to update | | `state` | string | No | Update the registration state (e.g., registered, pending, expired) | | `externalDomainId` | string | No | Update the external domain ID from the registrar | | `externalId` | string | No | Update the external registration ID from the registrar | | `autoRenew` | boolean | No | Update whether auto-renewal is enabled | | `whoisPrivacy` | boolean | No | Update whether WHOIS privacy is enabled | | `transferLock` | boolean | No | Update whether domain transfer lock is enabled | | `period` | number | No | Update the registration period in years | | `createdBy` | string (UUID) \| null | No | Update the user ID who created the registration | **Returns:** The updated domain registration object. *** ### deleteDomainRegistration Delete a domain registration (soft delete). **Permission:** `domain-registrations:delete` **Parameters:** | Name | Type | Required | Description | | ---------------- | ------------- | -------- | ------------------------------------------- | | `registrationId` | string (UUID) | Yes | The ID of the domain registration to delete | **Returns:** The deleted domain registration object. *** ## Next Steps Manage CRM contacts, distinct from the WHOIS-style domain contacts above Learn how MCP clients authenticate to the server # Email Address Tools Source: https://docs.bizzyco.ai/mcp-server/tools/email-addresses Inspect organization email addresses available for sending and receiving The Bizzy MCP server provides 2 tools for inspecting the email addresses connected to your organization. Use these tools to discover which addresses are available for sending templated emails or to look up a specific address by ID. ## getEmailAddress Get details of a specific email address by ID. **Permission:** `email-addresses:read` **Parameters:** | Name | Type | Required | Description | | ---------------- | ------------- | -------- | --------------------------------------- | | `emailAddressId` | string (UUID) | Yes | The ID of the email address to retrieve | **Returns:** The email address object, or `null` if not found. *** ## listEmailAddresses List email addresses for the organization with optional filtering. **Permission:** `email-addresses:read` **Parameters:** | Name | Type | Required | Default | Description | | ---------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------- | | `limit` | number | No | 100 | Maximum number of results | | `offset` | number | No | 0 | Offset for pagination | | `provider` | string | No | - | Filter by email provider. Valid values: `google`, `microsoft`, `bizzy`, `apple` | | `status` | string | No | - | Filter by email address status. Valid values: `pending`, `active`, `disabled`, `errored`, `deleted` | **Returns:** ```json theme={null} { "emailAddresses": [...], "count": 12, "limit": 100, "offset": 0 } ``` *** ## Next Steps Create, render, and send templated emails Learn how MCP clients authenticate to the server # Email Template Tools Source: https://docs.bizzyco.ai/mcp-server/tools/email-templates Create, render, and send Mustache-based email templates The Bizzy MCP server provides 7 tools for managing email templates and using them to send templated emails. These tools are organized into two categories: templates and render & send. ## Templates CRUD tools for managing reusable email templates. Templates support Mustache syntax for dynamic content in both subject lines and bodies. ### createEmailTemplate Create a new email template with name (max 200 chars), subject (max 1000 chars), body (max 50000 chars), and optional variables. Templates support Mustache syntax for dynamic content. **Permission:** `emailTemplates:write` **Parameters:** | Name | Type | Required | Description | | ------------- | --------- | -------- | ----------------------------------------------------------------------------------------- | | `name` | string | Yes | The name of the email template (1-200 characters) | | `subject` | string | Yes | The subject line of the email template (1-1000 characters). Supports Mustache variables. | | `body` | string | Yes | The body content of the email template (1-50000 characters). Supports Mustache variables. | | `description` | string | No | Optional description of the email template (max 2000 characters) | | `variables` | string\[] | No | Optional list of variable names used in the template for documentation | **Returns:** The created email template object. *** ### getEmailTemplate Get a specific email template by ID, including all template details. **Permission:** `emailTemplates:read` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | ---------------------------------------- | | `id` | string (UUID) | Yes | The ID of the email template to retrieve | **Returns:** The email template object, or `null` if not found. *** ### listEmailTemplates List email templates for the organization with pagination. Supports filtering by status and name. **Permission:** `emailTemplates:read` **Parameters:** | Name | Type | Required | Default | Description | | -------- | ------ | -------- | ------- | ------------------------------------------------------------------- | | `limit` | number | No | 10 | Number of email templates to return (1-100) | | `offset` | number | No | 0 | Number of email templates to skip for pagination | | `status` | string | No | - | Filter by template status (`active` or `archived`) | | `name` | string | No | - | Filter by name (case-insensitive partial match, max 200 characters) | **Returns:** ```json theme={null} { "emailTemplates": [...], "count": 8, "limit": 10, "offset": 0 } ``` *** ### updateEmailTemplate Update an existing email template with new values for any template fields. Name max 200 chars, subject max 1000 chars, body max 50000 chars. **Permission:** `emailTemplates:write` **Parameters:** | Name | Type | Required | Description | | ------------- | ----------------- | -------- | ------------------------------------------------------------- | | `id` | string (UUID) | Yes | The ID of the email template to update | | `name` | string | No | The name of the email template (1-200 characters) | | `description` | string \| null | No | Description of the email template (max 2000 characters) | | `subject` | string | No | The subject line of the email template (1-1000 characters) | | `body` | string | No | The body content of the email template (1-50000 characters) | | `variables` | string\[] \| null | No | List of variable names used in the template for documentation | | `status` | string | No | Template status (`active` or `archived`) | **Returns:** The updated email template object. *** ### deleteEmailTemplate Delete an email template (soft delete). **Permission:** `emailTemplates:delete` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | -------------------------------------- | | `id` | string (UUID) | Yes | The ID of the email template to delete | **Returns:** The deleted email template object. *** ## Render & Send Tools for rendering templates with variable data and dispatching templated emails through the organization's email pipeline. ### renderEmailTemplate Render an email template by ID with provided data variables using Mustache templating. Returns the rendered subject and body. **Permission:** `emailTemplates:read` **Parameters:** | Name | Type | Required | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------ | | `templateId` | string (UUID) | Yes | The ID of the email template to render | | `data` | Record\ | Yes | Key-value pairs of variable data to render into the template | **Returns:** Object with `subject` and `body` strings containing the rendered content. *** ### sendTemplatedEmail Render an email template with data and send it. Fetches the template, renders subject and body with the provided data, and sends the email from the specified email address. **Permission:** `emailTemplates:write` **Parameters:** | Name | Type | Required | Description | | -------------------- | ------------------------ | -------- | ------------------------------------------------- | | `templateId` | string (UUID) | Yes | The ID of the email template to use | | `data` | Record\ | Yes | Template variable data for rendering | | `to` | string\[] | Yes | Array of recipient email addresses (at least one) | | `fromEmailAddressId` | string (UUID) | Yes | The ID of the email address to send from | | `cc` | string\[] | No | Array of CC email addresses | | `bcc` | string\[] | No | Array of BCC email addresses | | `replyTo` | string | No | Reply-to email address | **Returns:** Object with `subject`, `to`, `from`, `rendered`, and `sent` fields summarizing the send result. *** ## Next Steps Discover which email addresses are available to send from Learn how MCP clients authenticate to the server # File Tools Source: https://docs.bizzyco.ai/mcp-server/tools/files Upload, download, search, and organize files in organization storage The Bizzy MCP server provides 7 tools for managing files and folders in organization storage. These tools are organized into two categories: files and folders. ## Files Tools for uploading, downloading, listing, searching, and deleting files. File content is exchanged as base64-encoded strings to support the MCP protocol. ### uploadFile Upload a file to organization storage with base64-encoded content. **Permission:** `files:write` **Parameters:** | Name | Type | Required | Description | | ------------- | --------------------- | -------- | ------------------------------------------------------------ | | `filename` | string | Yes | Name of the file (1-255 characters) | | `content` | string | Yes | Base64-encoded file content (max 10MB file size) | | `contentType` | string | Yes | MIME type of the file (e.g., `application/pdf`, `image/png`) | | `folderId` | string (UUID) \| null | No | Optional folder ID to place the file in | | `description` | string | No | Optional description of the file (max 5000 characters) | | `tags` | string\[] | No | Optional tags for the file (max 10) | **Returns:** Object with `success` boolean and a `file` object containing `id`, `filename`, `size`, `contentType`, and `folderId`. *** ### downloadFile Download a file from organization storage as base64-encoded content. **Permission:** `files:read` **Parameters:** | Name | Type | Required | Description | | -------- | ------------- | -------- | ------------------------------ | | `fileId` | string (UUID) | Yes | The ID of the file to download | **Returns:** Object with a `file` metadata object (`id`, `filename`, `contentType`, `size`) and a `content` string containing base64-encoded file bytes. Downloads are gated by each file's `agentAccessEnabled` flag. Files with agent access disabled return an error. *** ### listFiles List files in organization storage with optional folder filtering and pagination. **Permission:** `files:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | --------------------- | -------- | ------- | --------------------------------------------------------------- | | `folderId` | string (UUID) \| null | No | - | Filter by folder ID (`null` for root level, omit for all files) | | `limit` | number | No | 10 | Number of files to return (1-100) | | `offset` | number | No | 0 | Pagination offset | | `sortOrder` | string | No | "desc" | Sort order by creation date (`asc` or `desc`) | **Returns:** ```json theme={null} { "files": [...], "count": 23, "limit": 10, "offset": 0 } ``` *** ### searchFiles Search files by filename, description, or tags using full-text search. **Permission:** `files:read` **Parameters:** | Name | Type | Required | Default | Description | | -------- | ------ | -------- | ------- | -------------------------------------------------------------------------------- | | `query` | string | Yes | - | Search query to match against filename, description, and tags (1-255 characters) | | `limit` | number | No | 10 | Number of results to return (1-100) | | `offset` | number | No | 0 | Pagination offset | **Returns:** ```json theme={null} { "files": [...], "count": 5, "query": "invoice", "limit": 10, "offset": 0 } ``` *** ### deleteFile Delete a file from organization storage (soft delete). **Permission:** `files:delete` **Parameters:** | Name | Type | Required | Description | | -------- | ------------- | -------- | ---------------------------- | | `fileId` | string (UUID) | Yes | The ID of the file to delete | **Returns:** Object with `success` boolean, the deleted `file` object, and a `message` string. *** ## Folders Tools for organizing files into a folder hierarchy. Folders can be nested up to 5 levels deep. ### createFolder Create a new folder in organization storage with optional parent folder (max 5 levels deep). **Permission:** `folders:write` **Parameters:** | Name | Type | Required | Description | | ---------------- | --------------------- | -------- | ------------------------------------------------- | | `name` | string | Yes | Name of the folder (1-255 characters) | | `parentFolderId` | string (UUID) \| null | No | Optional parent folder ID (`null` for root level) | **Returns:** The created folder object. *** ### listFolders List folders in organization storage with optional parent folder filtering and pagination. **Permission:** `folders:read` **Parameters:** | Name | Type | Required | Default | Description | | ---------------- | --------------------- | -------- | ------- | ------------------------------------------------------------------------ | | `parentFolderId` | string (UUID) \| null | No | - | Filter by parent folder ID (`null` for root level, omit for all folders) | | `limit` | number | No | 10 | Number of folders to return (1-100) | | `offset` | number | No | 0 | Pagination offset | | `sortOrder` | string | No | "desc" | Sort order by creation date (`asc` or `desc`) | **Returns:** ```json theme={null} { "folders": [...], "count": 6, "limit": 10, "offset": 0 } ``` *** ## Next Steps Manage contacts and their associated data Learn how MCP clients authenticate to the server # Tools Overview Source: https://docs.bizzyco.ai/mcp-server/tools/index Available tools in the Bizzy MCP Server The Bizzy MCP server provides tools for managing your business communications and contacts. Tools are organized by resource type and require appropriate [permissions](/mcp-server/authentication) to access. ## Available Tool Categories The MCP server exposes 106 tools across 11 resource categories. Each category has a dedicated reference page listing every tool, its parameters, permission, and return shape. | Category | Tools | Description | | ---------------------------------------------------- | ----- | ------------------------------------------------------------ | | [Automations](/mcp-server/tools/automations) | 7 | Create, update, and inspect automations and their executions | | [Businesses](/mcp-server/tools/businesses) | 20 | Business profile, offerings, and online/physical presences | | [Contacts](/mcp-server/tools/contacts) | 20 | Contacts and their emails, phones, and addresses | | [Customers](/mcp-server/tools/customers) | 10 | Customer records and customer transactions | | [Domains](/mcp-server/tools/domains) | 15 | Domains, domain contacts, and domain registrations | | [Email Addresses](/mcp-server/tools/email-addresses) | 2 | List and read connected email addresses | | [Email Templates](/mcp-server/tools/email-templates) | 7 | Manage templates, render previews, and send templated email | | [Files](/mcp-server/tools/files) | 7 | Upload, download, search, and delete files; manage folders | | [Messages](/mcp-server/tools/messages) | 6 | Read messages, threads, and attachments; update status | | [Phone Numbers](/mcp-server/tools/phone-numbers) | 2 | List and read connected phone numbers | | [Tasks](/mcp-server/tools/tasks) | 10 | Task CRUD, search, and assignee management | ## Permission Model Each tool requires specific permissions to execute. Permissions follow the pattern `resource:action` (e.g., `contacts:read`) or `resource.subresource:action` for nested resources (e.g., `contacts.emails:write`). **Permission levels:** | Action | Description | | -------- | --------------------------- | | `read` | View and list resources | | `write` | Create and update resources | | `delete` | Remove resources | **Examples:** * `contacts:read` - List and view contacts * `contacts:write` - Create and update contacts * `contacts.emails:write` - Add or update contact email addresses * `messages:read` - View and search messages You grant these permissions on the MCP server's consent screen during the OAuth handshake. The set of tools advertised over `tools/list` is filtered against the categories you approve. See [Authentication](/mcp-server/authentication) for the full flow. ## Common Starting Points 20 tools for managing contacts, emails, addresses, and phone numbers 6 tools for accessing messages, threads, and attachments 10 tools for managing tasks and assignees 7 tools for uploading, downloading, and organizing files ## Next Steps Learn how MCP clients authenticate to the server Connect to AI tools like Claude, Cursor, and Windsurf # Message Tools Source: https://docs.bizzyco.ai/mcp-server/tools/messages Access and manage messages, threads, and attachments The Bizzy MCP server provides 7 tools for accessing and managing messages. These tools allow you to retrieve messages, search content, manage message status, and view conversation threads. ## getMessage Get detailed information about a specific message by its ID, including all message type-specific fields (email headers, SMS encoding, WhatsApp media, etc.). **Permission:** `messages:read` **Parameters:** | Name | Type | Required | Description | | ----------- | ------------- | -------- | ----------------------------- | | `messageId` | string (UUID) | Yes | ID of the message to retrieve | **Returns:** Message object with all type-specific fields. *** ## listMessages List messages in the organization with optional filtering. **Permission:** `messages:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | ------------------------------------------------------ | | `limit` | number | No | 10 | Maximum number of messages to return (1-100) | | `offset` | number | No | 0 | Offset for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | | `direction` | string | No | - | Filter by message direction ("incoming" or "outgoing") | **Returns:** Array of message objects. *** ## updateMessageStatus Update the status of a message - mark as read/unread, archive/unarchive, or snooze/unsnooze. **Permission:** `messages:write` **Parameters:** | Name | Type | Required | Description | | -------------- | -------------- | -------- | --------------------------------------------------------- | | `messageId` | string (UUID) | Yes | ID of the message to update | | `readAt` | string \| null | No | ISO datetime to mark as read, or `null` to mark as unread | | `archivedAt` | string \| null | No | ISO datetime to archive, or `null` to unarchive | | `snoozedUntil` | string \| null | No | ISO datetime to snooze until, or `null` to unsnooze | **Returns:** The updated message object. This tool only allows updating status fields for security reasons. To modify message content, use the appropriate channel-specific tools. *** ## getMessagesByContact Get all messages sent to or received from a specific contact. Useful for viewing the complete communication history with a contact. **Permission:** `messages:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------------- | -------- | ------- | ------------------------------------------------------------------------ | | `contactId` | string (UUID) | Yes | - | Contact ID to retrieve messages for | | `limit` | number | No | 20 | Maximum number of messages to return (1-100) | | `offset` | number | No | 0 | Offset for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | | `direction` | string | No | - | Filter by direction ("incoming" = from contact, "outgoing" = to contact) | **Returns:** Array of message objects from/to the specified contact. *** ## getMessageThread Get all messages that belong to the same conversation thread. Useful for viewing the complete conversation history. **Permission:** `messages:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | ------------------------------------------------------------------------------ | | `threadId` | string | Yes | - | Thread ID to retrieve messages for | | `limit` | number | No | 50 | Maximum number of messages to return (1-100) | | `offset` | number | No | 0 | Offset for pagination | | `sortOrder` | string | No | "asc" | Sort order ("asc" = oldest first for conversation flow, "desc" = newest first) | | `direction` | string | No | - | Filter by message direction ("incoming" or "outgoing") | **Returns:** Array of message objects in the thread. *** ## listMessageAttachments List all file attachments associated with a specific message, including details like filename, size, content type, and URL. **Permission:** `messages:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------------- | -------- | ------- | --------------------------------------------- | | `messageId` | string (UUID) | Yes | - | ID of the message | | `limit` | number | No | 20 | Maximum number of attachments to return | | `offset` | number | No | 0 | Offset for pagination | | `sortOrder` | string | No | "asc" | Sort order by creation date ("asc" or "desc") | **Returns:** Array of attachment objects with metadata (filename, size, content type, URL). *** ## Next Steps Manage contacts and their data Learn how MCP clients authenticate to the server # Phone Number Tools Source: https://docs.bizzyco.ai/mcp-server/tools/phone-numbers Inspect organization phone numbers used for SMS and voice channels The Bizzy MCP server provides 2 tools for inspecting the phone numbers connected to your organization. Use these tools to discover which numbers are available or to look up a specific number by ID. ## getPhoneNumber Get details of a specific phone number by ID. **Permission:** `phone-numbers:read` **Parameters:** | Name | Type | Required | Description | | --------------- | ------------- | -------- | -------------------------------------- | | `phoneNumberId` | string (UUID) | Yes | The ID of the phone number to retrieve | **Returns:** The phone number object, or `null` if not found. *** ## listPhoneNumbers List phone numbers for the organization with optional filtering. **Permission:** `phone-numbers:read` **Parameters:** | Name | Type | Required | Default | Description | | ---------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------- | | `limit` | number | No | 100 | Maximum number of results | | `offset` | number | No | 0 | Offset for pagination | | `provider` | string | No | - | Filter by phone provider. Valid values: `telnyx`, `twilio` | | `status` | string | No | - | Filter by phone number status. Valid values: `pending`, `active`, `disabled`, `errored`, `deleted` | **Returns:** ```json theme={null} { "phoneNumbers": [...], "count": 4, "limit": 100, "offset": 0 } ``` *** ## Next Steps Inspect email addresses available for sending Learn how MCP clients authenticate to the server # Task Tools Source: https://docs.bizzyco.ai/mcp-server/tools/tasks Manage tasks, search them, and assign them to users The Bizzy MCP server provides 10 tools for managing tasks and their assignees. These tools are organized into two categories: tasks and assignees. ## Tasks Core tools for creating, reading, updating, deleting, and searching tasks. ### createTask Create a new task with title (max 500 chars), description (max 10,000 chars), priority settings, and optional metadata. Tasks can be categorized and assigned due dates. **Permission:** `tasks:write` **Parameters:** | Name | Type | Required | Default | Description | | ------------- | ---------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- | | `title` | string | Yes | - | The title of the task (1-500 characters) | | `description` | string | Yes | - | Detailed description of the task and what needs to be done | | `status` | string | No | "todo" | Current status of the task. Valid values: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `cancelled` | | `category` | string \| null | No | - | Task category. Valid values: `bug_fix`, `feature_request`, `documentation`, `meeting`, `planning`, `research`, `review`, `other` | | `importance` | string \| null | No | - | How important this task is. Valid values: `low`, `medium`, `high` | | `urgency` | string \| null | No | - | How urgent this task is. Valid values: `low`, `medium`, `high` | | `dueDate` | string \| null | No | - | Due date for the task (ISO 8601 datetime with offset) | | `messageId` | string (UUID) \| null | No | - | Optional reference to a related message | | `contactId` | string (UUID) \| null | No | - | Optional reference to a related contact | | `metadata` | Record\ \| null | No | - | Additional structured metadata for the task | **Returns:** The created task object. *** ### getTask Get a specific task by ID, including all task details and assignees. **Permission:** `tasks:read` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | ------------------------------ | | `id` | string (UUID) | Yes | The ID of the task to retrieve | **Returns:** Full task object with assignees, or `null` if not found. *** ### listTasks List all tasks for the organization with pagination, including assignee details. **Permission:** `tasks:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | --------------------------------------------- | | `limit` | number | No | 10 | Number of tasks to return (1-100) | | `offset` | number | No | 0 | Number of tasks to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | **Returns:** ```json theme={null} { "tasks": [...], "count": 42, "limit": 10, "offset": 0 } ``` *** ### updateTask Update an existing task with new values for any task fields. Title max 500 chars, description max 10,000 chars. **Permission:** `tasks:write` **Parameters:** | Name | Type | Required | Description | | ------------- | ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | `id` | string (UUID) | Yes | The ID of the task to update | | `title` | string | No | The title of the task (1-500 characters) | | `description` | string | No | Detailed description of the task and what needs to be done | | `category` | string \| null | No | Task category. Valid values: `bug_fix`, `feature_request`, `documentation`, `meeting`, `planning`, `research`, `review`, `other` | | `importance` | string \| null | No | How important this task is. Valid values: `low`, `medium`, `high` | | `urgency` | string \| null | No | How urgent this task is. Valid values: `low`, `medium`, `high` | | `status` | string | No | Current status of the task. Valid values: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `cancelled` | | `dueDate` | string \| null | No | Due date for the task (ISO 8601 datetime with offset) | | `messageId` | string (UUID) \| null | No | Reference to a related message | | `contactId` | string (UUID) \| null | No | Reference to a related contact | | `metadata` | Record\ \| null | No | Additional structured metadata for the task | **Returns:** The updated task object. *** ### deleteTask Delete a task (soft delete). **Permission:** `tasks:delete` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | ---------------------------- | | `id` | string (UUID) | Yes | The ID of the task to delete | **Returns:** The deleted task object. *** ### searchTasks Search for tasks using PostgreSQL full-text search across title, description, and metadata. Supports automatic word stemming, phrase matching, and relevance ranking. Results are sorted by relevance (most relevant first). **Permission:** `tasks:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | Yes | - | Search query to find tasks using full-text search. Searches across title, description, and metadata. Supports automatic word stemming (e.g., "running" matches "run") and phrase matching (max 255 characters) | | `limit` | number | No | 10 | Maximum number of results to return (1-50) | | `offset` | number | No | 0 | Number of tasks to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by relevance rank ("desc" = most relevant first, "asc" = least relevant first) | **Returns:** Array of full task objects ordered by relevance. *** ## Assignees Tools for assigning users to tasks and listing assignment relationships. ### assignTask Assign a user to a task. **Permission:** `tasks:write` **Parameters:** | Name | Type | Required | Description | | -------- | ------------- | -------- | ---------------------------------------- | | `taskId` | string (UUID) | Yes | The ID of the task to assign | | `userId` | string (UUID) | Yes | The ID of the user to assign to the task | **Returns:** The created task assignee object. *** ### unassignTask Remove a user assignment from a task. **Permission:** `tasks:write` **Parameters:** | Name | Type | Required | Description | | -------- | ------------- | -------- | -------------------------------------------- | | `taskId` | string (UUID) | Yes | The ID of the task to unassign from | | `userId` | string (UUID) | Yes | The ID of the user to unassign from the task | **Returns:** The removed task assignee object. *** ### listTaskAssignees Get all users assigned to a specific task. **Permission:** `tasks:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------------- | -------- | ------- | --------------------------------------------- | | `taskId` | string (UUID) | Yes | - | The ID of the task to get assignees for | | `limit` | number | No | 10 | Maximum number of items to return (1-100) | | `offset` | number | No | 0 | Number of items to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | **Returns:** ```json theme={null} { "assignees": [...], "count": 3, "limit": 10, "offset": 0 } ``` *** ### listUserTasks Get all tasks assigned to a specific user. **Permission:** `tasks:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------------- | -------- | ------- | ---------------------------------------------- | | `userId` | string (UUID) | Yes | - | The ID of the user to get task assignments for | | `limit` | number | No | 10 | Maximum number of items to return (1-100) | | `offset` | number | No | 0 | Number of items to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | **Returns:** ```json theme={null} { "assignments": [...], "count": 8, "limit": 10, "offset": 0 } ``` *** ## Next Steps Build automations that create or update tasks in response to events Learn how MCP clients authenticate to the server # Agent Conversations Source: https://docs.bizzyco.ai/user-guide/agent-conversations/index Browse past agent chats, filter by status, and resume any conversation Beta Every chat with an agent is saved. The **Agent Conversations** page lists every conversation across every agent in your organization — with filters for status and pagination for large histories. Agent conversations list ## The list view Columns typically include: * **Title** — auto-generated from the first message; editable on the detail page * **Agent** — which agent handled the conversation * **Status** — current state * **Last updated** — when the most recent message landed ### Status values | Status | Meaning | | ----------- | ------------------------------------------------- | | `active` | Open — you can still send messages | | `completed` | Ended cleanly | | `timeout` | The agent hit a tool-approval or max-step timeout | | `error` | An error stopped the conversation | ### Filters * **Status** — pick one of the four statuses to narrow the list. * **Pagination** — page size defaults to 20 (max 100). ## Opening a conversation Click any row to open its [transcript](/user-guide/agent-conversations/transcripts), where you can see every message, every tool call, and every approval decision. ## Next steps Detailed conversation view Configure the agents that drive these conversations # Conversation Transcripts Source: https://docs.bizzyco.ai/user-guide/agent-conversations/transcripts Review the full message and tool-call history of a Bizzy agent conversation The conversation detail page shows every turn, every tool call, and every approval decision in the chat — in order. Conversation transcript view ## What you see ### Messages Each user and agent message renders as a bubble with the content and a timestamp. ### Tool invocations When the agent called a tool, you see an inline card with: * **Tool name** and **category** * **Inputs** — the arguments the agent passed (collapsed by default; click to expand) * **Outputs** — what the tool returned * **Duration** — how long the call took ### Tool approval audit For any tool set to **Ask**, the card also records: * Who approved or denied * The timestamp of the decision * If the approval timed out This gives you a complete trail of what the agent wanted to do and how you responded. ## Actions on the detail page | Action | How | Effect | | ---------- | ---------------------- | ----------------------------------------------------------------------------------- | | **Rename** | Edit the title | Updates the title via `PATCH` — useful when the auto-generated title isn't helpful | | **Delete** | Delete button | Soft-deletes the conversation — the transcript is hidden but recoverable by support | | **Resume** | Type into the composer | Sends a new message; if status was `active`, the conversation continues | ## When can I resume? * **Active:** always — just type and send. * **Completed / timeout / error:** sending a message reopens the conversation and changes its status back to active. Tool state may be stale (for example, if the conversation referenced a contact that has since been deleted). ## Exporting No UI export today. If you need a transcript out of Bizzy, contact support. ## Next steps Adjust what gets auto-approved Start a new conversation # Chatting with an Agent Source: https://docs.bizzyco.ai/user-guide/agents/chat The full-page Bizzy agent chat interface Each agent has a chat interface at `/{org}/agents/{id}` — a full-page, message-by-message view with inline tool calls and approval cards. Agent chat page with tool approval card ## Starting a conversation 1. Open an agent from the **Agents** list. 2. Type a message in the composer at the bottom of the chat. 3. Send. The agent thinks, optionally calls tools (subject to your [permissions](/user-guide/agents/tool-permissions)), and replies. ## Tool calls inline When the agent calls a tool, you see an inline card showing the tool name, inputs (collapsed by default — expand to see), and outputs once the call returns. If the tool is set to **Ask**, the card pauses with: * The tool's risk badge * The inputs the agent wants to use * A countdown timer * **Approve** / **Deny** buttons If the timer runs out with no decision, the tool is treated as denied and the agent continues without it. ## Resuming past conversations Past conversations appear in [Agent Conversations](/user-guide/agent-conversations/index). Open any conversation's detail page to see the full history; send a new message to continue from where it left off. ## Under the hood * The chat uses a WebSocket connection for low-latency streaming. * The UI is lazy-loaded, so the first open of an agent chat may take a moment. * Messages persist even if you close the tab — reload and you'll see what was already there. ## Troubleshooting | Problem | Likely cause | Fix | | -------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------ | | Agent just says "Max steps reached" | The agent hit its `maxSteps` budget mid-turn | Raise `maxSteps` on the agent, or simplify the request | | Tool keeps asking for approval | Permission set to **Ask** | Change to **Allow** in the Tools tab if you trust it | | Agent refuses a task it should be able to do | System prompt too restrictive, or tool set to **Deny** | Review the prompt and Tools tab | ## Next steps Review or resume past chats Fine-tune what the agent can do # Creating an Agent Source: https://docs.bizzyco.ai/user-guide/agents/creating Configure a new Bizzy agent with a system prompt, model, and LLM parameters 1. Go to **Agents** in the sidebar. 2. Click **New Agent**. 3. Fill in the form. Create agent form ## Required fields | Field | Notes | | ---------- | ----------------------------------------------------------------------- | | **Name** | Short label — shown in chat and conversation history | | **Type** | `Assistant` (general-purpose) or `Specialist` (narrower, task-focused) | | **Status** | `Active` to enable chat; `Disabled` to park it | | **Model** | See [Models](/user-guide/agents/models). Defaults to Claude Sonnet 4.6. | The type influences the default system prompt applied if you leave the prompt empty. ## System prompt Open the **System Prompt** section to customize behavior. Write in plain English — describe the agent's role, tone, any rules, and what kind of output you want. If left blank, a sensible default per type is used. The system prompt is the single biggest lever on agent behavior. Be specific about scope ("only answer support questions about our product X") and boundaries ("do not send email without explicit user confirmation"). ## LLM settings Advanced settings in the accordion — safe to leave at defaults for most cases: | Setting | Typical range | What it does | | --------------------- | ------------------- | ---------------------------------------------------- | | **Temperature** | 0 – 2 | Randomness. Lower = more deterministic | | **Max tokens** | Varies by model | Cap on output length per turn | | **Top P** | 0 – 1 | Nucleus sampling cutoff | | **Top K** | Integer | Candidate token cap | | **Frequency penalty** | -2 – 2 | Discourages repetition | | **Presence penalty** | -2 – 2 | Encourages new topics | | **Max steps** | Integer (default 5) | How many tool-call cycles the agent can run per turn | | **Max retries** | Integer | Retries on provider errors | ## Saving Click **Save**. The agent is created immediately. Tool permissions default to the regular-user baseline — open the new agent's detail page and visit the **Tools** tab to adjust. See [Tool Permissions](/user-guide/agents/tool-permissions). ## Default agent Each organization can have one **default agent**, marked with a badge in the list. The default agent is what Bizzy suggests when you haven't picked another one explicitly. To mark an agent as default, toggle the flag on its detail page. ## Next steps Available OpenRouter models Decide what the agent can do # Agents Source: https://docs.bizzyco.ai/user-guide/agents/index Create interactive AI assistants with custom system prompts, tool permissions, and model selection Beta Agents are interactive AI assistants you can chat with inside Bizzy. Each agent has its own system prompt, model, and per-tool permissions, so you can make an agent that answers support email one way and a research agent that behaves entirely differently. Agents list ## Agents vs. Automations **Agents** are interactive — you open a chat window and talk to them, and they can ask for your approval before running tools. **[Automations](/user-guide/automations/index)** are event-triggered — they fire automatically on events like "new email received" without a human in the loop. The two complement each other: automations handle recurring, well-defined work; agents handle ad-hoc, exploratory work. ## What you can do Name, type, system prompt, model, LLM settings Claude, GPT, Gemini — via OpenRouter Allow / ask / deny each tool Full-page chat with tool approval Conversations with an agent are saved and visible in [Agent Conversations](/user-guide/agent-conversations/index), including the full tool-call history. # Agent Models Source: https://docs.bizzyco.ai/user-guide/agents/models LLM models available for Bizzy agents via OpenRouter Bizzy agents run through [OpenRouter](https://openrouter.ai), which exposes a unified API over Anthropic, OpenAI, and Google models. ## Available models | Model | Typical use | | --------------------------------- | -------------------------------------------------------------- | | **Claude Sonnet 4.6** *(default)* | Balanced reasoning + cost for most agent tasks | | **Claude Haiku 4.5** | Fast, cheap — great for simple classification or short replies | | **Claude Opus 4** | Hardest reasoning, highest cost | | **GPT-4o** | Strong general model with broad tool use | | **GPT-4o Mini** | Smaller GPT-4o for cost-sensitive work | | **Gemini Flash** | Low-latency Google model | | **Gemini Pro** | Higher-capability Google model | No tier gating today — every organization can select any of these models. Usage is billed by the token, converted into Bizzy credits. See [Admin Guide → Billing](/admin-guide/billing/index) for how credits work. ## Picking a model Rough guidance: * **Default to Claude Sonnet 4.6.** It hits the best balance of quality and cost for most agent workloads. * **Move to Haiku or Flash** if latency and per-call cost matter more than reasoning depth (for example, a classifier agent that only picks a label). * **Move to Opus** only when a task consistently fails at Sonnet — the cost delta is substantial. ## Changing the model Open the agent's detail page and edit the **Model** field. The change applies to all new conversations; conversations already in progress continue on whichever model they started. ## Next steps Control what the agent can do The chat UI # Tool Permissions Source: https://docs.bizzyco.ai/user-guide/agents/tool-permissions Allow, ask, or deny each tool an agent can call Agents can use Bizzy tools — things like "read contact," "send email," "create task." You control what each agent is allowed to do on a per-tool basis. Tool permissions tab ## The three permission levels Each tool on each agent is set to one of three values: | Level | Icon | Behavior | | --------- | ------------- | ------------------------------------------------------ | | **Allow** | Green check | Agent calls the tool silently — no interruption | | **Ask** | Blue question | Agent pauses and requests your approval before calling | | **Deny** | Red X | Tool is hidden from the agent entirely | The "Ask" approval appears inline in the chat with a countdown timer and a risk-level badge. You can expand the card to see the exact tool input before approving. ## Finding the permissions UI 1. Open the agent's detail page. 2. Go to the **Tools** tab. 3. Tools are grouped by category (for example, Contacts, Messages, Tasks). Expand a category to see its tools, each with a three-way button. ## How defaults work When you create an agent, it inherits the **regular-user** baseline permissions for the organization. Tools considered sensitive default to **Ask**; lower-risk tools default to **Allow**. Your overrides are stored sparsely — only the tools where you deviate from the default are persisted. If the default shifts later (for example, we promote a new tool from risky to routine), agents inherit the new default unless you had explicitly overridden that tool. ## Risk levels Tool approval cards display a risk badge (low / medium / high) to help you decide quickly. Use your judgment: a low-risk tool misused is rarely damaging, a high-risk tool might send email from your domain or spend money. Changing permissions takes effect on the **next** tool call by the agent. A tool call already mid-flight when you change the setting will complete under the old rules. ## Next steps See approvals in action Review past approvals and denials # Creating Your First Automation Source: https://docs.bizzyco.ai/user-guide/automations/first-automation Build an AI-powered automation workflow in Bizzy This guide walks you through creating your first automation in Bizzy. By the end, you'll have a working automation that responds to events with AI-powered actions. For background on how automations work and what they can do, see [Automations Concepts](/get-started/concepts/automations). ## Prerequisites * A Bizzy account with an active organization * At least one connected email account * User permissions to create automations ## Step 1: Navigate to Automations 1. Click **Automations** in the sidebar navigation 2. View your existing automations (if any) 3. Click **Create Automation** or **New Automation** Create automation form ## Step 2: Name Your Automation Give your automation a clear, descriptive name: * **Good**: "Support Email Auto-Acknowledgment" * **Good**: "New Lead Welcome Message" * **Avoid**: "Automation 1" or "Test" The name helps you identify the automation later and understand its purpose at a glance. Automation names must be unique within your organization and under 100 characters. ## Step 3: Define the Trigger Event Specify what event should trigger this automation: ### Common Trigger Events | Event | When It Fires | | ------------------ | ------------------------------------------- | | New email received | An incoming email arrives in your inbox | | Contact created | A new contact is added to your organization | | Message sent | An outgoing email is sent | Enter a description of your trigger event. Be specific about when you want the automation to run. **Example triggers:** * "When a new email arrives from a domain ending in .edu" * "When a contact is created without a company name" * "When an email subject contains 'urgent' or 'help'" ## Step 4: Write Your Instructions This is where you tell the AI what to do when the trigger fires. Write in natural language as if you were instructing a colleague. Be specific about the action, tone, and any conditions. Here's an example for a support auto-reply: ``` When a support email arrives: 1. Send an acknowledgment reply 2. Thank them for contacting support 3. Mention we typically respond within 24 hours 4. If they mention "urgent", add that we'll prioritize their request 5. Keep the tone friendly and professional 6. Keep the reply under 100 words ``` Instructions have a 5,000 character limit. If you need more complex logic, consider splitting into multiple automations. ## Step 5: Save and Enable Once you've configured your automation: 1. Review your settings 2. Click **Save** or **Create** to save the automation 3. The automation is enabled by default and starts running immediately ## Testing Your Automation After creating your automation: 1. **Trigger a test event** - Send yourself an email or perform the trigger action 2. **Check the results** - Verify the automation performed as expected 3. **Adjust if needed** - Edit the instructions to refine the behavior ## Managing Automations ### Viewing Automations All your automations are listed on the Automations page, showing: * Automation name * Trigger event * Status (enabled/disabled) * Last run time ### Enabling/Disabling Toggle an automation on or off: 1. Navigate to **Automations** 2. Find the automation 3. Click the enable/disable toggle Disabled automations don't run but retain their configuration. ### Editing Automations To modify an existing automation: 1. Click on the automation name 2. Update the fields as needed 3. Save your changes Changes take effect immediately for enabled automations. ### Deleting Automations To remove an automation: 1. Open the automation 2. Click **Delete** 3. Confirm the deletion Deleted automations cannot be recovered. Consider disabling instead if you might need it later. ## Example: Complete Automation Walkthrough Let's create a complete automation for acknowledging support emails: ### Configuration | Field | Value | | ----------------- | ----------------------------------------------------------------------- | | **Name** | Support Email Auto-Acknowledgment | | **Trigger Event** | New email received to [support@company.com](mailto:support@company.com) | | **Instructions** | See below | ### Instructions ``` When a new email arrives at the support address: 1. Send an immediate acknowledgment reply 2. Include these elements: - Thank them for contacting our support team - Confirm we received their message - Set expectations: we respond within 24 hours (Mon-Fri) - For urgent issues, mention they can call our hotline 3. Tone guidelines: - Professional but warm - Empathetic if they describe a problem - Concise - keep under 100 words 4. Sign off with: - "Best regards" - "The Bizzy Support Team" ``` ### Expected Result When someone emails [support@company.com](mailto:support@company.com), they'll receive a reply like: > Thank you for contacting Bizzy Support! We've received your message and a > member of our team will respond within 24 business hours. > > If your issue is urgent, you can reach our priority support line at > 1-800-XXX-XXXX. > > Best regards, The Bizzy Support Team ## Troubleshooting ### Automation Not Triggering | Issue | Cause | Solution | | ----------------- | ------------------------ | --------------------------------------- | | No action taken | Automation disabled | Check and enable the automation | | Wrong events | Trigger too specific | Broaden the trigger event description | | Permission denied | Insufficient permissions | Contact your admin to check permissions | ### Unexpected Results | Issue | Cause | Solution | | ------------------- | -------------------- | ---------------------------- | | Wrong tone | Instructions unclear | Add explicit tone guidelines | | Missing information | Context not provided | Add context to instructions | | Too verbose | No length guidance | Add word or sentence limits | ## Next Steps Connect more email accounts Organize contacts for automations # Automations Source: https://docs.bizzyco.ai/user-guide/automations/index Set up automated workflows in Bizzy Automations let you create AI-powered workflows that respond to events automatically. For background on how automations work, see [Automations Concepts](/get-started/concepts/automations). ## Getting Started Step-by-step guide to building an automation Build a complete AI-powered support workflow from scratch ## Common Use Cases | Scenario | Trigger | Action | | ------------------- | -------------------------- | ------------------------- | | Auto-acknowledgment | New email received | Send confirmation reply | | Lead qualification | Contact form submission | Categorize and route lead | | Support triage | Support email | Tag by urgency and type | | Meeting scheduling | Email with meeting request | Propose available times | # AI Suggestions Source: https://docs.bizzyco.ai/user-guide/businesses/ai-suggestions Let Bizzy draft your business profile, offerings, and presences Every section of the Business page has a **Suggest** button that uses an LLM to draft content based on what you've already filled in. It's the fastest way to go from an empty profile to a useful one. AI suggestions review modal ## How suggestions work 1. Click **Suggest** on any block (Name, Description, Industries, Offerings, Online Presences, Physical Presences). 2. Bizzy sends the existing business context to the LLM and asks for **1–5 suggestions** for that section. 3. A modal shows the suggestions. Select the ones you want. 4. Click **Add** — the selected items are created in a single batch operation. The LLM is instructed to avoid duplicating items you already have, so repeat clicks generally produce new ideas rather than the same ones again. ## What gets sent to the LLM * Your business name * Business description * Industries you've selected * Other entities already on the page (for context and to avoid duplicates) Nothing is sent except what you've already typed into the Business page. ## Per-type behavior | Block | Typical suggestions | | ---------------------- | -------------------------------------------------------- | | **Name** | Cleaner or more formal versions of what you typed | | **Description** | A drafted paragraph based on name + industries | | **Industries** | Categories that might apply given name + description | | **Offerings** | 3–5 likely products/services based on industries | | **Online presences** | Guessed URLs for website and common social platforms | | **Physical presences** | Rarely useful — the LLM doesn't know your real addresses | ## Rate limiting Suggestions are rate-limited to **10 requests per minute per user**. If you hit the limit, wait a minute and try again. ## When to trust suggestions * **Always review.** Especially URLs and addresses — AI guesses can look right and be wrong. * **Prefer editing to accepting verbatim.** The suggestion is a draft; shape it to match your actual business. * **Combine with manual input.** Use suggestions to start a section, then edit. ## Next steps Review the core fields Iterate on what you sell # Business Source: https://docs.bizzyco.ai/user-guide/businesses/index Describe your business to Bizzy so agents and automations have accurate context The **Business** page is a single source of truth for what your organization does, where it operates, and how it sells. Agents, automations, and AI suggestions all reference this information, so filling it in meaningfully pays dividends across the product. Business profile page ## What lives on this page Name, description, industries Products and services you sell Online and physical locations LLM-generated drafts for every section Link your Stripe account for customer sync ## Why this matters When an agent drafts an email, when an automation classifies a message, when the platform shows you a Customers list — they all use Business information to ground their behavior in your actual context. A generic "we're a business" profile produces generic outputs; a detailed profile with offerings, presences, and industries produces outputs that actually sound like you. ## Where this data is used * **Agents** read the business profile as part of their context when composing replies. * **Automations** use offerings and industries to classify and route inbound messages. * **Customers** sync from Stripe is scoped to the primary business (via Stripe Connect). ## Next steps Start with the essentials Let Bizzy draft your profile # Offerings Source: https://docs.bizzyco.ai/user-guide/businesses/offerings Describe the products and services your business sells Offerings are the products and services you provide. Bizzy uses them when classifying inbound messages, drafting outbound replies, and surfacing relevant context to agents. Offerings list ## Per-offering fields | Field | Notes | | --------------- | ------------------------------------------------------ | | **Name** | Short label — "Basic Tune-Up", "Enterprise Onboarding" | | **Description** | Prose description of what the offering includes | | **Is service** | Toggle — `true` for services, `false` for products | The service vs. product toggle affects how agents phrase things (for example, "the service lasts 2 hours" vs. "the product ships in 2 days"). ## Adding offerings 1. Scroll to the **Offerings** block on the Business page. 2. Click **Add Offering**. 3. Fill in name, description, and the service toggle. 4. Save. ### Bulk add with AI suggestions Instead of typing each offering, click **Suggest** on the Offerings block. Bizzy returns 1–5 offerings based on your business profile; select the ones to add and commit them all at once. ## Editing Click any offering row to edit in place. Changes save on the next **Save** click. ## Removing Use the row menu → **Delete** to remove an offering. Deletion is immediate. ## Tips * Stay concrete. "Consulting" is weaker than "Monthly retainer: weekly 30-min calls + Slack support". * Keep descriptions short enough that an agent's context window can include several of them at once. ## Next steps Online and physical locations Draft offerings with the LLM # Online and Physical Presences Source: https://docs.bizzyco.ai/user-guide/businesses/presences Link websites, social accounts, listings, and physical addresses to your Bizzy business Presences tell Bizzy where your business shows up in the world — online and offline. Agents and automations use them for context and to build accurate replies (e.g., embedding your website URL in a signature). ## Online presences Each online presence has: | Field | Notes | | --------------- | -------------------------------------------------------------------------------- | | **URL** | Full URL, including `https://` | | **Type** | `Website`, `Social`, or `Listing` | | **Provider** | Brand label when applicable (Facebook, Instagram, Google Business Profile, etc.) | | **Description** | Optional prose context | Typical examples: * **Website:** `https://yourbusiness.com` * **Social:** your Instagram / LinkedIn / Facebook pages * **Listing:** Google Business Profile, Yelp, industry directories ### Adding Click **Add Online Presence** on the Business page. Pick a type and provider; paste the URL; save. ### AI suggestions The **Suggest** button on the Online Presences block proposes likely URLs based on your business name. These are best-guesses and may or may not actually belong to you. AI-generated URLs can be wrong or impersonate other businesses. Always review suggestions before accepting — the UI displays a disclaimer for this reason. ## Physical presences Each physical presence has: | Field | Notes | | --------------- | ----------------------------------------------------------------------- | | **Address** | Street / city / state / ZIP (or local equivalent) | | **Description** | Optional context — "main office", "east bay service area", "storefront" | Use physical presences for any location that matters to your business — offices, shops, service areas, warehouses. ### Adding **Add Physical Presence** → fill in address → save. ### AI suggestions Physical suggestions are weaker than online ones because the LLM has less reliable signal. Review carefully. ## Next steps How suggestions work across the page Link Stripe for customer sync # Business Profile Source: https://docs.bizzyco.ai/user-guide/businesses/profile Name, description, and industries for your Bizzy business The profile block is the core "who are you" section. Agents and automations read these fields directly when they need context about your organization. ## Fields ### Name Your business's public name. Agents use this in greetings and signatures. ### Description A longer prose description — what you do, who you serve, and how. This is a rich-text editor, so you can use headings, lists, and emphasis. Keep the description specific. "A company that sells things" gives agents nothing to work with; "a small roofing company in Northern California that handles residential replacements and inspections" gives them plenty. ### Industries A multi-select tag input. Pick every industry that fits — you can (and should) select multiple if your business straddles categories. Industries are stored on the business profile and feed into: * Automation classification (e.g., "is this a sales or support inquiry?") * AI suggestions across other sections * Customer segmentation ## Saving Edits save via the **Save** button under each block. Validation is light — only the name has a length cap. ## Using AI suggestions Every field supports AI suggestions — see [AI Suggestions](/user-guide/businesses/ai-suggestions). For the profile, suggestions draft a description and propose industries based on whatever you've already filled in. ## Next steps Add what you sell Add where you sell # Stripe Connect Source: https://docs.bizzyco.ai/user-guide/businesses/stripe-connect Link your Stripe account to Bizzy to sync customers and payments Stripe Connect is the OAuth handshake that lets Bizzy read customer data from your Stripe account. Once linked, your Stripe customers appear in the [Customers](/user-guide/customers/index) section. Stripe Connect card on the Business page ## Prerequisites * An existing Stripe account. If you don't have one, create it at [stripe.com](https://stripe.com). * Owner or Admin role in Bizzy — the Stripe Connect card is visible to everyone, but connecting runs under Owner/Admin authority. ## Connecting 1. Scroll to the **Stripe Connect** card on the Business page. 2. Click **Connect Stripe**. A Stripe-hosted page opens in a new tab. 3. Log in to Stripe and confirm the connection. 4. Stripe redirects you back to Bizzy. The card now shows your Stripe account as linked. Behind the scenes, Bizzy stores a `stripeAccountId` on the business record. That ID scopes every customer sync and billing action. ## What Connect enables * **Customer sync.** Stripe customers flow into Bizzy [Customers](/user-guide/customers/index). * **Account metadata.** Stripe's payout currency, country, and other profile fields become visible. ## What Connect does *not* do * **Bizzy's billing.** Your Bizzy subscription is unaffected by the Connect link. You still pay Bizzy separately — see [Admin Guide → Billing](/admin-guide/billing/index). * **Write to Stripe.** Today, sync is read-only from Stripe → Bizzy. There is no "create customer in Stripe from Bizzy" flow. ## Disconnecting Revoke the connection from your Stripe dashboard (Settings → Connected Accounts). When you revoke, Bizzy loses read access; existing synced customer records remain in your Customers list but no longer update. ## Troubleshooting | Problem | Likely cause | Fix | | -------------------------------- | ------------------------------------ | ---------------------------------------------- | | OAuth popup blocked | Browser blocker | Allow popups from Bizzy and retry | | "Connection failed" after Stripe | Stripe account requires verification | Complete Stripe onboarding, then retry | | Customers don't appear | Sync in progress | Wait a few minutes; initial sync can take time | ## Next steps See your synced customers How sync actually works # Contacts Source: https://docs.bizzyco.ai/user-guide/contacts/index Manage your contacts in Bizzy Bizzy's contact management helps you organize and maintain information about the people you communicate with. Store contact details, track conversation history, and build relationships with your business contacts. ## Features | Feature | Description | | ---------------- | ------------------------------------------ | | Contact Profiles | Store names, companies, and job titles | | Multiple Emails | Track multiple email addresses per contact | | Phone Numbers | Store phone numbers with country codes | | Addresses | Save physical addresses for contacts | | Message History | View all messages with each contact | | Profile Images | Add photos to contact profiles | ## Getting Started Add, edit, and organize your contacts ## Contact Data Each contact in Bizzy can include: * **Name** - First name, last name, and display name * **Company** - Organization or business affiliation * **Job Title** - Professional role or position * **Email Addresses** - Multiple emails with labels (work, personal, etc.) * **Phone Numbers** - Multiple numbers with country codes * **Addresses** - Physical addresses with full details * **Notes** - Internal notes about the contact * **Profile Picture** - Visual identifier for the contact ## Automatic Contact Creation Bizzy automatically creates contact records when: * You receive an email from a new sender * You send an email to a new recipient These auto-created contacts can be enriched with additional details as needed. Contact data is scoped to your organization. Team members with appropriate permissions can view and edit shared contacts. # Managing Contacts Source: https://docs.bizzyco.ai/user-guide/contacts/managing Add, edit, and organize contacts in Bizzy This guide covers how to create, edit, and manage contacts in Bizzy. Keep your contact information organized to improve communication and enable powerful automations. Bizzy contacts list ## Viewing Contacts Access your contacts from the main navigation: 1. Click **Contacts** in the sidebar 2. Browse the contact list or use search to find specific contacts 3. Click a contact to view their full profile The contact list displays: * Contact name and profile picture * Company and job title * Primary email address * Quick action buttons ## Adding a New Contact To create a new contact: 1. Navigate to **Contacts** 2. Click the **Add Contact** button 3. Fill in the contact details: * First name and last name * Company and job title * Email addresses * Phone numbers * Addresses 4. Click **Save** to create the contact ### Required Fields At minimum, a contact needs one of the following: * First name or last name * Email address All other fields are optional and can be added later. ## Editing Contact Details Contact detail view ### Basic Information To edit a contact's basic information: 1. Open the contact profile 2. Click **Edit** or click directly on the field you want to change 3. Update the information: * **First Name** / **Last Name** - The contact's name * **Company** - Their organization or employer * **Job Title** - Their role or position * **Title** - Honorific prefix (Mr., Ms., Dr., etc.) * **Notes** - Internal notes about this contact 4. Changes save automatically ### Profile Picture Add or change a contact's profile picture: 1. Open the contact profile 2. Click the profile picture area or the **Upload Image** button 3. Select an image file from your computer 4. The image uploads and displays on the profile Supported formats: JPG, PNG, GIF (max 5MB) ## Managing Email Addresses Contacts can have multiple email addresses with labels. ### Adding an Email 1. Open the contact profile 2. Navigate to the **Emails** section 3. Click **Add Email** 4. Enter the email address 5. Optionally add a label (e.g., "Work", "Personal") 6. Click **Save** ### Editing an Email 1. Find the email in the contact's profile 2. Click the **Edit** button next to the email 3. Update the address or label 4. Click **Save** ### Deleting an Email 1. Find the email in the contact's profile 2. Click the **Delete** button 3. Confirm the deletion Deleting an email address also removes its association with message history. The messages remain but won't be linked to this contact via the deleted email. ## Managing Phone Numbers Store multiple phone numbers with international support. ### Adding a Phone Number 1. Open the contact profile 2. Navigate to the **Phone Numbers** section 3. Click **Add Phone Number** 4. Enter the phone number 5. Select the country code 6. Click **Save** ### Phone Number Format Phone numbers are stored with: | Field | Description | Example | | --------------- | -------------------- | ----------------- | | Phone Number | Full number | +1 555 123 4567 | | Country Code | International prefix | +1 (US), +44 (UK) | | National Number | Local format | 555 123 4567 | ## Managing Addresses Store physical addresses for contacts. ### Adding an Address 1. Open the contact profile 2. Navigate to the **Addresses** section 3. Click **Add Address** 4. Fill in the address fields: * Address Line 1 (street address) * Address Line 2 (apartment, suite, etc.) * City * State/Province * Postal Code * Country 5. Click **Save** ### Address Fields | Field | Description | Required | | -------------- | ------------------ | -------- | | Address Line 1 | Street address | No | | Address Line 2 | Additional info | No | | City | City name | Yes | | State | State or province | No | | Postal Code | ZIP or postal code | No | | Country | Country name | Yes | ## Viewing Message History See all communications with a contact: 1. Open the contact profile 2. Navigate to the **Messages** section 3. Browse messages sent to/from this contact 4. Click a message to open it in the inbox Messages are displayed chronologically with: * Date and time * Subject line * Message preview * Direction (incoming/outgoing) ## Deleting Contacts To remove a contact from your organization: 1. Open the contact profile 2. Click **Delete Contact** (usually in a menu or at the bottom) 3. Confirm the deletion Deleting a contact is a soft delete. The contact is removed from views but data is preserved for compliance. Contact support if you need permanent deletion. ## Troubleshooting ### Contact Not Saving | Issue | Cause | Solution | | ------------------------- | ----------------------- | ------------------------------------------ | | Save button disabled | Required fields missing | Ensure name or email is provided | | Error on save | Invalid data format | Check email format and phone number format | | Duplicate contact warning | Contact already exists | Search for existing contact and merge | ### Missing Contacts | Issue | Cause | Solution | | --------------------- | -------------------- | ----------------------------------- | | Contact not appearing | Search filter active | Clear search and filters | | Contact deleted | User removed contact | Contact cannot be recovered by user | ## Next Steps View messages from your contacts Create automated workflows for contacts # Customers Source: https://docs.bizzyco.ai/user-guide/customers/index Browse customers synced from your Stripe account into Bizzy The **Customers** section shows the customers on your primary business's Stripe account. Think of it as a CRM-style view over Stripe data — unified with the rest of Bizzy so agents and automations can reference customer context. Customers list with Stripe-synced badges ## The list Each row shows: | Column | Notes | | ------------------ | -------------------------------------------- | | **Name** | From Stripe | | **Email** | From Stripe | | **Customer since** | Stripe creation date | | **Stripe badge** | Green badge if the row is synced from Stripe | ### Filters * **Search** — matches name and email. * **Sync filter** — `All` / `Synced from Stripe` / `Not synced`. ## Customer detail Click a row to open the customer's detail page. You'll see: * Contact information (name, email) * Stripe-sourced metadata (customer since, Stripe customer ID if synced) * Related context from Bizzy when applicable ## Prerequisites For the Customers section to be populated, you need: 1. A linked Stripe account — see [Stripe Connect](/user-guide/businesses/stripe-connect). 2. Customers in that Stripe account. If Stripe isn't linked yet, the list will be empty and you'll see guidance pointing you to connect. ## Limitations today * **Read-only from Stripe.** The current UI displays Stripe customers — it doesn't create them. New customers show up only after they exist in Stripe. * **No manual "sync now".** Sync happens automatically; there's no button to force an immediate refresh. * **No customer ↔ contact mapping.** Customers and [Contacts](/user-guide/contacts/index) are separate entities today; linking them explicitly is not yet supported in the UI. ## Next steps Understand the data flow Link Stripe to populate this list # How Customer Sync Works Source: https://docs.bizzyco.ai/user-guide/customers/sync The data flow between Stripe and Bizzy Customers Customer sync is **Stripe → Bizzy**, scoped to your primary business's connected Stripe account. ## What triggers a sync * **Initial sync** runs when you first connect Stripe — existing customers are imported in a batch. * **Ongoing sync** runs on Stripe webhooks. New customers and updates to existing customers propagate to Bizzy automatically. There is no manual "sync now" button today. Webhook propagation is usually within seconds. ## Sync scope * Only the Stripe account you linked via [Stripe Connect](/user-guide/businesses/stripe-connect) is synced. * The linked account is scoped to your **primary** business. In a multi-business setup, the other businesses' customers don't appear here. ## What gets synced * **Name** * **Email** * **Customer ID** (`stripeCustomerId`, used to detect that a row is synced) * **Customer creation date** (displayed as "Customer since") Stripe-specific metadata that Bizzy doesn't surface today (tax IDs, shipping addresses, metadata keys) remains in Stripe. Contact support if you need a specific field pulled through. ## Detecting sync status * **Synced** customers have a green **Stripe** badge in the list and a populated `stripeCustomerId`. * **Not synced** customers are rows added in Bizzy directly — today this path is rare because the UI doesn't expose customer creation, but some API/MCP callers do. The **Sync filter** in the list lets you narrow to synced or not-synced. ## What does NOT sync * **Bizzy → Stripe.** Edits in the Customers list do not push back to Stripe. Customer data in Stripe is authoritative. * **Deletion.** Deleting a customer in Stripe does not delete the Bizzy record automatically — it stays visible until support removes it (or a future sync pass handles soft-deletes). ## When sync breaks | Symptom | Likely cause | Fix | | ----------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------- | | New Stripe customer not showing | Webhook delivery delay or failure | Wait a few minutes; if still missing, check Stripe's event log | | Stripe disconnected | OAuth revoked | Reconnect from [Stripe Connect](/user-guide/businesses/stripe-connect) | | Initial import didn't populate everything | Rate limits on large Stripe accounts | Contact support | ## Next steps Back to the list view Link or relink Stripe # Domain Events Source: https://docs.bizzyco.ai/user-guide/domains/events Audit trail of status transitions and actions on a Bizzy domain Each domain has an events timeline on its detail page. The timeline is your audit trail for verifications, registration milestones, and status changes. Domain events timeline ## What shows up Events are logged for the transitions that matter: | Event | Fires when | | ---------------------- | ---------------------------------------------------------- | | Domain created | You added the domain (via verify or register) | | Verification check | The verification workflow ran against DNS | | Verification succeeded | TXT record observed, status moved to active | | Registration purchased | Stripe checkout completed | | Registration activated | DNSimple confirmed the registration | | Status changed | Any transition — pending → active, active → expiring, etc. | | Email address added | An address was created on the domain | The exact set depends on the source (registered vs. verified) and how old the domain is. ## Reading the timeline * Most recent event appears at the top. * Each event shows a timestamp and a short description. * For verification-related events, the full DNS resolution context is typically included. ## When this is useful * **Debugging verification.** If a domain stays stuck in pending, the timeline shows what the verification workflow actually saw in DNS. * **Audit.** If a domain unexpectedly lost active status, the timeline tells you when and, often, why. * **Compliance.** If someone asks "when did we add this domain," the answer is here. ## Next steps Back to verification Buy one through Bizzy # Domains Source: https://docs.bizzyco.ai/user-guide/domains/index Verify or register a domain to send email from Bizzy A domain is the piece before the `@` in an email address. Bizzy needs your domain to be verified — and optionally registered through us — before you can send from addresses on it. Domains list ## Two ways to get a domain Add a TXT record at your DNS provider — free Buy through Bizzy via DNSimple — Stripe checkout ## Status states Each domain has a status — visible as a badge in the list: | Status | Meaning | | ---------- | -------------------------------------------------------------------------------------------- | | `pending` | Awaiting verification (TXT record hasn't been seen yet) | | `active` | Verified and healthy — ready for [email addresses](/user-guide/email-addresses/bizzy-hosted) | | `expiring` | Registration renewal due within 7–30 days | | `expired` | Registration has lapsed — domain is non-functional | ## Source The list also shows each domain's source: * **Registered** — bought through Bizzy via DNSimple + Stripe * **Verified** — owned elsewhere; verified via TXT record ## Events Each domain has an events timeline (on its detail page). See [Domain Events](/user-guide/domains/events) for what you can learn from it. ## Filters and search * **Search** — matches domain names. * **Status filter** — narrow to active / pending / expiring / expired. * **Source filter** — all / registered / verified. * **Pagination** — 25 items per page. ## Next steps Add a TXT record at your DNS host Buy one through Bizzy # Registering a Domain Source: https://docs.bizzyco.ai/user-guide/domains/register Buy a new domain through Bizzy via DNSimple and Stripe checkout If you don't already own a domain, Bizzy can register one for you through [DNSimple](https://dnsimple.com). Payment runs through Stripe and the domain is auto-configured for email once the purchase completes. ## When to register vs. verify * **Register** if you're buying a fresh domain specifically for your Bizzy business. * **Verify** if you already own the domain somewhere else. See [Verify a domain](/user-guide/domains/verify). ## The registration flow 1. Go to **Domains** and click **Add Domain** → **Register a new domain** (or visit `/{org}/domains/create` directly). 2. **Search** for a domain. Bizzy queries DNSimple for availability. 3. **Pick a TLD** — the pricing list shows available extensions (`.com`, `.co`, `.io`, etc.) with their annual prices. 4. **Fill in contact details** — the registration form collects the registrant contact information required by the domain registry. 5. **Continue to payment** — the form expands to show an embedded Stripe payment form. If you have a saved card on file it appears pre-selected for one-click payment; new cards are saved automatically for future checkouts. Apple Pay, Google Pay, and Link appear inside the form when supported by your browser. 6. **Pay** — click **Pay** to confirm. Once payment succeeds the form switches to a confirmation view. Domain registration search and TLD picker ## After purchase When payment is confirmed, the form displays a confirmation view instead of navigating away automatically: * **Heading:** "Payment successful — registering …" * **Body:** "We're registering your domain now. You'll get an email when it's ready, and it will appear on your domains list within a few minutes." * **Button:** Click **Go to domains** to navigate to your Domains list. The domain appears in the list with source **Registered** within a few minutes. Initial DNS is configured automatically — you don't need to add TXT records; Bizzy already controls the zone. The domain transitions to **active** once DNS propagation completes. ## Renewals * Registered domains renew annually by default via Stripe. * The list highlights domains entering **expiring** status 7–30 days before renewal. * If payment fails and the domain reaches **expired**, you'll need to contact support to recover it. ## Troubleshooting | Problem | Likely cause | Fix | | ---------------------------------------------- | ---------------------------- | ---------------------------------------------------------------- | | "Domain not available" | Already registered elsewhere | Try a different name or TLD | | Checkout fails | Payment method issue | Update in [Billing](/admin-guide/billing/index) | | Purchase completed but domain stuck in pending | DNS propagation lag | Wait 10–30 minutes; contact support if still stuck after an hour | ## Next steps Use the new domain Verify one you already own # Verifying a Domain Source: https://docs.bizzyco.ai/user-guide/domains/verify Prove ownership of a domain you already have by adding a DNS TXT record Verification proves you control a domain — without this, Bizzy can't let you send from addresses on it. ## Prerequisites * Access to DNS at your domain registrar (or wherever DNS for the domain is hosted). * Permission in Bizzy to add domains (typically Owner or Admin). ## The verification flow 1. Go to **Domains** and click **Verify Domain**. 2. Enter the domain name (for example `example.com`). 3. Save. Bizzy generates a **verification token** for you. Verify domain dialog showing TXT record to add 4. Copy the TXT record Bizzy displays — the record name (often `@`) and the value (the verification token). 5. Add the TXT record at your DNS provider. Exact steps vary by host; most providers have a "TXT" record type in their dashboard. 6. Back in Bizzy, click **Check Verification**. The app polls DNS and updates the status once it sees the record. ## Expiry You have **7 days** to complete verification. If the TXT record isn't found by then, the pending domain is cleaned up and you can start over. ## Statuses you'll see | Status | What it means for you | | --------- | ----------------------------------------------------------------------------------------------- | | `pending` | TXT record not yet observed — still waiting | | `active` | Verified — you can now create [email addresses](/user-guide/email-addresses/bizzy-hosted) on it | ## Troubleshooting | Problem | Likely cause | Fix | | ----------------------------------- | -------------------------------------- | ------------------------------------------------------------- | | Check keeps saying "not found" | TXT record hasn't propagated | Wait 5–30 minutes; some hosts are slow | | Check finds a different value | Old TXT record cached | Verify at the DNS host that the value matches exactly | | Record is in place but not detected | Record is on a subdomain or wrong host | The record must be on the apex of the domain you're verifying | ## Next steps Use your newly verified domain Buy a new one through Bizzy instead # Bizzy-Hosted Email Addresses Source: https://docs.bizzyco.ai/user-guide/email-addresses/bizzy-hosted Create an email address on a domain you have verified with Bizzy Once a domain reaches **active** status, you can create email addresses on it. Bizzy handles sending and receiving for those addresses — you don't need to run a mail server. ## Prerequisites * At least one domain with **Active** status. See [Domains → Verify](/user-guide/domains/verify). ## Creating an address 1. Go to **Email Addresses** in the sidebar. 2. Click **Add Email Address** (or visit `/{org}/email-addresses/new` for the full-page form). 3. Select **Bizzy** as the provider. The domain dropdown lists only domains in active state. 4. Fill in the form: | Field | Notes | | --------------------- | ----------------------------------------------------------------- | | **Name** | Display name — what recipients see as the "From" | | **Email** | The local part — what comes before the `@` | | **Domain** | Select from your verified domains | | **System email** | Check this if the address is for automated sends and not a person | | **Daily send limit** | Soft cap on sends per day | | **Hourly rate limit** | Soft cap on sends per hour | 5. Click **Save**. Create email address form The new address appears in the list and is ready to use. Messages sent to it land in the [inbox](/user-guide/email/inbox); messages sent from it route through Bizzy's infrastructure (Resend). ## Limits The daily and hourly limits exist to keep deliverability healthy. If you regularly hit them, raise them — just be mindful of the reputation impact of large sudden increases on a new domain. ## Removing an address Open the address's detail page and delete it. The underlying domain is unaffected — other addresses on the same domain keep working. ## Next steps Verify or register the domain first Where incoming mail shows up # Email Addresses Source: https://docs.bizzyco.ai/user-guide/email-addresses/index Create Bizzy-hosted email addresses or connect your existing Google / Microsoft account There are two ways to get email flowing in and out of Bizzy: Create `name@yourdomain.com` on a domain you've verified. Sending is handled by Bizzy's infrastructure. Authorize Google Workspace / Gmail or Microsoft 365 via OAuth. Sending stays in your provider's outbox. ## When to pick which | Situation | Recommended | | ---------------------------------------------------------------------------------- | ---------------- | | You own a domain and want a clean `support@`, `hello@`, `info@` address | Bizzy-hosted | | You already use Gmail / Google Workspace for personal email | Connect external | | You already use Microsoft 365 / Outlook | Connect external | | You want automations to send from a generic mailbox your team doesn't have to open | Bizzy-hosted | Both paths feed the same [unified inbox](/user-guide/email/inbox). You can mix: connect a personal Gmail for one sender and host `support@` through Bizzy for another. ## Prerequisites * **Bizzy-hosted:** you need a domain in **active** verified state. See [Domains → Verify](/user-guide/domains/verify) to add one. * **External:** your Google Workspace admin or Microsoft 365 admin may need to approve the app. No prep is required for personal Gmail. ## Next steps Create an address on a verified domain OAuth flow for Google and Microsoft # Creating an Email Template Source: https://docs.bizzyco.ai/user-guide/email-templates/creating Write a template with variables and validate it against Bizzy templating rules 1. Go to **Email Templates** in the sidebar. 2. Click **Add Email Template**. 3. Fill in the form. Create email template dialog ## Fields | Field | Limit | Required | | --------------- | --------------------- | -------- | | **Name** | 1 – 200 characters | Yes | | **Subject** | 1 – 1,000 characters | Yes | | **Body** | 1 – 50,000 characters | Yes | | **Description** | 0 – 2,000 characters | No | ## Template variables Use `{{mustache}}` syntax anywhere in the subject or body: ``` Subject: Welcome to {{business_name}}, {{first_name}}! Body: Hi {{first_name}}, Thanks for signing up — we're excited to have you. If you need help, just reply to this email. Cheers, {{sender_name}} ``` Bizzy extracts every `{{variable}}` automatically. There's no separate step to declare them — just use them where you want them filled in. ### What the preview shows The template detail page has a **Preview** tab that lists every extracted variable. You can fill sample values and see the rendered subject and body update live. ## Validation Bizzy validates the subject and body for Mustache syntax errors on save — for example, an unclosed `{{` or a dangling `}}`. You cannot save a template whose syntax is invalid. Variables that aren't provided at send time render as empty strings — Mustache silently skips them. If a variable is truly required, enforce that in the automation or agent that calls the template, not in the template itself. ## Active vs. archived Every template has an **active** or **archived** state. Archived templates don't appear in the automation/agent picker but remain in the list for reference and reactivation. This is a soft state — archiving does not delete history. ## Next steps Preview, versions, sends Reference a template from an automation # Email Templates Source: https://docs.bizzyco.ai/user-guide/email-templates/index Reusable email templates with variables, previews, and version history Email templates are reusable, variable-aware message bodies. Write them once and let automations or agents fill them in with specific contact data at send time. Email templates list ## When to use templates * **Repeatable sends.** Welcome emails, follow-ups, appointment confirmations. * **Automations.** An automation references a template by ID — the template evolves independently of the automation logic. * **Agent sends.** Agents can use templates via LLM tools, so the message stays on-brand even when an agent writes it. ## What a template is * A **name** (internal label) * An optional **description** * A **subject** line * A **body** (plain text or markdown) * Optional **variables** in `{{mustache}}` syntax that get filled at send time Variables are not declared explicitly — Bizzy extracts them from whatever you put in the subject and body. ## Next steps Form fields, variables, validation Preview, version history, send via automation # Using Email Templates Source: https://docs.bizzyco.ai/user-guide/email-templates/using Preview, version history, and referencing templates from automations and agents The template detail page is where you iterate on an existing template. It has tabs for editing, previewing, and reviewing version history. Email template detail tabs ## Tabs | Tab | Contents | | ------------ | ------------------------------------------------------------------ | | **Settings** | Edit name, description, subject, body. Validation runs on save. | | **Preview** | Fill sample variable values and see the rendered email update live | | **History** | Version snapshots — view or restore any previous version | ## Previewing Open the **Preview** tab: 1. The list on the left shows every variable Bizzy extracted from the subject and body. 2. Type sample values for each. 3. The rendered subject and body update as you type. Use this to verify that your variable names match what your automations actually pass. ## Version history Every meaningful change to the subject or body creates a new version. The **History** tab shows: * When the version was saved * Who saved it * A **View** button to inspect that version * A **Restore** button to promote that version back to current Restoring a version becomes the new current version — older versions remain in history. ## Sending from an automation In an automation's instructions, reference the template by name or by ID. Under the hood, the automation calls `renderEmailTemplateContent` with the variable data it has available and the rendered result goes out via the configured sender. Because Mustache silently ignores missing variables, make sure the automation actually has the data it needs before the send step. ## Sending from an agent Agents can call a `send_email` tool that accepts a template reference and a map of variable values. Tool permissions apply — see [Tool permissions](/user-guide/agents/tool-permissions) — and a human can be required to approve each send. ## Deleting Use the dropdown on the list or detail page to **Delete** a template. Deletion is soft — the row is hidden but version history and references are preserved. ## Next steps Trigger a template send from an event Ask an agent to send using a template # Connecting Email Providers Source: https://docs.bizzyco.ai/user-guide/email/connect Link your Google or Microsoft email accounts to Bizzy Connect your email accounts to Bizzy to bring all your business communications into a single, unified inbox. Bizzy uses secure OAuth authentication to access your email—we never store your email password. ## Prerequisites * A Bizzy account with an active organization * Access to a Google Workspace/Gmail or Microsoft 365/Outlook account * Permission to authorize third-party applications (may require admin approval in some organizations) ## Connecting Google Workspace / Gmail To connect your Google account: 1. Navigate to **Settings > Connected Accounts** 2. Click **Connect Google** 3. Sign in to your Google account if prompted 4. Review the permissions Bizzy is requesting 5. Click **Allow** to authorize the connection Google OAuth authorization screen ### Google Permissions When connecting Google, Bizzy requests the following permissions: | Permission | Purpose | | ------------------------- | -------------------------------------- | | View your email messages | Read incoming and sent emails | | Send email on your behalf | Allow Bizzy to send replies | | View your contacts | Access contact information for context | | View your profile | Display your name and email in the app | Bizzy only accesses the permissions you grant. You can revoke access at any time from your Google Account settings or from Bizzy. ## Connecting Microsoft 365 / Outlook To connect your Microsoft account: 1. Navigate to **Settings > Connected Accounts** 2. Click **Connect Microsoft** 3. Sign in to your Microsoft account if prompted 4. Review the permissions Bizzy is requesting 5. Click **Accept** to authorize the connection Microsoft OAuth authorization screen ### Microsoft Permissions When connecting Microsoft, Bizzy requests the following permissions: | Permission | Purpose | | ----------------- | -------------------------------------- | | Read your mail | Access incoming and sent emails | | Send mail as you | Allow Bizzy to send replies | | Read your profile | Display your name and email in the app | For Microsoft 365 business accounts, your organization's admin may need to approve Bizzy as a trusted application before you can connect. ## Managing Connected Accounts Once connected, you can manage your email accounts from **Settings > Connected Accounts**: * **View permissions** - See which permissions are granted to each connection * **Manage** - Access connection-specific settings * **Disconnect** - Remove the connection and revoke Bizzy's access ## Multiple Accounts You can connect multiple email accounts to Bizzy. Each account will: * Appear in your unified inbox * Be identified by its email address in message lists * Maintain separate authentication and permissions ## Troubleshooting ### Connection Failed | Issue | Cause | Solution | | --------------------- | --------------------------------------------- | ---------------------------------------------- | | "Access Denied" error | Organization policy blocking third-party apps | Contact your IT administrator to approve Bizzy | | Connection times out | Network or browser issue | Try a different browser or clear cookies | | "Invalid Grant" error | Authorization expired | Disconnect and reconnect the account | ### Sync Issues | Issue | Cause | Solution | | ----------------------- | ----------------------------- | ------------------------------------------------- | | Emails not appearing | Initial sync in progress | Wait a few minutes for the first sync to complete | | Old emails missing | Only recent emails are synced | Bizzy syncs emails from the last 30 days | | Sent emails not showing | Permission issue | Verify the "send email" permission was granted | ### Organization Restrictions If you're using a corporate Google Workspace or Microsoft 365 account: 1. Check if your organization allows third-party applications 2. Contact your IT administrator if you see "admin approval required" 3. Request that Bizzy be added to the approved applications list ## Security Bizzy takes your email security seriously: * **OAuth 2.0** - We use industry-standard OAuth 2.0 for authentication * **No password storage** - We never see or store your email password * **Encrypted connections** - All data is transmitted over HTTPS * **Minimal permissions** - We only request permissions necessary for the features you use ## Next Steps Learn how to navigate your unified inbox Set up automated email workflows # Inbox Overview Source: https://docs.bizzyco.ai/user-guide/email/inbox Navigate and manage your unified inbox in Bizzy The Bizzy inbox brings every connected email account and SMS-enabled phone number into a single, organized view. This guide covers how to navigate, read, and manage your messages. Bizzy inbox interface ## Inbox modes Bizzy organizes messages into four modes, switched from the sidebar: | Mode | Contents | | ------------ | ------------------------------------------ | | **Inbox** | Incoming messages that need your attention | | **Snoozed** | Messages you've snoozed to review later | | **Archived** | Messages you've archived for reference | | **Sent** | Outgoing messages you've sent | Use the URL to link directly to a mode — `/{org}/inbox/snoozed`, `/{org}/inbox/archived`, etc. ## Reading messages ### The message list Each row shows: * **Sender** — who the message is from * **Subject** — the subject line (for email) or the SMS preview (for phone) * **Preview** — first line of the body * **Time** — when the message arrived * **Attachment icon** — present if the message has attachments Click a row (or focus it and press Enter/Space) to open the message in the reading pane. ### Thread view Email replies and forwards group into conversation threads: * All messages in the thread appear together, oldest at the top. * Thread participants are shown in the header. * Expand or collapse individual messages within the thread. ### Attachments Messages with attachments show an attachment icon in the list and the full file list inside the message view. Click an attachment to preview supported formats or download the original. ## Message actions Actions are available per message from the toolbar at the top of the reading pane. ### Archive Remove a message from your Inbox while keeping it accessible: 1. Open the message. 2. Click the **Archive** button. 3. The message moves to **Archived**. ### Snooze Hide a message and have it return later: 1. Open the message. 2. Click the **Snooze** button. 3. Pick how long from the dropdown: | Option | Returns to Inbox in | | ----------- | ------------------- | | For 1 hour | 1 hour | | For 3 hours | 3 hours | | For 1 day | 24 hours | | For 3 days | 72 hours | The message moves to **Snoozed** and comes back to **Inbox** when the time elapses. Custom times and "until next week"-style options are not currently exposed. ### Delete Permanently remove a message: 1. Open the message. 2. Click the **Delete** button. Delete is permanent. Use **Archive** if you might want the message back. ### Mark as read / unread Opening a message marks it read. To toggle state without opening, use the context menu on the message row. ## Selection and bulk actions The current UI supports **one selected message at a time**. Multi-select and bulk actions (select all, bulk archive, bulk delete) are not yet available — open an issue or contact support if you need them. ## Search Search is accessed via the search bar at the top of the inbox. It queries across every connected account and mode. ## Keyboard interactions The inbox relies on standard browser focus behavior plus a few specific actions: | Interaction | What it does | | ---------------------------------- | ----------------------------------------------- | | `Tab` / `Shift+Tab` | Move focus between message rows and UI controls | | `Enter` / `Space` on a focused row | Open that message | | Click | Open a message or activate a toolbar action | Per-action keyboard shortcuts (archive, snooze, delete) are not implemented today. ## Connected accounts and numbers When multiple mailboxes or phone numbers are in play: * Each message shows which account it arrived at. * Replies default to sending from the same address that received the original. * Sent messages are grouped under the outbound channel for easy auditing. ## Troubleshooting ### Messages not loading | Issue | Cause | Fix | | ---------------------------- | ------------------------ | ------------------------------------------------------------------- | | Empty inbox on first load | Initial sync in progress | Wait for sync to complete (usually a minute or two) | | Missing recent emails | Sync delay | Refresh the page | | "Connection error" indicator | Account was disconnected | Reconnect from [Email Addresses](/user-guide/email-addresses/index) | ### Performance | Issue | Cause | Fix | | ------------------- | ---------------- | ------------------------------- | | Slow list scroll | Very large inbox | Use search instead of scrolling | | Thread won't expand | Browser cache | Hard refresh (Cmd/Ctrl+Shift+R) | ## Next steps Add more sending addresses Auto-respond to incoming mail # Email Source: https://docs.bizzyco.ai/user-guide/email/index Manage your email communications with Bizzy Bizzy integrates with your existing email providers to bring all your business communications into a single, AI-powered inbox. Connect your Google or Microsoft accounts to start managing emails more efficiently. ## Features | Feature | Description | | --------------- | ---------------------------------------------------- | | Unified Inbox | View all emails from connected accounts in one place | | Thread View | See complete conversation threads with context | | Message Actions | Archive, snooze, and manage messages efficiently | | Search | Find messages quickly across all connected accounts | | AI Processing | Let Bizzy help process and respond to messages | ## Getting Started Link your Google or Microsoft email accounts Learn how to navigate and manage your inbox ## Supported Providers Bizzy currently supports the following email providers: * **Google Workspace / Gmail** - Full integration with Gmail, including labels and search * **Microsoft 365 / Outlook** - Complete support for Outlook and Exchange Online Additional email providers may be added in future updates. Contact support if you need integration with a specific provider. # Deleting Files and Folders Source: https://docs.bizzyco.ai/user-guide/files/deletion How Bizzy handles file and folder deletion Deletion in Bizzy Files is **soft** — deleted items are hidden from the UI but retained behind the scenes. Contact support if you need to restore something recently deleted. ## Deleting a file 1. Open the file (either in a row menu or from the detail page). 2. Click **Delete**. 3. Confirm. The file disappears from the list immediately (optimistic UI). If the delete request fails, the item reappears with an error message. ## Deleting a folder Folders can be deleted from their row menu. The folder and all its contents are soft-deleted together. Large folders may take a moment to finish processing after you click Delete. The folder disappears immediately from the UI, but downstream indexes (like agent retrieval) catch up asynchronously. ## What happens to agent indexes When a file with **agent access** is deleted, its chunks are removed from the retrieval index. Agents won't be able to retrieve content from deleted files in new queries. Existing agent conversations that previously cited the file still show the original content in their transcripts. ## Restoring There is no self-serve restore UI today. Contact support with the file name and approximate deletion time to recover deleted content. ## Next steps Back to Files Account-level storage and retention # Organizing Files with Folders Source: https://docs.bizzyco.ai/user-guide/files/folders Create nested folders and navigate them in Bizzy Files Folders keep your Files section organized. You can nest folders to any depth, and the breadcrumb at the top of the page shows where you are in the hierarchy. Folder breadcrumbs in Files ## Creating a folder 1. Navigate to the folder you want the new folder to live inside (or stay at the root). 2. Click **New Folder**. 3. Enter a name. 4. Save. The folder appears in the current view. Click into it to drill down. ## Navigating * **Click a folder** to drill in. * **Click a breadcrumb segment** to jump back to that level. * **Click the root** (leftmost breadcrumb) to return to the top of the hierarchy. ## Pagination Each folder page lists up to **50 items** (files + sub-folders) per page. Use the pagination controls to walk through larger folders. ## Deleting a folder Open the folder's menu and choose **Delete**. The folder and its contents are soft-deleted — see [Deletion](/user-guide/files/deletion). ## Next steps Add files into your folders Make folder contents agent-readable # Files Source: https://docs.bizzyco.ai/user-guide/files/index Upload, organize, and share files in Bizzy — with optional agent access for RAG-powered retrieval The Files section holds documents attached to your organization — contracts, manuals, reference docs, whatever agents or teammates need to read. Files can optionally be made accessible to [agents](/user-guide/agents/index), which indexes them for retrieval. Files list with folders and breadcrumbs ## What you can do Drag-drop or the upload dialog Nested folders with breadcrumb navigation Make files searchable by agents Soft-delete semantics ## Limits Storage is counted against your organization's allocation. See [Admin Guide → Billing](/admin-guide/billing/index) for current limits and overage behavior. # Agent Access & RAG Indexing Source: https://docs.bizzyco.ai/user-guide/files/rag-indexing Let Bizzy agents search and retrieve content from your uploaded files Files can optionally be made **agent-accessible**. When a file is agent-accessible, Bizzy indexes its contents for retrieval — so an [agent](/user-guide/agents/index) can pull relevant passages into its context when answering questions. ## The agent-access flag Every file has a boolean **agent access** flag: | State | What it means | | ------------------------------------------ | --------------------------------------------------- | | **Agent Access** (default off for privacy) | The file's contents can be retrieved by agents | | **No Agent Access** | The file exists in Files but is invisible to agents | The flag is set at upload time and shown as a badge on the file detail page. Agent access badge on file detail page ## How indexing works When you enable agent access: 1. Bizzy splits the file into semantic chunks using a **structural markdown chunker** — sections, paragraphs, and other structural boundaries rather than fixed-size windows. 2. Each chunk is embedded and stored in the retrieval index. 3. When an agent needs information, it queries the index and receives the most relevant chunks back as context. This approach (RAG — retrieval-augmented generation) keeps the agent grounded in your actual documents rather than relying on its generic training. There is no UI indicator for index status today. Once you enable agent access, give the system a minute to finish indexing before relying on the file's content in an agent chat. ## Turning agent access on or off Edit the file (via its detail page) and toggle **Agent access**. Turning it off removes the file from the index; turning it back on re-indexes. ## What content agents see Agents see the file's **text** — extracted from the document. Binary content (images, raw PDFs without OCR) isn't indexed meaningfully; the indexer works best with markdown, plain text, and documents with recoverable text layers. ## Privacy Agent-accessible files are scoped to your organization. Agents in other organizations never see them. Within your org, any agent that has the "read files" tool permission can retrieve content. ## Next steps Enable agent access at upload time Configure which agent reads which files # Uploading Files Source: https://docs.bizzyco.ai/user-guide/files/uploading Upload files to Bizzy via drag-drop or the upload dialog Files upload directly to Bizzy storage (Cloudflare R2) and appear in the list as soon as they finish. ## Two ways to upload ### Drag and drop Drop one or more files anywhere on the Files page. The upload starts immediately. ### Upload dialog Click **Upload Files** to open the upload dialog. Select one or more files from your file picker and confirm. File upload dialog ## What you can attach per file On upload you can optionally set: | Field | Purpose | | ---------------- | -------------------------------------------------------------------------------------- | | **Description** | Short note about what the file is | | **Tags** | Free-form labels | | **Agent access** | Whether agents can read this file — see [RAG indexing](/user-guide/files/rag-indexing) | ## Where uploads land New files appear in the **current folder** — whichever folder you're viewing when you start the upload. To upload into a specific folder, navigate into it first. ## Storage limits Before any upload, Bizzy checks your organization's remaining storage allocation. If you're out of space, the upload fails with an error and no partial file is stored. Raise your allocation in [Admin Guide → Billing](/admin-guide/billing/index). ## Troubleshooting | Problem | Likely cause | Fix | | --------------------------------- | --------------------------- | ------------------------------ | | Upload fails with "storage limit" | Hit your allocation | Free up space or upgrade | | Very large file times out | Network interruption | Retry from a stable connection | | File doesn't appear in list | Browser cached the old list | Refresh the page | ## Next steps Group files into folders Let agents search file contents # User Guide Source: https://docs.bizzyco.ai/user-guide/index Learn how to use Bizzy to manage your business communications, contacts, tasks, and AI agents The User Guide covers the everyday features of Bizzy — the things you'll use to run your business. For account-level configuration (billing, team members, API keys, security), see the [Admin Guide](/admin-guide/organization/setup). New to Bizzy? Start with the [Setup Checklist](/user-guide/setup-checklist/index). It walks through the seven things worth doing first so the rest of the product works end-to-end. ## Get your inbox working Connect a mailbox or create an address on a verified domain Send and receive from addresses you control Buy phone numbers via Telnyx for voice and SMS Read, snooze, archive, and search unified messages ## Organize who and what People and companies you communicate with Customers synced from your Stripe account Track work with an urgency × importance matrix Upload documents for agents to reference ## Automate with AI Event-triggered workflows described in plain English Interactive AI assistants with tool permissions Review past agent transcripts and approvals Reusable templates with variables for sends ## Set up your business Profile, offerings, presences, Stripe Connect Verify or register domains for email History of phone numbers and other purchases Seven onboarding tasks to finish early # Buying a Phone Number Source: https://docs.bizzyco.ai/user-guide/phone-numbers/buying Search available numbers from Telnyx and purchase through Bizzy Bizzy sells phone numbers through Telnyx. Checkout runs through Stripe — the line item appears on your Bizzy invoice, not a separate Telnyx one. ## Three entry points ### From the phone numbers inventory 1. Go to **Phone Numbers** in the sidebar. 2. Click **Buy number**. 3. You land on `/{org}/phone-numbers/buy`, the search page. ### From the purchases page 1. Go to **Purchases** in the sidebar. 2. Click **Purchase Phone Numbers** (or the **Phone Numbers** quick action). 3. You land on the same search page. ### From the inbox setup wizard If you're still setting up, the **Inbox Setup Wizard** at `/{org}/inbox/setup` lets you choose "Phone" and walks through location → search → select → checkout → success. ## The purchase flow 1. **Choose a location** — pick a country (default: United States) and optionally an area code. 2. **Refine your search** (optional) — narrow the results with any of these filters: * **Pattern** — a digit or vanity string up to 7 characters (e.g. `1000`, `COURIER`). Letters are mapped to phone-keypad digits before searching, so `COURIER` matches numbers containing `2687437`. * **Type** — restrict to **Local**, **Toll-free**, or **Mobile**, or leave as **Any**. * **Capabilities** — tick **Voice**, **SMS**, or **MMS** to require those features on the returned numbers. Voice and SMS are pre-selected; unchecking everything returns numbers regardless of capability. All filters live in the URL, so a search like `/{org}/phone-numbers/buy?countryCode=US&areaCode=415&pattern=1000&phoneNumberType=local&features=voice,sms` is shareable and bookmarkable. 3. **Pick a number** — Bizzy queries Telnyx and lists available numbers with their features and monthly cost. Click the one you want. 4. **Review** — confirm the selection and the calculated total on the purchase confirmation page. 5. **Checkout** — you're redirected to Stripe to pay. 6. **Success** — you land back on Bizzy's success page, and the number attaches to your organization automatically. The `phone_number_provision` metric is emitted for billing. ## Adding a number you already own If you already have a Telnyx number and want to attach it directly: 1. Go to **Phone Numbers**. 2. Click **Add existing number** to open the inline form (or visit `/{org}/phone-numbers/new` for the full-page version). 3. Fill in: * **Name** — a label you'll recognize * **Phone number** — in E.164 format (for example `+14155550123`) * **Country code** and **Region** * **Provider** — Telnyx 4. Save. The number is now available for configuration. ## Troubleshooting | Problem | Likely cause | Fix | | ---------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | No available numbers in search | Filters too narrow, or area code out of stock at Telnyx | Loosen the pattern, switch type to **Any**, untick capabilities you don't strictly need, or try a nearby area code | | Vanity pattern returns nothing | The mapped digits don't exist in stock | Shorten the pattern (try 3–4 chars), or change the area code | | Stripe checkout fails | Payment method issue | Update in [Billing](/admin-guide/billing/index) | | Purchase succeeded but number not listed | Webhook lag | Wait 30–60 seconds and refresh | ## Next steps Turn on SMS, voice, voicemail, recording See your purchase history # Configuring a Phone Number Source: https://docs.bizzyco.ai/user-guide/phone-numbers/configuring Set SMS, voice, voicemail, and recording options on a Bizzy phone number Open any phone number from the Phone Numbers list to reach its detail page. Settings save when you submit the form. Phone number settings ## Channels Each number has three independent toggles: | Toggle | What it enables | | ------------- | ------------------------------------------------------------------------------------------------- | | **SMS** | Inbound and outbound text messaging. Incoming SMS lands in your [inbox](/user-guide/email/inbox). | | **Voice** | Inbound and outbound voice calls, governed by the voice mode below. | | **Voicemail** | Unanswered calls fall through to voicemail. | Leave channels off that you don't intend to use. ## Voice modes When **Voice** is on, choose how calls are handled: | Mode | Behavior | | ---------- | --------------------------------------------------------------- | | **WebRTC** | Calls ring into the Bizzy web app for you to answer in-browser | | **IVR** | An automated menu routes callers before (or instead of) a human | Additional modes may appear in the UI depending on what's rolled out for your account. ## Recording If recording is enabled on the number, both inbound and outbound calls are recorded. Recordings are retained per your account's retention settings — see [Admin Guide → Billing](/admin-guide/billing/index) for storage implications. Call recording laws vary by jurisdiction. In some regions you must notify or obtain consent from both parties. Check local requirements before enabling recording. ## Name and display The **Name** field is how the number appears in the Bizzy UI — it's internal only. Outbound caller ID is set by Telnyx at the provider level. ## Removing a phone number Phone number removal releases the number back to Telnyx (or disconnects it if it's a BYO number). Contact support if you need to remove a number — the current UI does not expose self-serve deletion. ## Next steps Where inbound SMS and voice events land See what you've bought # Phone Numbers Source: https://docs.bizzyco.ai/user-guide/phone-numbers/index Buy and configure phone numbers in Bizzy for voice and SMS Bizzy provisions phone numbers through [Telnyx](https://telnyx.com). Once a number is attached to your organization, you can route calls, record voice, and send and receive SMS through the [inbox](/user-guide/email/inbox). Phone numbers list ## What you can do | Action | Where | | --------------------------------- | ---------------------------------------------------------------------------- | | Search for and buy a number | Inbox Setup Wizard → phone option, or Purchases → **Purchase Phone Numbers** | | Add a number you already own | **Phone Numbers** → **Add Phone Number** | | Configure SMS / voice / voicemail | Phone number detail page | | See purchase history | [Purchases](/user-guide/purchases/index) | ## Next steps Search Telnyx and check out via Stripe Voice mode, SMS, voicemail, recording # Purchases Source: https://docs.bizzyco.ai/user-guide/purchases/index History of phone-number purchases and other account-level buys in Bizzy The **Purchases** page is your record of what you've bought through Bizzy — phone numbers today, with additional product lines rolling out. Purchases dashboard ## What's tracked here | Product | Available today | Where to buy | | -------------------------- | --------------- | ----------------------------------------------------------------- | | Phone numbers | ✅ | Purchases → **Purchase Phone Numbers**, or the inbox setup wizard | | Brand registration (10DLC) | Coming soon | — | | Campaign setup (10DLC) | Coming soon | — | **Domain registrations are not in Purchases.** Domains have their own flow on the [Domains](/user-guide/domains/register) page. This is intentional — Domains are account resources that persist and renew, while Purchases captures one-off buys of consumable or single-use items. ## The purchase history list Each row shows: | Column | Notes | | ----------- | ---------------------------------------------- | | **Type** | Phone numbers, brand, campaign | | **Date** | When you checked out | | **Items** | Phone numbers (or names) purchased | | **Amount** | Total charged in USD | | **Status** | `completed`, `processing`, `failed`, `pending` | | **Actions** | View details | ### Filters * **Search** — matches against item names / phone numbers * **Type** — filter to a specific product line ## Status banner The index shows a status banner when you land after a checkout: | URL param | Banner | | ------------- | ------------------------------------ | | `?success=1` | Success confirmation | | `?canceled=1` | You canceled checkout | | `?error=...` | Something went wrong during checkout | ## Making a purchase Click **Purchase Phone Numbers** to start the phone-number buy flow. See [Phone Numbers → Buying](/user-guide/phone-numbers/buying) for the full walkthrough. Brand and Campaign flows are stubbed in the UI and not yet functional. The tiles will activate once 10DLC support ships. ## Next steps Current purchase flow Payment methods and invoices # Setup Checklist Source: https://docs.bizzyco.ai/user-guide/setup-checklist/index Seven onboarding tasks that unlock the rest of Bizzy The Setup Checklist is a home-page widget that tracks the seven things worth doing when you first join an organization. It auto-completes as you work — most tasks finish when you create the matching entity somewhere else in the product. Setup checklist widget on the home page ## The seven tasks | # | Task | What it asks you to do | Auto-completes when | | - | --------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | 1 | **Business profile** | Fill in your business name, description, and industries | You save the [Business profile](/user-guide/businesses/profile) | | 2 | **Connect email** | Connect a Google or Microsoft account, or create an address on a verified domain | You add any [email address](/user-guide/email-addresses/index) | | 3 | **Add domain** | Verify ownership of a domain, or register one through Bizzy | You add a [domain](/user-guide/domains/index) | | 4 | **Connect phone** | Buy a phone number through Telnyx | You add a [phone number](/user-guide/phone-numbers/index) | | 5 | **Add contact** | Create your first contact record | You add a [contact](/user-guide/contacts/index) | | 6 | **Create automation** | Write a natural-language automation | You create an [automation](/user-guide/automations/index) | | 7 | **Invite team** | Send an invitation to a team member | You invite an [organization member](/admin-guide/organization/users) | ## How the widget behaves ### The first pending task is expanded The top pending task is shown with its full description and a large **Open** button that takes you to the right page. Remaining pending tasks appear as collapsed rows underneath. ### Completed tasks vanish silently There is no "Setup complete!" message. When you finish a task — by creating the matching entity — it disappears from the list. When all seven are done, the widget disappears from the home page entirely. ### Manual actions (Owner and Admin only) If you have the **Owner** or **Admin** role, each pending task also shows: * **Mark done** — complete the task without creating the entity, useful when you finished it through another path (for example, you imported a contact via API before opening the web app). * **Dismiss** — hide the task. Dismissed tasks move into a **View dismissed** section at the bottom of the widget, where you can **Restore** them later. Users without the manage-setup-tasks permission see the same list but without these buttons — the tasks still auto-complete based on entity creation. Auto-completion runs regardless of your role. Even a regular user can finish the entire checklist just by using the product; the manual buttons only exist for Owner/Admin edge cases. ## When the widget appears * **At least one task pending:** the widget renders on the home page. * **All tasks completed:** the widget is hidden. The home page shows other dashboards (Eisenhower matrix, recent activity, etc.) in its place. * **Brand-new org with no tasks yet:** the widget renders with all seven tasks pending. ## Next steps Start with task 1 Work on task 2 # Eisenhower Widget Source: https://docs.bizzyco.ai/user-guide/tasks/eisenhower-widget The urgency × importance priority matrix on your Bizzy home page The Eisenhower widget is a 2×2 grid on your home page that groups active tasks by **urgency** and **importance**. It's the fastest way to see what to work on next. Home-page Eisenhower matrix ## The four quadrants | | High importance | Low importance | | ---------------- | ------------------------------------------------------------------ | ---------------------------------------------------------- | | **High urgency** | **Do** — top-left, crisis and deadlines | **Delegate** — top-right, interruptions and batchable work | | **Low urgency** | **Schedule** — bottom-left, strategic work worth planning time for | **Eliminate** — bottom-right, candidates to drop | A task's quadrant is purely a function of the importance and urgency fields you set on it. Change either field and the task moves accordingly. ## What the widget shows * Up to **50 tasks** across the four active statuses: `backlog`, `todo`, `in_progress`, `in_review`. * Each quadrant lists the tasks that fall into it, with title, status badge, and due date if one is set. * Clicking a task takes you to its detail page. ## When the widget is visible * **At least one qualifying task:** the widget renders on the home page. * **No qualifying tasks:** the widget is hidden. Create your first task from the [Tasks page](/user-guide/tasks/managing) and it will appear. ## Tips for the quadrants * Treat **Do** as a "today" list — if it stays crowded, importance or urgency probably needs re-evaluating. * Put recurring strategic work in **Schedule** and actually block calendar time for it. * **Delegate** is where to hand work off when that's an option. * If **Eliminate** keeps filling up, consider whether those tasks belong anywhere at all. ## Next steps Create and edit tasks Auto-create tasks from incoming email # Tasks Source: https://docs.bizzyco.ai/user-guide/tasks/index Track work in Bizzy with a priority matrix based on urgency and importance Tasks in Bizzy are lightweight to-do items that integrate with the rest of your workspace — they can be created manually, surfaced from emails by automations, or produced by agents while they work. Each task is scored on two axes — **urgency** and **importance** — which place it in one of four quadrants on the home-page Eisenhower matrix. Tasks list page ## The priority matrix The urgency × importance matrix sorts work by whether it needs your attention *now* and whether it moves the needle. | | High importance | Low importance | | ---------------- | ---------------------------------- | --------------------------------- | | **High urgency** | **Do** — do these first | **Delegate** — hand off or batch | | **Low urgency** | **Schedule** — plan time for these | **Eliminate** — consider dropping | Set urgency and importance when you create a task. Change them anytime as priorities shift. ## Task fields | Field | Required | Notes | | --------------- | -------- | ------------------------------------------------------------------------------------------- | | **Title** | Yes | Short summary — this is what shows in lists | | **Description** | No | Longer context | | **Status** | Yes | Defaults to `todo` — see [statuses](#statuses) | | **Importance** | Yes | Low, Medium, or High | | **Urgency** | Yes | Low, Medium, or High | | **Due date** | No | ISO date — no default | | **Category** | No | One of: Bug Fix, Documentation, Feature Request, Meeting, Other, Planning, Research, Review | ## Statuses Tasks move through six statuses: | Status | Meaning | | ------------- | --------------------------------- | | `backlog` | Captured but not worked yet | | `todo` | Ready to pick up | | `in_progress` | Actively being worked on | | `in_review` | Waiting on review or confirmation | | `done` | Completed | | `cancelled` | Won't be done | The home-page matrix widget shows tasks in the four active statuses (`backlog`, `todo`, `in_progress`, `in_review`). ## Next steps Create, edit, filter, and search tasks The home-page priority matrix # Managing Tasks Source: https://docs.bizzyco.ai/user-guide/tasks/managing Create, edit, filter, and search tasks in Bizzy This guide covers the task list, the create form, and the detail page. ## Creating a task 1. Go to **Tasks** in the sidebar. 2. Click **Create Task**. 3. Fill in the form: * **Title** (required) * **Description** (optional) * **Category** (optional) — Bug Fix, Documentation, Feature Request, Meeting, Other, Planning, Research, or Review * **Importance** — Low, Medium, or High * **Urgency** — Low, Medium, or High * **Due date** (optional) * **Status** — defaults to `todo` 4. Click **Save**. Create task modal The task appears in the list and — if its status is active — in the home-page [Eisenhower widget](/user-guide/tasks/eisenhower-widget). ## The task list The tasks index page is a data table with a filter sidebar. ### Filters | Filter | Behavior | | -------------- | -------------------------------------------------------------------------------- | | **Search** | Matches against both task title and description | | **Category** | Select one or more categories | | **Status** | Any subset of `backlog`, `todo`, `in_progress`, `in_review`, `done`, `cancelled` | | **Importance** | Any subset of Low, Medium, High | | **Urgency** | Any subset of Low, Medium, High | ### Sorting Sort by: * **Title** * **Due date** * **Created at** Each sort supports ascending or descending order. ## The task detail page Click any task to open its detail page. The page has three tabs: | Tab | Contents | | ------------ | ----------------------------------------------------------------------- | | **Overview** | Title, description, status, priority, due date, category — all editable | | **Activity** | Timeline of status changes, edits, and system events | | **Settings** | Delete the task | Changes saved on the Overview tab take effect immediately and are recorded in Activity. ## Deleting a task 1. Open the task. 2. Go to the **Settings** tab. 3. Click **Delete**. 4. Confirm. Deleted tasks are soft-deleted — they're hidden from the UI but the history remains. Contact support if you need to restore one. ## Next steps See tasks grouped by urgency × importance Have an automation create tasks from emails