Chirps Documentation

Chirps is a RAG-powered customer support platform. Your assistant reads your real content before answering-no manual flowcharts. Visitors chat on your site; you manage everything from the dashboard at chirps.cc.

What Chirps does

• Answers from your knowledge - website crawl, PDF uploads, text snippets.
• Embeds in minutes - one script tag via embed.js.
• Captures leads - in-chat forms and booking calendars.
• Alerts your team - WhatsApp, SMS, Telegram, Discord, email dispatch.
• Voice support - browser voice calls and optional dedicated phone numbers.
• Human takeover - agents reply live from the inbox when needed.

Who it is for

• E-commerce - shipping, returns, product questions (see Shopify guide).
• SaaS - onboarding and docs deflection.
• Local services - after-hours intake and callbacks.
• Agencies - one assistant per client site.

How it differs from legacy chatbots

Documentation map

This guide covers the full platform. Start with Getting Started, then Knowledge Base, Widget, and Troubleshooting. Public help: Support and Blog.

Chirps turns your website and documents into a 24/7 AI support agent. Whether you want the AI to build it for you via prompt, or you want to manually configure it step-by-step, deployment takes just minutes.

1. Create your account

Go to Sign up and register with email/password or Google OAuth. After confirmation, sign in at Login. You will land on your dashboard workspace.

2. Choose your creation path

Click New Assistant in the sidebar or dashboard header. You will be presented with two ways to create your assistant:

Path A: Agentic Builder (Recommended)

The fastest way to build. Simply describe what you want your assistant to do in plain English, and the Chirps Agentic AI handles the rest.

• Type a prompt: E.g., 'Build a friendly real estate assistant that collects leads and answers FAQ from our site.'
• Wait 15 seconds: The AI compiles the persona, sets up lead capture forms, configures UI colors, and enables necessary tools autonomously.

Path B: Manual Setup (Classic)

If you prefer total control from the start, use the 7-step manual wizard:

1. About You: Enter business name and default website URL.
2. Learning: Choose to crawl your site, upload documents, or skip for now.
3. Language: Set primary reply language or enable multi-language support.
4. Personality: Pick a preset tone or write a custom persona.
5. Human Backup: Provide a support email and set crawl depth limits.
6. Guidelines: Add specific rules, constraints, or competitor rules.
7. Review & Launch: Confirm your settings and run the initial setup pipeline.

3. Copy your embed code

Once your assistant is created, open your assistant → Integration tab (?tab=integration). Copy the snippet:

<script>
  window.chirpsConfig = { assistantId: "YOUR_ASSISTANT_ID" };
</script>
<script src="https://chirps.cc/embed.js" async></script>

Paste before </body> on your site (or use platform guides under Integration). See Integrations for WordPress, Shopify, Webflow, and more.

4. Post-launch checklist

1. Appearance - brand colors, welcome message, starter suggestions, dark mode if needed.
2. Knowledge - verify crawled pages; add missing URLs or PDFs; click Train AI Engine.
3. Notifications - connect WhatsApp, SMS, Telegram, or email for lead alerts.
4. Conversations - test chat on your site and view logs in the dashboard inbox.

After login at chirps.cc you see a persistent sidebar, workspace switcher, and notification bell. What you can access depends on your role-owners and admins see everything; collaborators see only permitted sections.

Sidebar navigation

Workspace home

Route: /dashboard

Stats cards

• Total Assistants - deployed agents in this workspace.
• Total Sessions - unique visitor conversation threads.
• AI Satisfaction Rate - CSAT from thumbs up/down surveys.
• Message Exchanges - lifetime message count.
• Assistant Messages (Billed) - AI replies this month toward your plan cap.

Deployed Agents list

Each card shows business name, favicon, status (Online, Paused, or setup states), and links to your assistant detail page.

Workspace switcher

Switch between your personal workspace and team workspaces you belong to. Your personal workspace shows a Default badge. Billing limits always apply to the workspace owner, not the logged-in member.

Notifications bell

Team invites and alerts appear here. Accept workspace invites from the bell-there is no separate invite landing page.

Assistant command center

Each assistant opens at /dashboard/assistants/[id] with these tabs (?tab= query):

• overview - metrics and performance chart
• conversations - inbox for this assistant
• appearance - widget customizer
• artifacts - forms, booking, cards, CSAT
• notifications - dispatch channels
• integration - embed code and platform guides
• knowledge - crawl, train, harvest
• phone - voice number and dispatch add-ons
• settings - status, domain lock, rate limits, GDPR, delete

Until setup is ready, you only see the setup progress screen-not the tabs. See Assistant Tabs for every field.

Open any assistant from your dashboard. Use the tab bar to configure behavior. Click Publish Changes on Appearance after edits.

Overview tab

Route: ?tab=overview

• KPI cards: sessions, CSAT, billed AI messages, combined AI+agent messages, total messages.
• Performance Trends chart with 7 / 14 / 30 / 90 day filter.
• Monthly Cap progress bar for billed AI interactions.
• Response breakdown: AI Managed, Human Assisted, User Interactions.
• Engine Configuration summary: personality, language, knowledge source.

Appearance tab

Route: ?tab=appearance - live widget preview on the right.

Text & content

Theme & layout

• Widget Theme - Light or Dark.
• Bubble Style - circle, bar, drawer (standard or branded with logo).
• Primary Color - color picker + hex.
• Position - bottom-right, bottom-left, top-right, top-left.
• Page Visibility - all pages, only these paths, or all except (supports /* wildcards).

Feature toggles

Voice settings

When voice is enabled: pick AI Voice Model and Physical Voice (30+ options with preview).

Artifacts tab

Route: ?tab=artifacts - full guide: Artifacts & Forms

• Lead / Contact Forms - custom fields, multi-step wizards.
• Booking & Scheduling - Google Calendar OAuth, services, time slots.
• Product / Service Cards - CTA links inside chat.
• CSAT Survey - thumbs up/down with trigger rules.
• Custom artifacts - JSON schema (Starter+ / Pro tier 5+).

Notifications tab

Route: ?tab=notifications - see Notifications & Phone

Channels: WhatsApp, SMS, Telegram, Discord, Email, Webhook (Enterprise). Template variables and Test button per channel.

Integration tab

Route: ?tab=integration

Copy embed snippet and follow platform steps. All guides: Integrations.

Knowledge tab

Route: ?tab=knowledge - Knowledge Base chapter.

Communication tab

Route: ?tab=phone - buy numbers at Communications.

Settings tab

Route: ?tab=settings

General

Assistant Status toggle - Live or Inactive.

Security & access

• Authorized Domain - widget only loads on matching host (subdomains allowed).
• Developer Mode - bypass domain lock for localhost/staging.

Rate limiting

Per-visitor cap: default 30 messages per 60 minutes. Adjustable 5–500 messages, 1–1440 minute window.

Privacy & GDPR

• Require Consent to Chat - consent screen before chat opens.
• PII Data Masking - server-side redaction of emails, phones, cards.

Danger zone

Delete assistant - type exact business name to confirm.

Chirps uses RAG (Retrieval-Augmented Generation): every answer starts with a search of your indexed content. If the fact is not in your knowledge base, the assistant should escalate-not guess.

Open the Knowledge tab

In your assistant dashboard: Knowledge (?tab=knowledge). The left sidebar shows your Knowledge Blueprint-blocks, insights, and sync status.

Add a knowledge block

Click Add → Add Knowledge Block:

Add, Recrawl & Train (URLs) or Add & Train (snippets/files) saves and indexes the content.

Crawl limits

• Max pages - set at creation (1–50); capped by your plan.
• Max depth - how many link levels to follow (1–20).
• Initial wizard crawl does not consume recrawl/train credits.
• Manual Re-crawl per URL node consumes monthly recrawl quota.

Engine actions

Train AI Engine

Rebuilds embeddings from all active blocks. Consumes train quota. Run after editing content or adding blocks.

Re-crawl & Train

Re-fetches all URL nodes, then trains. Use after a site-wide pricing or policy update.

Harvest Insights from Chats

Scans conversations for knowledge gaps. Up to 3 insights per run. Review in sidebar → Graduate good insights to permanent facts.

Editor sub-tabs

• Refinery - edit cleaned text (refined_content), toggle active, per-node re-crawl.
• Identity - business name, description, language, tone, support email, guidelines.
• AI Head - raw system prompt (advanced).
• Visualization - Mermaid knowledge graph.

Fix wrong or "I don't know" answers

1. Check if the page was crawled (Knowledge sidebar list).
2. Run Re-crawl on that URL or upload a PDF with the missing info.
3. Click Train AI Engine.
4. Test the same question in the live widget.
5. If still stuck, add a short FAQ paragraph on your public site and recrawl.

Hit a quota limit? Upgrade at Billing or wait for the UTC month reset.

Visitors see a chat bubble on your site. When they open it, they get a branded panel powered by embed.js-isolated in Shadow DOM so your site CSS does not break the widget.

Launcher (bubble) styles

Configure in Appearance (?tab=appearance). Position: bottom-right, bottom-left, top-right, or top-left.

Chat features

• Messages - markdown-lite formatting, link previews, source citation pills.
• Starter suggestions - up to 3 welcome pills; tap to auto-send.
• Inline suggestions - AI-generated quick-reply pills under replies.
• Reply to message - quote an assistant reply and follow up.
• Thinking bubble - shimmer text while AI processes; updates with status labels.
• Unread badge - count on bubble when chat closed; optional preview toast + sound.

Input bar

• Text - up to 2,000 characters; Enter to send.
• Voice call - waveform button when input empty (if voice enabled).
• Dictation - mic for speech-to-text (browser Speech Recognition).
• Attach (+) - file picker or screenshot capture (Pro file upload).

File attachments (Pro)

PDF, TXT, MD, DOCX, PNG, JPG, WEBP - max 5MB. Images preview in the user bubble.

Copilot Mode (Beta)

Copilot Mode turns your website into an interactive canvas. When a user enables Copilot, the AI becomes screen-aware, gaining the ability to inspect the user's current view, select elements, and highlight answers directly on the page.

• Screen-Awareness - The AI reads exactly what the user is looking at without requiring them to copy/paste text or explain their context.
• Pencil Mode & Selection - Users can click the Pencil icon to visually select elements on the page, point to specific paragraphs, or highlight buttons, giving the AI precise context.
• Visual Navigation - The AI can highlight specific sections or elements on your website to draw the user's attention.
• Activation - Visitors can trigger Copilot Mode from the attach menu (+), the call overlay, or by pressing Escape. (Note: this feature requires a Pro or Enterprise plan).

Voice calling

Visitor-initiated

Tap voice button → full-screen overlay: timer, visualizer, mute, minimize, end call. AI greets on connect. Artifacts (forms/booking) can appear during calls.

AI-initiated

Incoming call overlay with ringtone - visitor Accept or Decline.

GDPR consent

When enabled in assistant Settings, visitors see a Privacy Notice screen with I Agree & Continue before chat opens. Pair with a Privacy Policy URL in Appearance. See Privacy Policy for your own site policy.

Dark mode

Set Widget Theme to Dark in Appearance. Thinking bubble, attach menu, GDPR screen, and message area follow the dark palette.

Human agent (visitor view)

When an agent takes over from the dashboard inbox, the header shows the agent name and avatar. There is no "Talk to human" button-escalation is triggered by the AI or your team.

Mobile

• ≤480px: chat fills the viewport.
• Expanded mode on tablet: near-fullscreen panel.
• Drawer mode: full-width bottom sheet on small screens.

Artifacts are interactive UI blocks the AI shows during conversation—forms visitors fill out, or calendars they book from. Configure them in Artifacts (?tab=artifacts).

Lead / Contact forms

• Default fields: Full Name, Email, Phone, Details.
• Add custom fields: text, email, tel, textarea, select, radio, checkbox, slider, date, url, location (map picker).
• Multi-step wizard when more than one field.
• Submit → saved to Leads + dispatch notifications.

Trigger rules

Define when the AI should show the form (e.g. "when user asks for a quote" or "after pricing question").

Booking & scheduling

1. Connect Google Calendar from the Artifacts tab (OAuth returns via calendar callback).
2. Add services with duration, category, and routing (virtual / physical / phone).
3. Set working hours, buffer time, blocked dates, and timezone.
4. Visitor picks service → date → time slot (live from calendar API) → intake form → confirm.

Success shows confirmation text and fires booking_confirmed dispatch to your notification channels.

CSAT survey

Thumbs up / down after support interactions. Feeds satisfaction metrics on the assistant Overview tab and Analytics.

Custom artifacts

JSON schema editor for bespoke components. Requires Starter+ or Pro tier 5+ (custom_artifacts). Widget shows a placeholder and fires a chirps:artifact event for custom host-page rendering.

Configure notification channels per assistant in Notifications (?tab=notifications). Buy phone numbers workspace-wide at Communications.

Dispatch events

• Lead Captured - contact form or legacy lead submitted.
• Booking Confirmed - calendar booking completed.
• Agent handoff - human takeover (when configured).

Channel reference

Template variables

Use in HTML/text templates: {{form_data}}, {{form_data_html}}, {{timestamp}}, {{lead_location}}, {{dashboard_url}}, {{booking_routing}}, {{notes}}.

Click Test on any channel to send a sample without waiting for a live event.

Buy a phone number

1. Open Communications or assistant Phone tab.
2. Choose country (US, CA, GB, AU, IE, SE, FI, EE, LT, PL) and optional area code.
3. Select a number from the search results.
4. Set voice minutes slider (60–5,000) and optional SMS/WhatsApp bundles.
5. Assign to an assistant → Subscribe & Claim via Stripe Checkout.

Voice usage

• Inbound calls answered by AI using the same knowledge as chat.
• Transcripts saved in Conversations.
• Minutes tracked against included bundle; overage billed per minute.
• AI Call Back from inbox can place outbound calls to visitors.

Standalone dispatch add-on

SMS/WhatsApp monthly bundles without buying a voice number-same checkout flow under Standalone Dispatch tab.

Manage subscriptions at Billing → Manage Billing.

The Conversations inbox is your live support queue. Leads stores form submissions. Analytics shows workspace-wide trends.

Conversations inbox

Filters

• Search by session ID.
• Status: All, Live (agent active), Online (<2 min activity), Offline.
• Type: Booking, Form.
• Assistant dropdown - workspace-wide or per-assistant tab.
• Artifact: Booking, Lead, Call.

20 conversations per page. Realtime updates when new threads start.

Conversation detail

• Full message thread (user, AI, agent roles).
• Agent Active toggle - reply as human; visitor sees your name/avatar.
• Download Transcript (.txt).
• AI Call Back - enter reason → outbound voice call.
• Linked artifacts and lead data.

Leads

Route: /dashboard/leads

• Filter: New, Contacted, Archived.
• Filter by assistant.
• Open detail sheet → update status → view linked conversation.
• Export CSV for CRM import.

Analytics

Route: /dashboard/analytics

• KPI cards, charts, hourly heatmap.
• Top assistants by session volume.
• Country breakdown and agent involvement stats.
• Date ranges: 7D, 14D, 30D, 90D.

Per-assistant metrics also appear on the assistant Overview tab (?tab=overview).

CSAT feedback

Thumbs up/down from CSAT artifacts feed into Satisfaction % on Overview and Analytics.

Plans and usage live at Billing. Team management at Workspace Teams. Limits always bill to the workspace owner.

Plan tiers (pricing page)

*Enforced limits come from the database plan row. See full comparison at Pricing.

Usage meters

• Assistant Messages - billed AI replies per month.
• Knowledge Quota - harvest + recrawl + train combined.
• Dispatching Quota - SMS + WhatsApp + email sends.
• Assistants Created - concurrent ready assistants.
• Collaborator Seats - invited non-owner members.
• Workspace Joins - external workspaces you can join.

Feature gates

Invite team members

Administrators: Workspace Teams → enter email → set Permissions → Send Invite.

Permission categories

• Workspace: view conversations, leads, billing, create/manage assistants, phones, notifications.
• Assistant access: all assistants or specific ones.
• Tabs: knowledge, settings, analytics, embed, customize, conversations per member.

Invitee accepts via the notification bell on their dashboard.

Payment issues

Downgrade / cancel

Canceling or downgrading runs scrubToPlanLimits: branding re-enabled, file upload/voice may disable, excess assistants deactivated.

Questions? Open a billing ticket or email [email protected] via Support.

Every assistant generates a unique embed snippet from the Integration tab. Paste it into your site and the widget appears instantly. There are no server-side changes required.

<script>
  window.chirpsConfig = { assistantId: "YOUR_ASSISTANT_ID" };
</script>
<script src="https://chirps.cc/embed.js" async></script>

Replace YOUR_ASSISTANT_ID with the ID from your assistant Integration tab (?tab=integration). The snippet is also pre-filled with your ID on the dashboard, so you can copy it directly.

Platform guides

AI-native dev tools

• Bolt.new
• Lovable
• v0
• Cursor
• VS Code
• Windsurf
• Claude Code
• GitHub Copilot
• Xcode

Domain lock and staging

• The widget loads only on domains matching your authorized domain set in the assistant Settings tab.
• Enable Developer Mode to allow localhost and preview URLs during development.
• Disable Developer Mode before your production launch.

Test before launch

1. Publish your site with the embed snippet.
2. Open the live URL in an incognito window.
3. Ask a pricing question, a product question, and a support question.
4. Submit a test lead form and confirm the contact appears in your Leads dashboard.
5. Turn off Developer Mode if it was enabled.

Looking to connect Chirps to external tools? See Connectors for API integrations, MCP servers, and the connector marketplace.

The widget is a browser client that talks to chirps.cc APIs. You do not need API keys to embed-only your public assistantId.

Load sequence

1. Site loads https://chirps.cc/embed.js with window.chirpsConfig.assistantId.
2. embed.js fetches GET /api/assistants/{id}/widget-config.
3. Domain lock check (403 if origin ≠ authorized domain, unless Developer Mode).
4. Loads widget.js and mounts Shadow DOM chat UI.

Visitor-facing endpoints

Security

• Domain lock - business_url host must match page origin; subdomains allowed.
• Developer Mode - bypasses lock for staging (disable in production).
• Rate limiting - per-visitor message cap (Settings tab, default 30/hour).
• PII masking - optional server-side redaction when enabled.

Dashboard-only APIs

Authenticated session routes (not for embed): assistant CRUD, train, harvest, widget-config PATCH, billing, team invite, notification channels. Managed only from dashboard after login.

Webhooks (server-to-server)

• Stripe → POST /api/billing/webhook
• Twilio → POST /api/twilio/* for voice and SMS
• Your server ← Enterprise Webhook dispatch channel on lead/booking events

Full product docs: Documentation · Privacy · Terms.

Most issues fall into four buckets: embed/domain, knowledge gaps, plan limits, or dispatch config. Still stuck? Contact support or email via Support page.

Widget & embed

Answers & knowledge

Billing & limits

Dispatch & phone

Team & access

Booking & calendar

Chirps ships with a fully integrated CRM out of the box. There is nothing to install or configure. The moment your assistant captures a lead, books an appointment, or qualifies a visitor, that data flows directly into your Leads, Bookings, and Marketing sections inside the dashboard.

Leads

Route: /dashboard/leads

The Leads section is a structured contact database built entirely from conversations. Every time a visitor fills in a lead form on the chat widget, the assistant extracts and stores the following:

• Full name and email address (required by the form schema you define).
• Phone number when provided.
• Source assistant so you know exactly which deployment captured the lead.
• Capture timestamp for accurate time-based filtering.
• Conversation link to jump straight into the exact chat thread that generated the lead.
• Tags and labels set automatically based on assistant logic or manually by your team.

Searching and filtering

• Use the search bar to query by name, email, or phone in real time.
• Filter by date range to view leads from a specific period.
• Filter by source assistant to isolate traffic from individual deployments.
• Sort by newest, oldest, or alphabetically.

Lead actions

• View profile: open the full lead detail sheet with all captured data and the linked conversation.
• Export: download your leads as a CSV file for import into external tools.
• Delete: permanently remove a contact record in compliance with GDPR requests.
• Dispatch: select one or more leads and send them directly to a marketing campaign.

Bookings

Route: /dashboard/bookings

Bookings are appointments your assistant scheduled on your behalf. When a visitor asks to book a call, a demo, or a service appointment, the assistant walks them through a structured booking flow, collects the required details, and logs the confirmed appointment in this section.

What is captured per booking

Managing bookings

• Confirm or cancel a booking directly from the dashboard row or detail sheet.
• Search by contact name or email to find a specific appointment.
• Filter by date to view upcoming appointments for a given week or month.
• Filter by status to quickly action pending requests.
• Export bookings as CSV for use in calendar tools or reporting.

Marketing

Route: /dashboard/marketing

The Marketing section is your campaign control center. It lets you create reusable message templates and dispatch them to leads captured by your assistants, via email, SMS, or WhatsApp.

Templates

Templates are the building blocks of every campaign. Each template consists of:

• Name: an internal reference label for your team.
• Subject: shown in email clients as the message subject line.
• Body: the full message content. You can use plain text or simple HTML for emails.
• Channel: Email, SMS, or WhatsApp.
• Variables: placeholders like {{name}} and {{email}} that are automatically replaced with lead data at send time.

Creating a template

1. Open Marketing and click New Template.
2. Name the template and choose a channel.
3. Write your message body. Use {{name}}, {{email}}, or {{phone}} to personalize.
4. Save the template. It is now available for any campaign.

Campaigns

A campaign ties a template to a set of leads and fires the outreach. To create a campaign:

1. Click New Campaign.
2. Select a template from the dropdown.
3. Add leads manually or import them from the Leads section.
4. Set the campaign name and confirm.
5. Review and click Dispatch. Your AI processes and sends each message.

Dispatch logs

Every campaign maintains a full delivery log so you can audit exactly what was sent:

• Recipient: the lead's name and contact address.
• Status: Sent, Failed, or Pending.
• Channel: how the message was delivered.
• Timestamp: when Chirps processed the send.
• Failure reason: if delivery failed, the error is shown so you can fix and retry.

BYOK dispatch quotas

On Pro and Enterprise plans, you can bring your own API keys (BYOK) for email, SMS, and WhatsApp to remove per-message caps. This is configured under the Dispatch tab of each assistant or globally in Settings.

Connectors are the bridge between your AI assistant and the rest of your business stack. Once connected, your assistant can look up customer records in HubSpot, check availability in Google Calendar, retrieve order data from Stripe, and more, all during a live conversation.

What are Connectors?

A Connector is a preconfigured integration that grants your assistant structured read or write access to an external service. Unlike generic webhooks, Connectors are purpose-built for specific platforms. They handle authentication, schema mapping, and error handling automatically.

Connectors are available in two categories:

• Preset Connectors: ready-to-use integrations with popular tools like HubSpot, Stripe, Google Calendar, Notion, and more. Authorize once and your assistant can use them immediately.
• Custom Connectors: define your own API schema with headers, authentication, and endpoint paths. Useful for internal systems, proprietary databases, or any REST API not yet in the preset library.

The Connector Marketplace

Route: /dashboard/connectors

The Connectors page is your central hub for managing all integrations. It shows every available connector with its status, authorization state, and linked assistants.

Browsing available connectors

• Use the search bar to find a specific service by name.
• Filter by category: CRM, Calendar, Payments, Communication, Database, and more.
• Each connector card shows the service logo, a brief description, and its authorization status (Connected or Not configured).

Connector status indicators

Preset Connectors

Preset Connectors are built and maintained by the Chirps team. They require minimal configuration: typically just an API key or an OAuth login.

Supported preset connectors

Installing a preset connector

1. Open Dashboard and navigate to Connectors.
2. Find the service you want and click Install.
3. Follow the authorization flow. For OAuth services this opens a login popup. For API key services paste your key into the field provided.
4. Click Save. The connector status changes to Connected.
5. Open the assistant you want to use it with, go to the Settings tab, and enable the connector for that assistant.

MCP Connectors

Chirps supports the Model Context Protocol (MCP), an open standard for providing structured, typed tool definitions to AI models. MCP connectors allow your assistant to call external APIs in a structured way, with full type safety, retry logic, and error reporting.

What is MCP?

MCP defines a universal format for describing what an AI tool can do: its name, its input parameters, and its expected outputs. When your assistant calls an MCP tool, it knows exactly what to send and what to expect back. This eliminates prompt ambiguity and makes integrations more reliable.

Installing an MCP connector

1. In the Connectors page, switch to the MCP tab.
2. Click Add MCP Server.
3. Paste in the MCP server URL or upload the server manifest JSON.
4. Configure any required authentication headers or API keys.
5. Click Connect. Chirps validates the server and imports the tool definitions.
6. Assign the MCP server to one or more assistants from the assistant Settings tab.

{
  "name": "my-internal-api",
  "version": "1.0",
  "tools": [
    {
      "name": "get_order",
      "description": "Retrieve an order by ID",
      "inputSchema": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string", "description": "The order ID to look up" }
        },
        "required": ["order_id"]
      }
    }
  ]
}

Custom API Connectors

If the service you need does not have a preset and you do not have an MCP server, you can define a Custom Connector. A Custom Connector is a raw REST endpoint definition that your assistant calls during conversations.

How to create a custom connector

1. In the Connectors page, click New Custom Connector.
2. Give it a name and a short description. The assistant uses this to understand when to call it.
3. Enter the base URL of the API.
4. Define the HTTP method (GET, POST, PUT, etc.).
5. Set any required headers, such as Authorization: Bearer YOUR_API_KEY.
6. Define the request body schema if the endpoint requires a payload.
7. Map the response fields you want the assistant to use.
8. Save and test with a sample request.

Authentication options

Assigning connectors to assistants

Connectors are global to your workspace, but you choose which assistants can use them. This lets you, for example, give your sales assistant access to HubSpot while keeping your support assistant isolated from CRM data.

1. Open the assistant you want to configure.
2. Go to the Settings tab.
3. Scroll to the Connectors section.
4. Toggle on any connectors this assistant should be allowed to call.
5. Save. The assistant can now use those connectors in real conversations.

How the assistant uses connectors during conversations

You do not need to write any prompt instructions for connectors. The assistant automatically learns what each connector can do from its description and schema. When a visitor asks a question that requires external data, the assistant decides in real time which connector to call, fires the request, and incorporates the result into its reply.

Example interaction:

• Visitor: "What is the status of my order #12345?"
• Assistant calls the Shopify connector with { order_id: '12345' }.
• Connector returns order status, items, and tracking number.
• Assistant replies: "Your order #12345 is currently in transit. Expected delivery is Friday, July 18th."

Connector limits by plan

Frequently asked questions

Can I use the same connector across multiple assistants?

Yes. A connector is authorized once at the workspace level and can be assigned to as many assistants as you need.

What happens if a connector API is down?

If the connector returns an error, the assistant falls back to its knowledge base and tells the visitor it could not retrieve real-time data. All errors are logged in the connector error log.

Can I build my own MCP server?

Yes. Any server that implements the MCP specification will work. You host and maintain the server, and Chirps handles routing requests to it from the assistant.