# Chatzyn > Chatzyn connects WhatsApp, Instagram and Facebook Messenger to a shared inbox, with Google Sheets, Shopify, WooCommerce, webhooks and a REST API. Chatzyn is a messaging CRM for sales and support teams. Its shared inbox includes contact history, leads and pipelines, teammate assignment, automation flows and bots that answer from a business's own knowledge library. WhatsApp broadcasts use templates and contact segments. Feature availability and usage limits depend on the workspace plan. See the plans page for the offering on this site. ## Key facts - Chatzyn uses Meta's official APIs only — the WhatsApp Business Platform (Cloud API), the Instagram Platform and Messenger. Unofficial WhatsApp gateways get business numbers banned; Chatzyn is not built on one. - One WhatsApp Business number, many agents: staff sign in with their own email and reply from the business's connected number. Nobody needs a SIM, a second handset or a personal WhatsApp account. - Where Meta makes Coexistence available, the WhatsApp Business app keeps working on the same number after it is connected. - Instagram rules are enforced in the inbox: the 24-hour messaging window, one private reply per comment, and user-initiated conversations only. Optional AI comment moderation flags spam or abuse for a human to decide on. - Inbound media (photos, documents, voice notes) is copied to storage as it arrives, because Meta's media links expire within minutes. - Broadcasts use contact segments and Meta-approved WhatsApp templates with per-person variables, can be scheduled, and report delivery, read and reply per recipient. - Contacts, leads and pipelines are built in; conversations can be auto-assigned round-robin or by team, within per-team business hours. - Automation is a visual flow builder: bot answers from the business's own knowledge library, branches, delays, follow-ups, hand-off to a human, and Google Sheets steps. - Scales from one number and one person to several numbers, teams and unlimited contacts on the same product. ## Features ### Shared team inbox - One inbox for every channel: WhatsApp, Instagram and Facebook Messenger conversations arrive in one live thread list, with the contact's full history beside each chat. - Many agents, one business number: Staff sign in with their own email and reply from the connected business number. Nobody needs a SIM, a second handset or a personal WhatsApp account. - Assignment and chat sharing: New chats go to an agent or to a team such as Sales or Support, round-robin or by rule, so nothing sits unclaimed. - Roles for the whole team: Invite people as owner, admin, agent or viewer. An agent sees the conversations that are theirs, not the whole workspace. - Business hours and reply targets: Say when you are open and how fast you aim to answer; a conversation that passes the target is raised before the customer has to chase it. - Quick replies, labels and notes: Saved answers inserted with a /shortcut, colour-coded labels for sorting, internal notes, and resolve or snooze on every thread. ### Channels - WhatsApp Business Platform: Connect official Cloud API numbers through Meta's own sign-up. Where Meta makes Coexistence available, the WhatsApp Business app keeps working on the same number. - Instagram DMs, comments and stories: Direct messages, comment replies, story replies and story mentions, with Instagram's 24-hour window and its one-private-reply-per-comment rule enforced in the inbox. - Facebook Messenger: Connect a Facebook Page and answer Messenger conversations in the same queue as everything else. - Several numbers, per-number rules: Run more than one number in a workspace, give each its own automations, and restrict who may see or answer which number. - Instagram icebreakers: Set the starter questions a new Instagram chat offers. - Number quality and sending controls: See Meta's quality rating and messaging tier for each number, and pause all promotional sending workspace-wide when you need to. ### Contacts and CRM - Contacts with full history: Everyone who has messaged you, with every conversation across channels kept against them. - Custom fields and labels: Record the details your business actually needs on a contact, and tag them for later. - Import, export and merge: Bring contacts in from CSV, take them out again, and fold duplicates together without losing history. - Segments: Save an audience — by label, field, channel or activity — and reuse it for campaigns and automations. - Leads and pipelines: A queue of the people worth following up, and deal boards that track them from first message to closed. - Analytics: Conversation volume, response times, agent activity and campaign results over time, with export. ### Campaigns and templates - WhatsApp broadcasts: Send an approved template to a segment, now or scheduled, with per-person variables and delivery, read and reply reported per recipient. - Pause, resume and cancel: Stopping a running campaign genuinely stops the queued sends rather than only hiding them. - Template management: Create and track the Meta-approved templates that are the only way to open a conversation outside WhatsApp's 24-hour window, with variable checks before you send. - Opt-outs respected everywhere: A STOP from a customer is honoured on every sending path, and survives a later CSV import. - Tracked links and QR codes: wa.me links and QR codes for print or ads that open a chat, start an automation, and report which entry point brought the customer. ### Automation - Visual flow builder: Build automations by dragging steps, keep a draft while the live version runs, publish when ready and roll back if needed. - Ten ways a flow can start: A keyword, any incoming message, a tracked link, a click-to-WhatsApp ad, an Instagram comment, an Instagram DM keyword, a story reply, a story mention, a manual start, or a schedule. - Ask questions and collect answers: Tappable button questions, multi-field forms and photo requests, with the answers written back onto the contact. - Decide, wait and split: Conditions on what you already know about the contact, delays, and A/B splits to compare two versions. - Act on the conversation: Assign an agent or a team, add or remove tags, update contact fields, set a lead stage, hand over to a person, or resolve the chat. - Reach other systems mid-flow: Call your own webhook or REST endpoint, append a row to Google Sheets, look a record up in a sheet, or send a conversion event back to Meta. - Ready-made flows: Start from a template for the common jobs instead of from an empty canvas. ### AI - A bot that answers from your own material: Upload text, FAQs or a web page; the bot answers from that library rather than from general knowledge, and hands over to a person when it cannot. - A persona per bot: Give each bot its own instructions, tone and the channels it is allowed to answer on. - Voice notes understood and spoken: A customer's voice note is transcribed and answered, and a bot can reply with a spoken voice note of its own. - Help for agents, not instead of them: Draft a reply, summarise a long thread, translate it or change its tone — the agent reads it and decides what to send. - Instagram comment moderation: Spam and abuse under your posts are flagged, with replying and hiding available, so a person decides instead of scrolling. - Lead scoring with the decision left to you: The AI scores a conversation and parks a suggestion an agent accepts in one click. It never converts a lead by itself. - Credits and one master switch: AI usage is metered in credits you can see, and a single workspace switch stops all AI spending at once. ### Integrations and developer tools - REST API: Work with contacts, conversations, messages, templates and media from your own software, using scoped workspace API keys. - Outbound webhooks: Signed message and conversation events delivered to your endpoints, and retried when your server is down. - MCP server for AI assistants: Connect Claude, Cursor or another MCP client to the workspace to triage unassigned conversations, assign an agent, build and publish a flow, create WhatsApp templates and submit them to Meta, or trigger a campaign. - Google Sheets: Sign in with Google once, then write rows or look records up from any automation. - WooCommerce and Shopify: Orders from your store arrive in the workspace, where order events can trigger messages on WhatsApp. The WooCommerce plugin downloads from the dashboard. - Orders, catalog and coupons: A product catalog and an order list in the dashboard, with coupons and their redemptions tracked. - Connected apps and audit log: See which third-party apps hold access, revoke any of them, and read a record of who changed what. ### Online store automation - Order confirmations on WhatsApp: Each new store order gets one confirmation from your approved template, with the order number, total, items or a link back to your shop — never sent twice for the same order. - Cash-on-delivery confirmation: COD orders get Confirm and Cancel buttons instead. A Cancel cancels the order in your WooCommerce shop, which cuts fake and refused COD orders; an order already shipped is never cancelled from a chat. - Abandoned-cart recovery: One reminder per abandoned cart: on WhatsApp to shoppers who ticked consent at checkout, or by email from your own shop for the rest. The link refills their exact cart on any device. - Product reviews from WhatsApp: A few days after an order is completed, ask the customer to rate it. They review inside WhatsApp, and with their consent it appears on your product page as a verified review. - Consent recorded with every opt-in: The checkout consent box is never pre-ticked, and the exact sentence each shopper agreed to is stored with their opt-in. ### For agencies and resellers - A console over every client: One place to see all client workspaces, how they are doing, and what needs attention. - Your own plans and prices: Define the plans you sell, what each one includes and what it costs, in rupees or US dollars. Clients pay you directly, by UPI, bank transfer or your own payment link, and you give them the plan. - Give a client a paid plan: Record a payment a client made to you directly and give them a plan for one, three, six or twelve months; it ends by itself on its end date, with a reminder a week before. - Your product name and branding: Clients see your product name and look rather than ours. - Workspace snapshots: Set a client up from a saved configuration instead of building the same thing again. - Support desk and go-live checklist: Client tickets inside the console, and a pre-launch list so nothing is missed before a number goes live. ## Pages - [Home](https://chatzyn.com/): product overview, team inbox, automation and frequently asked questions. - [Features](https://chatzyn.com/features): the full feature list, by area. - [Integrations](https://chatzyn.com/integrations): supported messaging channels, data tools, online stores and AI providers. - [Plans](https://chatzyn.com/p): current plans offered by the agency serving this site. - [Solutions](https://chatzyn.com/solutions): every use-case and comparison page below, grouped. - [WhatsApp automation](https://chatzyn.com/whatsapp-automation): WhatsApp automation for business on the official API: auto replies, chatbots, order messages, cart reminders, lead capture and broadcasts, and Meta's rules for each. - [WooCommerce WhatsApp](https://chatzyn.com/woocommerce-whatsapp): WooCommerce WhatsApp order notifications from your own number: order confirmations, COD confirm or cancel, abandoned cart recovery and reviews. Official API. - [Cart message templates](https://chatzyn.com/abandoned-cart-whatsapp-templates): Abandoned cart WhatsApp message template examples you can copy, in English, Hindi and Malayalam, plus Meta's rules: marketing category, opt-in and variables. - [WhatsApp shared inbox](https://chatzyn.com/whatsapp-shared-inbox): A WhatsApp shared inbox for multiple numbers: every agent replies from the business number with their own login, with assignment, reply targets and notes. - [WhatsApp Business API](https://chatzyn.com/whatsapp-business-api): What the WhatsApp Business API is, how it differs from the app, how to get it in about ten minutes, and how to keep using the app on the same number. - [WhatsApp chatbot](https://chatzyn.com/whatsapp-chatbot): Build a WhatsApp chatbot for business without code: a visual flow builder for menus, questions and forms, plus an AI bot that answers from your own material. - [Instagram DM automation](https://chatzyn.com/instagram-dm-automation): Instagram DM automation on Meta's official API: auto reply to comments with a private DM, answer DM keywords and story replies, inside Instagram's own rules. - [WhatsApp API pricing](https://chatzyn.com/whatsapp-api-pricing): WhatsApp API pricing in India: Meta's per-message rates for marketing, utility, authentication and service, the free reply allowance, and what Chatzyn adds. - [WhatsApp broadcast limits](https://chatzyn.com/whatsapp-broadcast-limits): WhatsApp broadcast limit per day explained: 256 contacts per list in the app, and API limits of 250 to unlimited people a day, shared per portfolio. - [WhatsApp green tick](https://chatzyn.com/whatsapp-green-tick): WhatsApp green tick verification is now a blue checkmark. See the two ways to get it, Official Business Account and Meta Verified, who qualifies and the cost. - [Wati alternatives](https://chatzyn.com/wati-alternative): Five Wati alternatives in India compared: Chatzyn, AiSensy, Interakt, the free WhatsApp Business app and Meta's own Cloud API, with prices and who each suits. - [AiSensy alternative](https://chatzyn.com/aisensy-alternative): Looking for an AiSensy alternative? Compare plan prices, add-ons, number limits, Instagram, Messenger, WooCommerce and white label options with Chatzyn. - [Interakt alternatives](https://chatzyn.com/interakt-alternative): Comparing Interakt alternatives in India? See plan prices, message rates, number limits, Instagram, Messenger, WooCommerce and white label next to Chatzyn. - [White label WhatsApp](https://chatzyn.com/white-label-whatsapp): A white label WhatsApp CRM for agencies: run every client from one console, under your own brand, on your own plans and prices, with Meta's official API. - [WhatsApp CRM](https://chatzyn.com/whatsapp-crm): WhatsApp CRM software that keeps every customer chat, label and custom field in one place, with a team inbox, leads, deal boards and AI help. Official API. - [WhatsApp marketing software](https://chatzyn.com/whatsapp-marketing-software): WhatsApp marketing software for Indian businesses: approved templates to opted-in segments, pause or cancel any time, tracked links, official API only. - [WhatsApp Business multiple users](https://chatzyn.com/whatsapp-business-multiple-users): WhatsApp Business multiple users: the app allows one phone plus 4 linked devices. A shared inbox gives every agent their own login on the same business number. - [Messenger automation](https://chatzyn.com/facebook-messenger-automation): Facebook Messenger automation in Chatzyn today: Page messages in a shared team inbox, auto-assignment to agents, and Meta's 24-hour and human agent rules. - [Click to WhatsApp ads](https://chatzyn.com/click-to-whatsapp-ads): Run Click to WhatsApp ads that start an automatic reply flow and show which ad brought each chat, plus tracked wa.me links and QR codes for your business. - [WhatsApp + Google Sheets](https://chatzyn.com/whatsapp-google-sheets): WhatsApp Google Sheets integration: save chat answers as a new row in your sheet, or look up an order or phone number and use it in the reply. Official API. - [WhatsApp MCP server](https://chatzyn.com/whatsapp-mcp-server): A WhatsApp MCP server for Claude, Cursor and other AI assistants, plus a REST API and signed webhooks, all on Meta's official WhatsApp Business Platform. - [Real estate](https://chatzyn.com/whatsapp-crm-real-estate): WhatsApp CRM for real estate: property enquiries from ads and listings in one inbox, budget and BHK questions, lead pipelines and site visit follow-ups. - [WhatsApp for clinics](https://chatzyn.com/whatsapp-automation-clinics): WhatsApp automation for clinics on Meta's official API: answer appointment enquiries, run an FAQ bot from your own material and send reminder templates. - [Restaurants](https://chatzyn.com/whatsapp-automation-restaurants): WhatsApp automation for restaurants: take table booking enquiries with an in-chat form, send your menu, and share offers with opted-in customers. Official API. - [Privacy policy](https://chatzyn.com/privacy): how personal data is handled. - [Terms of service](https://chatzyn.com/terms): terms for using the service. - [Data deletion](https://chatzyn.com/data-deletion): how to request deletion of personal data. ## Common questions ### What is Chatzyn? Chatzyn is a customer-messaging CRM for WhatsApp, Instagram and Facebook Messenger. It combines a shared team inbox with contacts, leads, pipelines, visual automation and WhatsApp broadcasts. ### What does it cost? The plans and what each one includes are on the pricing page. WhatsApp message charges are separate: Meta bills them per message, at Meta's own rates. ### Which WhatsApp numbers can I connect? Connect an eligible WhatsApp Business number through Meta's official WhatsApp Business Platform. Where Meta makes coexistence available, you can keep using the WhatsApp Business app on the same number. A personal WhatsApp account cannot be connected directly. ### What do I need from Meta to connect? For WhatsApp, sign in with the Facebook account that runs your business; it needs a Meta business portfolio, which is free to create. Keep the phone with the number nearby, because Meta checks it with a code or a QR scan. A number in the WhatsApp Business app can stay there with coexistence; a new number must be able to receive an SMS or a call and must not be on any WhatsApp app; a number on personal WhatsApp has to move to the WhatsApp Business app first. For Instagram you need a professional (Business or Creator) account with access to messages turned on, and for Messenger, admin access to the Facebook Page. ### Does it use the official WhatsApp API? Yes. Chatzyn connects through Meta's official WhatsApp Cloud API, Instagram Platform and Messenger APIs, never an unofficial WhatsApp gateway — the kind that gets business numbers banned. Your connected accounts and messages remain subject to Meta's eligibility requirements and messaging policies. ### Can my whole team answer conversations together? Yes. Invite staff with roles, assign conversations to people, and set business hours per team. Automatic assignment and round-robin routing help distribute conversations across your team, with a named assignee for each assigned conversation. ### Do my staff need their own SIM or WhatsApp number? No. Each teammate signs in to Chatzyn with their own email in the browser or the Android app and replies from the business's connected number. Staff do not need a separate SIM, handset or personal WhatsApp account to use the shared inbox. ### Does the shared inbox support Instagram and Messenger? Yes. Connect an Instagram professional account for DMs and comment moderation, or a Facebook Page for Messenger conversations. These channels appear alongside WhatsApp in the shared inbox. Reply windows and permissions depend on the channel and Meta's rules. ### What happens to photos and documents customers send? Inbound media is copied to storage so your team can view it in the conversation history after the original provider link expires. This depends on successful retrieval of the media; deleted media is no longer available in the conversation. ### Can I automate replies without writing code? Yes. Build visual flows to answer common questions from your knowledge library, branch on answers, wait, follow up, or hand conversations to a teammate. Google Sheets steps can write rows or look up data. Automated messages still follow the connected channel's messaging rules. ### Can I connect Google Sheets or my own software? Yes. Connect Google Sheets in settings for flow steps that write rows or look up data. Use API keys to call the REST API from your own software, and signed webhooks to receive events for messages and conversations. ## Integrations ### Messaging platforms - WhatsApp: Connect the official WhatsApp Business Platform (Cloud API) to your team inbox. Eligible numbers can use Coexistence to keep the WhatsApp Business app on the same number. - Instagram: Connect an Instagram professional account for DMs, comments and moderation through Meta's official APIs. Reply windows and private-reply limits are enforced in the inbox. - Facebook Messenger: Connect a Facebook Page to manage Messenger conversations alongside WhatsApp and Instagram in the shared inbox. ### Data and tools - Google Sheets: Connect your Google account in workspace settings, then use automation steps to write rows or look up existing records in a spreadsheet. - Webhooks: Send signed message and conversation events to your own endpoints, or call an external endpoint from an automation flow. - REST API: On plans with API access, create a workspace API key to work with contacts, conversations, messages and templates from your own software. ### Online stores - WooCommerce: Connect your store with its REST API credentials to import orders, customer details, line items and statuses into the order board. - Shopify: Connect your shop with a Shopify Admin API access token that can read orders, then sync orders into the same workspace as your customer conversations. ### AI providers and models - Groq: Runs supported Llama models for bots that answer using your business's knowledge library. - OpenRouter: Provides additional model choices and provider failover when an alternative provider is configured for the selected model. - Model choices: The bot settings offer Llama 3.3 70B, Llama 3.1 8B and Mistral Small 3. Availability depends on the configured AI providers. ## Common integration questions ### Which messaging channels does Chatzyn support? Chatzyn supports the WhatsApp Business Platform, Instagram professional accounts and Facebook Page Messenger through Meta's official APIs. Your team manages connected channels in one shared inbox. ### Can I send leads or order details to Google Sheets? Yes. Connect your Google account under Settings → Integrations, then add a Google Sheets step to a flow to write a row or look up an existing record. ### Can I connect my Shopify or WooCommerce store? Yes. Connect your store under Settings → Integrations with credentials that can read orders, then sync orders into the workspace order board. Customer details, line items and order statuses are imported from the store. ### How do I connect software without a built-in integration? Use a workspace API key for the REST API on plans with API access, subscribe an endpoint to signed webhook events, or add a Call a webhook step to an automation flow. These options require your own software or an endpoint to receive the data. ## Developers - [Developers](https://chatzyn.com/developers): the MCP server and the REST API, in one place. - [Chatzyn in the Claude Connectors Directory](https://claude.ai/directory/chatzyn): the official Claude connector, one-click connect. - [MCP server](https://chatzyn.com/developers/mcp): connect Claude, Claude Code, Cursor or any MCP client; every tool, scope and token lifetime. - [REST API v1](https://chatzyn.com/developers/api): authentication, scopes, errors, endpoints and signed webhooks. - [llms-full.txt](https://chatzyn.com/llms-full.txt): this file plus all of the developer docs, in plain text. ## Platform operator and official profiles Chatzyn is operated by PROXCELERATE LLP. - [Android app](https://play.google.com/store/apps/details?id=com.chatzyn.app) - [Facebook](https://www.facebook.com/chatzynapp) - [Instagram](https://www.instagram.com/chatzyn.app) # Chatzyn for developers Chatzyn has two ways in for developers and AI assistants. Both work on one workspace at a time, and both need a plan with API access (Growth and Pro). - [MCP server](https://chatzyn.com/developers/mcp): connect Claude, Claude Code, ChatGPT, VS Code, Cursor, Gemini or any MCP client, so an assistant can read and act on your inbox, templates, flows, broadcasts and store automations. - [REST API v1](https://chatzyn.com/developers/api): plain HTTPS endpoints for contacts, conversations, messages, one-time passcodes, templates and the wallet, plus signed outbound webhooks. - [llms-full.txt](https://chatzyn.com/llms-full.txt): all of these docs in one plain text file, for AI agents. Keys and connected apps are managed in your workspace under **Settings > API & MCP**. # Chatzyn MCP server ## At a glance - **Endpoint:** `https://chatzyn.com/api/mcp` - **Transport:** Streamable HTTP. One JSON-RPC message per request; batches are refused. - **Sign in:** with OAuth (your app opens a Chatzyn sign-in and asks you to approve), or with an API key sent as `Authorization: Bearer czk_…`. OAuth apps identify themselves (Client ID Metadata Documents) or register on their own (dynamic client registration), so there is usually no Client ID to paste. - **Plans:** API access is on Growth and Pro. - **Limits:** every tool call counts as one call against your plan's monthly API allowance, and each key is rate limited. ## Connect Claude (claude.ai or Claude Desktop) Chatzyn is in the official Claude Connectors Directory: [open Chatzyn in Claude](https://claude.ai/directory/chatzyn) and press **Connect**. Claude opens the Chatzyn sign-in. Sign in, pick the workspace, check the permissions it asks for, and press **Allow**. Or add it by hand as a custom connector: 1. In Claude, open **Customize > Connectors**, press **+ Add**, then choose **Add custom connector**. 2. Name it Chatzyn and paste `https://chatzyn.com/api/mcp` as the URL. 3. Press **Connect**, sign in and press **Allow**. On a Claude Team or Enterprise plan, an organization Owner adds the connector first, under **Organization settings > Connectors > Add > Custom > Web**. Members then connect it from **Customize > Connectors**. If Claude asks for an OAuth Client ID, enter `https://claude.ai/api/mcp/auth_callback` and leave the Client Secret empty. The connection works as you. It can never do more than your own role allows in that workspace, and an owner connects as admin. ## Connect Claude Code Sign in with OAuth (run `/mcp` in Claude Code afterwards to sign in): ``` claude mcp add --transport http chatzyn https://chatzyn.com/api/mcp ``` Or use an API key instead: ``` claude mcp add --transport http chatzyn https://chatzyn.com/api/mcp --header "Authorization: Bearer czk_…" ``` ## Connect ChatGPT In a work workspace, your admin may need to allow custom plugins first. 1. In ChatGPT on the web, open `chatgpt.com/plugins`, press **+** and choose **Add custom MCP server**. 2. Name it Chatzyn and paste `https://chatzyn.com/api/mcp` as the server URL. 3. Under **Connection**, set authentication to **OAuth** and leave Client ID and Client Secret empty. ChatGPT identifies itself on its own. 4. Confirm the warning, press **Create as a plugin** and install it, then sign in to Chatzyn and press **Allow** when it asks. Type **@** in a chat to use it. ChatGPT asks you before it runs any tool that changes something. It has no API key option, so OAuth is the only way in. ## Connect the OpenAI API (Responses API) Pass an API key in the MCP tool's `authorization` field, without the word Bearer. OpenAI does not store it, so send it with every request: ``` { "type": "mcp", "server_label": "chatzyn", "server_url": "https://chatzyn.com/api/mcp", "authorization": "czk_…", "require_approval": "always" } ``` ## Connect VS Code (GitHub Copilot agent mode) Run **MCP: Add Server** from the Command Palette, choose **HTTP**, paste `https://chatzyn.com/api/mcp` and give it an ID. VS Code opens the Chatzyn sign-in the first time it starts the server. Or in `mcp.json`: ``` { "servers": { "chatzyn": { "type": "http", "url": "https://chatzyn.com/api/mcp" } } } ``` To use an API key instead, VS Code can prompt for it and keep it secret: ``` { "inputs": [ { "type": "promptString", "id": "chatzyn-key", "description": "Chatzyn API key (czk_…)", "password": true } ], "servers": { "chatzyn": { "type": "http", "url": "https://chatzyn.com/api/mcp", "headers": { "Authorization": "Bearer ${input:chatzyn-key}" } } } } ``` ## Connect Cursor Open the **Customize** page, or edit `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project). With just the URL, Cursor registers itself and opens the Chatzyn sign-in: ``` { "mcpServers": { "chatzyn": { "url": "https://chatzyn.com/api/mcp" } } } ``` One-click install link (it holds no key), to open in your browser: ``` cursor://anysphere.cursor-deeplink/mcp/install?name=chatzyn&config=eyJ1cmwiOiJodHRwczovL2NoYXR6eW4uY29tL2FwaS9tY3AifQ%3D%3D ``` To use an API key instead, add `"headers": { "Authorization": "Bearer czk_…" }` next to the URL. ## Connect Windsurf / Devin Desktop Add a custom server in `~/.config/devin/mcp_config.json` (or `.devin/mcp_config.json` in a project). With just the URL it uses OAuth: sign in when prompted, or run `devin mcp login chatzyn` in the CLI. For an API key, add the header: ``` { "mcpServers": { "chatzyn": { "url": "https://chatzyn.com/api/mcp", "headers": { "Authorization": "Bearer czk_…" } } } } ``` ## Connect Gemini CLI ``` gemini mcp add --transport http chatzyn https://chatzyn.com/api/mcp ``` Then run `/mcp auth chatzyn` in Gemini CLI to sign in with your browser. OAuth needs a browser on the same machine; over SSH or in a container, use an API key: ``` gemini mcp add --transport http --header "Authorization: Bearer czk_…" chatzyn https://chatzyn.com/api/mcp ``` ## Connect the Gemini app Google limits custom apps in Gemini (gemini.google.com) to some accounts: personal Google Accounts in the US, and guides report a Google AI Pro or Ultra plan is needed too. If you do not see **Add a custom app**, your account is not eligible yet. On a computer, open **Settings & help > Connected Apps**, press **Add a custom app** under **Custom apps**, paste `https://chatzyn.com/api/mcp`, press **Next** and sign in to Chatzyn. If Gemini asks for credentials under **Advanced features**, leave them empty. ## Connect Microsoft Copilot Studio Use an API key. In your agent open **Tools > Add a tool > New tool > Model Context Protocol**, name it Chatzyn, paste `https://chatzyn.com/api/mcp`, and set **Authentication** to **API key**, type **Header**, header name `Authorization`. When it asks for the key, paste the whole value including the word Bearer: `Bearer czk_…`. ## Connect Zed **Settings > AI > MCP Servers > Add Server > Add Remote Server** and paste `https://chatzyn.com/api/mcp`. With no Authorization header set, Zed starts the Chatzyn sign-in on its own. Or in `settings.json`: ``` { "context_servers": { "chatzyn": { "url": "https://chatzyn.com/api/mcp" } } } ``` For an API key, add `"headers": { "Authorization": "Bearer czk_…" }`. ## Connect Cline In `cline_mcp_settings.json`. Set `type`, or Cline falls back to the old SSE transport. Leave out `headers` to sign in with OAuth instead: ``` { "mcpServers": { "chatzyn": { "type": "streamableHttp", "url": "https://chatzyn.com/api/mcp", "headers": { "Authorization": "Bearer czk_…" }, "disabled": false, "autoApprove": [] } } } ``` ## Connect Goose **Extensions > Add custom extension**, type **Streamable HTTP**, endpoint `https://chatzyn.com/api/mcp`. Goose opens the Chatzyn sign-in. For an API key, add the Authorization header under `headers`. ## Connect Perplexity Custom connectors need a paid Perplexity plan. Open **Settings > Connectors** and add a custom remote MCP connector (if your app shows **Plugins > Add custom**, use that), name it Chatzyn, paste `https://chatzyn.com/api/mcp`, transport **Streamable HTTP**, authentication **OAuth**. In an Enterprise organization an admin adds it under **Organization settings > Connectors** and turns it on for members. ## Connect Mistral Le Chat **Connectors > + Add Connector > Custom MCP Connector**. Name it `chatzyn`, paste `https://chatzyn.com/api/mcp` and press **Connect**. Choose OAuth, or **Bearer token** and paste a `czk_…` key. Only admins can add connectors; on a personal plan you are the admin. ## Connect Raycast Run **Install MCP Server**, transport **HTTP**, URL `https://chatzyn.com/api/mcp`. Choose OAuth type **Dynamic**. If your version offers HTTP headers, you can instead leave OAuth off and add `Authorization` with the value `Bearer czk_…`. ## Connect Manus **Settings > Connectors > + Add connectors > Custom MCP > Direct configuration**, transport **HTTP**, URL `https://chatzyn.com/api/mcp`, and a custom header `Authorization` with the value `Bearer czk_…`. ## Connect LM Studio Use an API key. In **Program > Install > Edit mcp.json**: ``` { "mcpServers": { "chatzyn": { "url": "https://chatzyn.com/api/mcp", "headers": { "Authorization": "Bearer czk_…" } } } } ``` ## Connect n8n or Zapier - **n8n:** add an **MCP Client Tool** to an AI Agent, endpoint `https://chatzyn.com/api/mcp`, transport **HTTP Streamable**, authentication **Bearer Auth** with a `czk_…` key. - **Zapier:** **Apps > + Add connection > MCP Client**, server URL `https://chatzyn.com/api/mcp`, transport **Streamable HTTP**, OAuth **No**, and the `czk_…` key as the bearer token. ## Connect from your own code (Google ADK and other SDKs) Any MCP SDK that takes a URL and headers works with an API key. Python, Google ADK: ``` McpToolset(connection_params=StreamableHTTPConnectionParams(url="https://chatzyn.com/api/mcp", headers={"Authorization": "Bearer czk_…"})) ``` Keep the key in an environment variable or a secret store, never in the code. ## Any other MCP client Add `https://chatzyn.com/api/mcp` as a remote (Streamable HTTP) MCP server. If it supports OAuth, it finds the Chatzyn sign-in on its own. If it asks for a header, send `Authorization` with the value `Bearer czk_…`. Not supported yet: Microsoft 365 Copilot declarative agents and Gemini Enterprise custom MCP data stores. Both need an OAuth client with a client secret, which Chatzyn does not issue. To make a key, open **Settings > API & MCP**, press **Create a key** and pick the **MCP key** preset: an admin key with exactly the scopes the tools need. The key is shown once, so copy it then. ## Tools | Tool | What it does | Reads or changes | Scopes | Key role | Arguments | | --- | --- | --- | --- | --- | --- | | `chatzyn_list_unassigned_conversations` | List unassigned conversations | Reads | `conversations:read` | admin or higher | `channelId?`, `olderThanMinutes?`, `order?`, `limit?`, `cursor?` | | `chatzyn_assign_agent` | Assign a conversation | Changes | `conversations:assign` | agent or higher | `conversationId`, `agent`, `note?` | | `chatzyn_create_or_update_flow` | Create or update a flow draft | Changes | `flows:write` | admin or higher | `flowId?`, `name?`, `draftGraph`, `triggerRules?` | | `chatzyn_publish_flow` | Publish a flow | Changes | `flows:publish` | admin or higher | `flowId`, `confirm` | | `chatzyn_trigger_broadcast_or_template` | Preflight or launch a broadcast | Changes | `broadcasts:send` + `messages:send` (launch only) | admin or higher | `idempotencyKey`, `mode?`, `expectedRecipients?`, `campaign` | | `chatzyn_list_templates` | List WhatsApp templates | Reads | `templates:read` | any | `status?` | | `chatzyn_create_template` | Create a WhatsApp template | Changes | `templates:write` | admin or higher | `whatsappAccountId?`, `name`, `language`, `category`, `headerText?`, `headerSample?`, `body?`, `bodySamples?`, `footer?`, `quickReplies?`, `urlButtons?`, `phoneButton?`, `otp?`, `confirm` | | `chatzyn_get_store_automations` | Read store automations | Reads | `store:read` | any | none | | `chatzyn_update_store_automation` | Change a store automation | Changes | `store:write` | admin or higher | `kind`, `enabled`, `channelId`, `templateId`, `variables?`, `storeName?`, `delayDays?`, `delayMinutes?`, `confirm` | | `chatzyn_search` | Search workspace records | Reads | `contacts:read`, `conversations:read`, `flows:read`, `broadcasts:read`, `store:read` (the scope for the type searched) | any (flows, broadcasts: admin; orders: agent) | `type`, `query?`, `filters?`, `limit?`, `cursor?` | | `chatzyn_get_record` | Read one record | Reads | `contacts:read`, `conversations:read`, `flows:read`, `broadcasts:read`, `store:read` (the scope for the type read) | any (flow, broadcast: admin; order: agent) | `type`, `id` | | `chatzyn_get_conversation_messages` | Read a conversation's messages | Reads | `conversations:read` | any | `conversationId`, `limit?`, `before?` | | `chatzyn_get_analytics` | Read workspace analytics | Reads | `analytics:read` | admin or higher | `days?`, `channelId?` | | `chatzyn_get_workspace_status` | Read workspace status | Reads | `conversations:read` | any | none | | `chatzyn_list_workspace_catalog` | List workspace tags, fields, people and replies | Reads | `contacts:read` | any (teams, segments: admin) | `kind` | `chatzyn_publish_flow`, `chatzyn_create_template`, `chatzyn_update_store_automation` only act with `confirm: true`, and `chatzyn_trigger_broadcast_or_template` only launches after a clean preflight of the same campaign, so your assistant has to show you the details first. Other changes, such as assigning a chat or saving a flow draft, happen as soon as the tool is called. ## Scopes A key, or a connected app, can only use the scopes it was given, and only those its role allows. | Scope | Grants | Lowest key role | Used by | | --- | --- | --- | --- | | `contacts:read` | Read contacts and their tags. | viewer | REST and MCP | | `contacts:write` | Create, update and delete contacts. | agent | REST only | | `conversations:read` | Read conversations and their message history. | viewer | REST and MCP | | `messages:send` | Send messages, including uploading the media they carry (all send guards still apply). | agent | REST and MCP | | `templates:read` | List approved message templates. | viewer | REST and MCP | | `flows:read` | Read flow definitions and their publish state. | viewer | MCP only | | `flows:write` | Create flows and save their draft graph. Does not publish. | admin | MCP only | | `flows:publish` | Publish a flow, making it live. | admin | MCP only | | `conversations:assign` | Assign or unassign conversations to workspace members. | agent | MCP only | | `broadcasts:send` | Preflight and launch WhatsApp broadcast campaigns (all send guards still apply). | admin | MCP only | | `templates:write` | Create WhatsApp message templates and submit them to Meta for review. | admin | MCP only | | `store:read` | Read store automation settings, abandoned-cart figures and recent store orders. | viewer | MCP only | | `store:write` | Switch store automations on or off and change their template (order and COD confirmation, review requests, cart recovery). | admin | MCP only | | `templates:send` | Send one-time passcodes to any WhatsApp number with an approved authentication template (all send guards still apply). | agent | REST only | | `analytics:read` | Read workspace analytics: conversation, message, lead and order figures, agent performance and campaign results. | admin | MCP only | | `broadcasts:read` | Read broadcast campaigns, their delivery figures and a sample of recipients. | admin | MCP only | ## Key roles | Role | What it can do | | --- | --- | | viewer | Read only. Sees only the chats given to the person who made the key. | | agent | Can reply to and assign the chats given to the person who made the key, and add or edit contacts. | | admin | Sees every chat, and can also publish flows and send campaigns. | ## How long access lasts - A connected app gets an access token that lasts **1 hour** and is renewed on its own with a refresh token that lasts **30 days**. - However often it renews, a connection ends **90 days** after you approved it. Then you connect again. - The sign-in code that comes back to Claude works once, for **1 minute**. - An API key does not expire. It works until you revoke it. ## Disconnect or revoke - **Connected apps:** a workspace admin opens **Settings > API & MCP > Connected apps** and presses **Disconnect**. It stops working straight away. If you are not an admin, ask one to do it. - **API keys:** a workspace admin opens **Settings > API & MCP** and presses **Revoke** on the key. It stops working straight away. - Removing the connector inside Claude stops Claude using it. To cancel the access on our side too, an admin disconnects it here. ## Your data - A key or connection belongs to one workspace and can never reach another. - An admin connection sees every chat. An agent or viewer connection sees only the chats given to the person who connected it, the same rule the inbox uses. - Tools return only the workspace data the tool is for. They never return passwords, API keys, Meta access tokens or card details. - Anything that sends to customers still follows every send rule: the 24-hour window, opt-outs, blocked contacts, approved templates and your number's health. - Every tool call that runs is recorded in the workspace audit log: which tool, who, which key or connected app, and whether it worked. - What a tool returns goes to your own AI app, at your request. That app's own terms cover what it does with it. # Chatzyn REST API v1 Base URL: `https://chatzyn.com/api/v1` Everything here is scoped to one workspace by the key. There is no workspace parameter, and no way for a key to name a different workspace. Rate limit: 120 requests a minute per key. ## Authentication ``` Authorization: Bearer czk_a1b2c3d4_<64 hex chars> ``` * Keys are created in **Settings → API & MCP** and shown **exactly once**. Only a hash of the key is stored, so we cannot recover a lost key, only revoke it and issue another. * `?api_key=` is **not** accepted. Query strings end up in access logs, browser history and `Referer` headers. * Revocation is immediate; there is no cache to wait out. * Only keys made in **Settings → API & MCP** (`czk_…`) work here. A token a connected app received through the consent screen (`czo_…`) is for the MCP endpoint only and gets `403 forbidden` ("OAuth tokens are only valid at /api/mcp") on every v1 route. Requires the `api_access` entitlement (Growth and Pro plans). --- ## Scopes Enforced server-side on every request, read from the key row — never from anything the caller sends. There is no "all scopes" value. | Scope | Grants | Lowest key role | Used by | | --- | --- | --- | --- | | `contacts:read` | Read contacts and their tags. | viewer | REST and MCP | | `contacts:write` | Create, update and delete contacts. | agent | REST only | | `conversations:read` | Read conversations and their message history. | viewer | REST and MCP | | `messages:send` | Send messages, including uploading the media they carry (all send guards still apply). | agent | REST and MCP | | `templates:read` | List approved message templates. | viewer | REST and MCP | | `flows:read` | Read flow definitions and their publish state. | viewer | MCP only | | `flows:write` | Create flows and save their draft graph. Does not publish. | admin | MCP only | | `flows:publish` | Publish a flow, making it live. | admin | MCP only | | `conversations:assign` | Assign or unassign conversations to workspace members. | agent | MCP only | | `broadcasts:send` | Preflight and launch WhatsApp broadcast campaigns (all send guards still apply). | admin | MCP only | | `templates:write` | Create WhatsApp message templates and submit them to Meta for review. | admin | MCP only | | `store:read` | Read store automation settings, abandoned-cart figures and recent store orders. | viewer | MCP only | | `store:write` | Switch store automations on or off and change their template (order and COD confirmation, review requests, cart recovery). | admin | MCP only | | `templates:send` | Send one-time passcodes to any WhatsApp number with an approved authentication template (all send guards still apply). | agent | REST only | | `analytics:read` | Read workspace analytics: conversation, message, lead and order figures, agent performance and campaign results. | admin | MCP only | | `broadcasts:read` | Read broadcast campaigns, their delivery figures and a sample of recipients. | admin | MCP only | A request with a valid key but the wrong scope gets `403 insufficient_scope` and lists what was required. ### Roles Every key has a role — `viewer`, `agent` or `admin` — chosen when it is made, and it is enforced here exactly as in the dashboard: * **A scope needs a role.** A key whose role is below the one in the table gets `403 insufficient_role`, even though it holds the scope. Settings refuses to make such a key in the first place. * **Which chats a key sees follows its role.** An **admin** key sees every conversation in the workspace. An **agent** or **viewer** key acts for the person who made it and sees only the conversations given to that person, on the numbers they may work — the inbox's own rule. Everything else answers `404`, the same as an id that does not exist. This applies to `GET /conversations`, `GET /conversations/{id}/messages` and `POST /messages`. Need every chat? Use an admin key. Keys made before roles existed run as `agent`. **When the person who made a key leaves the workspace**, the key keeps its role. An admin key carries on as before. An agent or viewer key still acts for that person, and nobody can give chats to someone who has left: their open chats go back to Unassigned, so from then on the key lists only their old resolved chats and answers `404` for every live one. Contacts and templates are not affected. Replace such a key with an admin key before removing its maker. --- ## Rate limits `120 requests / minute / key`, fixed window. Every response carries: ``` X-RateLimit-Limit: 120 X-RateLimit-Remaining: 118 X-RateLimit-Reset: 34 # seconds until the window rolls X-Request-Id: ``` Over the limit → `429 rate_limited` with `Retry-After`. Separately, every call consumes one unit of the plan's `api_calls_month` entitlement. Exhausting it returns `402 payment_required` — the per-minute limiter protects the platform, the monthly meter is the commercial limit. Need more headroom for one integration? Issue it its own key: the limiter is per key, so a runaway script cannot starve your other integrations. --- ## Errors Every non-2xx response has this exact shape — parse one, parse them all. A 500 never leaks a stack trace or a database message. ```json { "error": { "code": "insufficient_scope", "message": "This key is missing the \"messages:send\" scope.", "details": { "required": "messages:send", "granted": "contacts:read" }, "requestId": "0f3c…" } } ``` | `code` | HTTP | Meaning | | --- | --- | --- | | `unauthorized` | 401 | Missing, malformed, unknown or revoked key | | `forbidden` | 403 | Workspace suspended, or a `czo_` connected-app token (MCP only) | | `insufficient_scope` | 403 | Key lacks the scope this endpoint needs | | `insufficient_role` | 403 | Key holds the scope, but its role may not use it | | `invalid_request` | 400 | Bad body, bad parameter, bad cursor | | `not_found` | 404 | No such row **in this workspace** | | `conflict` | 409 | Duplicate contact, closed window, disconnected channel | | `rate_limited` | 429 | Per-key limit exceeded | | `payment_required` | 402 | No active subscription / `api_access` off / monthly allowance used | | `unavailable` | 503 | Stored but not queued — safe to retry | | `internal` | 500 | Our fault. Quote `requestId` to support | **Timeouts.** During a brief service interruption (a few seconds), a send (`POST /messages`, `POST /messages/template`) waits for it rather than failing, so it can take up to about 8 seconds, and about 16 in the worst case. Give these calls a client timeout of at least **20 seconds**: a shorter one can give up on a request that still sends, and a retry then sends twice. --- ## Pagination Collections return: ```json { "data": [ … ], "nextCursor": "MjAyNi0wOC0wNFQxMDoxMjozM1o…" } ``` Pass it back as `?cursor=…`. `nextCursor: null` means you have everything. Cursors point at a position in a fixed order, not a page number, so new rows arriving while you page never make you skip or repeat one. `?limit=` is clamped to 100. --- ## Endpoints ### `GET /contacts` — `contacts:read` Query: `limit`, `cursor`, `search` (name/email/phone substring), `phone` (normalised before matching, so `+91 98…` and `9198…` find the same person). Soft-deleted and merged-away contacts are never returned. ```json { "data": [{ "id": "…", "name": "Priya", "phone": "919876543210", "email": null, "locale": "ml", "attributes": {}, "tags": ["vip"], "isBlocked": false, "lastSeenAt": "2026-08-01T09:12:00.000Z", "createdAt": "…", "updatedAt": "…" }], "nextCursor": null } ``` ### `POST /contacts` — `contacts:write` ```json { "name": "Priya", "phone": "+91 98765 43210", "email": null, "locale": "ml", "attributes": { "city": "Kochi" } } ``` At least one of `phone` / `email`. Phone numbers are stored as **bare digits, no `+`** (what WhatsApp ingest writes) — send whatever format you have, we normalise. An existing contact on that number returns `409 conflict` with its id in `details.contactId` rather than creating a duplicate. `201` with the created contact. ### `GET /contacts/{id}` — `contacts:read` ### `PATCH /contacts/{id}` — `contacts:write` PATCH is a true patch: an **absent** key leaves the field alone, an explicit `null` clears it. Send `{"name": null}` to clear a name; send `{}` and you get `400`. ### `DELETE /contacts/{id}` — `contacts:write`, admin key Deleting a contact is admin-only in the dashboard, so it needs an **admin** key here; an agent key gets `403 insufficient_role`. A **soft** delete: the contact disappears from the API and the dashboard, but conversations, messages and the audit trail survive. Hard erasure is a separate, deliberate GDPR job — not something a loop in an integration can trigger. ### `GET /conversations` — `conversations:read` Query: `limit`, `cursor`, `status` (`open|resolved|snoozed`), `contactId`. An admin key lists every conversation; an agent or viewer key lists only the ones given to the person who made it (see **Roles**). Ordered by `createdAt` **descending**, not by last activity, so rows do not jump between pages every time a customer replies. `windowExpiresAt` is the important field — past it, free-form sending is refused and you need an approved template. ### `GET /conversations/{id}/messages` — `conversations:read` Newest first. Query: `limit`, `cursor`. ### `POST /media` — `messages:send` Put a file where a send can name it. The body is the **raw file**, not multipart and not base64: ``` POST /api/v1/media?purpose=voice_note Authorization: Bearer czk_… Content-Type: audio/ogg Content-Length: 41233 x-file-name: note.ogg ``` `purpose` is `message` (default) or `voice_note`. Returns **`201`**: ```json { "id": "a17d…", "kind": "audio", "mimeType": "audio/ogg", "sizeBytes": 41233, "fileName": "note.ogg", "durationSeconds": 7, "voiceNote": true } ``` `mimeType` is what we **sniffed from the bytes**, not what you declared — upload WebM/Opus and it comes back `audio/ogg`, because it was remuxed. Caps are Meta's: image 5 MB, audio and video 16 MB, document 100 MB. **Voice-note intent is declared at UPLOAD time, and it has to be.** `audio/ogg` is a container, not a codec: WhatsApp shows the push-to-talk bubble only when the send carries `voice: true`, and Meta rejects that flag on anything that is not Opus — a rejection that counts against your number's quality rating. `?purpose=voice_note` is the only path that proves Opus, by remuxing WebM/Opus, re-encoding MP4/AAC, or asserting the codec on an Ogg you supply. **Send Ogg/Opus and it always works.** `image/webp` is refused. WhatsApp treats WebP as a sticker, a MIME type alone cannot say which you meant, and silently turning a customer's photo into a sticker reads as a bug. Send JPEG or PNG. There is **no `DELETE`**. API-uploaded files appear on Settings → Storage with a blank uploader and can be removed there. Nothing sweeps files you upload and never send, and they count against the workspace's storage. ### `POST /messages` — `messages:send` Exactly one of `text` or `media`: ```json { "conversationId": "…", "text": "Your order has shipped." } ``` ```json { "conversationId": "…", "media": { "id": "a17d…" } } ``` `media.caption` (≤ 1024 chars, refused on audio and stickers), `media.filename` (documents only) and `media.voice` are optional. `media.voice` defaults to the asset's own `voiceNote`; setting it `true` on a file that was not uploaded with `?purpose=voice_note` is a `400`, never a silent upgrade. Setting it `false` on a recording sends it as an ordinary audio file. **There is no `media.link` or `media.url`, and there will not be one.** A URL we never fetched skips every check this pipeline exists to run — the type sniffer, the allowlist, the size caps, the polyglot check — Meta then fetches it under limits we cannot pre-check, and a failure comes back as an opaque error against **your** number rather than as a local `400`. It also leaves the message with no attachment in your own inbox. A media send costs **two** API calls: the upload and the send. Both count against `api_calls_month` and the per-minute rate limit. `body` on the returned message is a **preview** (`[Voice note]`, `[Image] my caption`), not the caption you sent. Which conversations and files a key may use follows its role (see **Roles**). An **admin** key may send into any conversation in its workspace and attach any file in it. An **agent** key may send only into the conversations given to the person who made it, and attach only files that person could see, or files this same key uploaded with `POST /media`. Returns **`202 Accepted`** with the message row at `status: "queued"`. **202 is not a delivery promise.** The send goes through the same pipeline an agent's reply does: it is queued, then every guard is checked again (24-hour window, opt-out, blocked contact, channel health) before anything reaches Meta. Poll `GET /conversations/{id}/messages` or subscribe to the `message.status` outbound webhook for the outcome. Fast-fail `409`s you can get before queueing: closed customer-service window, disconnected channel, contact with no WhatsApp identity. Free-form **text and media** here. The only template send in v1 is a one-time passcode through `POST /messages/template` below; marketing and utility template sends need per-template variable validation and a category, and shipping half of that publicly is how unreviewed marketing goes out on a client's number. Use the dashboard, or broadcasts, for those. Instagram and Messenger attachments are not supported: both Send APIs need a public file URL, and media uploaded here is kept private. Sending the same `media.id` twice sends the file twice — there is no request-level idempotency anywhere in v1 yet. ### `POST /messages/template` — `templates:send` Send a login or verification code to **any** WhatsApp number — no existing conversation needed — with an approved **AUTHENTICATION** template. ```json { "to": "+919876543210", "channelId": "…", "templateName": "login_code", "language": "en", "code": "482913" } ``` * `to` — E.164 **with the `+` and country code**. We never guess a country code: guessing one sends a stranger somebody else's code. * `channelId` — the WhatsApp number that sends it. Required when the workspace has more than one connected number; optional when it has exactly one. A non-admin key may use only numbers its maker may work. * `templateName` + `language` — an **approved** template in **that number's** WhatsApp business account (as listed by `GET /templates`). * `code` — 4 to 8 digits, as a string. It fills the body's `{{1}}` and the copy-code / one-tap / zero-tap button. **Authentication templates only.** A marketing or utility template is refused with `400 invalid_request`, whatever its content. That is deliberate, not a gap waiting to be filled: those categories need consent and variable rules a public endpoint cannot check for you. The number is found or added as a contact and the code lands in its WhatsApp thread in the inbox, the same way an inbound message or a broadcast would. The thread stays **Resolved** and nobody is asked to reply. The code itself is **masked** (`••••••`) in the inbox, in previews and in `GET /conversations/{id}/messages`, so staff cannot read users' codes. Returns **`202 Accepted`**: ```json { "messageId": "…", "conversationId": "…", "status": "queued" } ``` As with `POST /messages`, 202 is not delivery. The send is still refused for a blocked or deleted contact, a disconnected number, a template Meta has paused, and an empty prepaid wallet (`insufficient_balance`). Authentication templates may be sent outside the 24-hour window, so there is no window check. Watch the `message.status` webhook for the outcome: `errorCode` `131026` means the number is not on WhatsApp (or cannot receive the message), so fall back to SMS. **Limit per number: 5 codes per number per WhatsApp channel per hour**, on top of the per-key limit. The sixth gets `429 rate_limited` with `Retry-After` (seconds until the oldest of the five is an hour old). This is what stops a leaked key from flooding a stranger's phone. | Error | When | | --- | --- | | `400 invalid_request` | Bad `to` / `code`, missing `templateName`/`language`, several numbers and no `channelId`, a non-authentication template, a template shape we cannot fill (a header, a non-OTP button, no `{{1}}`) | | `404 not_found` | No such connected channel, or no template with that name and language on that number | | `409 conflict` | No connected WhatsApp number, number disconnected or not linked to a business account, template not approved | | `429 rate_limited` | Per-key limit, or 5 codes to this number in the last hour | | `402 payment_required` | Subscription or trial over | ### `GET /templates` — `templates:read` Approved templates only — a draft, rejected or Meta-paused template is not sendable, and listing it would invite you to build against a name that will be refused. `bodyVariableCount` tells you how many `{{n}}` placeholders the body has. ### `GET /me` — `contacts:read` Which workspace this key is bound to, what it may do, and the rate limit. Use it as a health check. If the workspace here is not the one you expect, you are holding the wrong key. --- ### `GET /wallet` — `messages:send` The prepaid message wallet, when the workspace's plan uses one. Each WhatsApp message's price is set aside when it is sent and only charged once WhatsApp reports it delivered and billable; a failed or unbilled message costs nothing. When the balance cannot cover a message, the send fails with `error_code: "insufficient_balance"` (visible on the message and in its `message.status` webhook). ```json { "data": { "enabled": true, "currency": "INR", "balance": "1234.5600", "balanceCentipaise": 12345600, "pricePerMessage": { "marketing": "0.1000", "utility": "0.0500", "authentication": "0.0500", "service": null } } } ``` Amounts are rupees as decimal strings (4 places) and 1/100 paise as integers; `null` means that message type is free. `enabled: false` means the plan does not charge per message. ## Outbound webhooks The push half of the integration story is configured in **Settings → Webhooks**. Each endpoint has its own secret; deliveries are HMAC-signed and timestamped: ``` X-Chatzyn-Timestamp: 1785913200 # unix seconds X-Chatzyn-Signature: sha256= # HMAC-SHA256 of "." X-Chatzyn-Event: message.status X-Chatzyn-Delivery: ``` Verify by recomputing the HMAC over `"."` — **the raw bytes**, before any JSON parse — and comparing in constant time. Reject anything with a timestamp more than five minutes old; that is what stops a captured delivery being replayed at you later. `message.status` payload: ```json { "messageId": "…", "conversationId": "…", "channelId": "…", "channel": "whatsapp", "status": "failed", "errorCode": "131026", "errorTitle": "Message undeliverable", "at": "2026-11-04T09:12:00.000Z" } ``` `status` is `delivered`, `read` or `failed` as WhatsApp reports them. `errorCode` and `errorTitle` appear only on `failed`. For a failure WhatsApp reports, they are Meta's error code and title. A send refused before it reached Meta (blocked contact, `insufficient_balance`, paused template) also fires one `failed` event, with our code (`contact_blocked`, `insufficient_balance`, …) and the reason text as `errorTitle`. Failed deliveries retry with exponential backoff and are marked `dead` after the configured attempt ceiling. Every attempt is visible in the dashboard. --- ## Not in v1 (deliberately) * Marketing and utility template sends (authentication/OTP is the one template send in v1), broadcast triggering, flow triggering, leads/deals CRUD. None are half-shipped here. * Reading media bytes back. `ApiMedia` carries no URL: a presigned link is a bearer capability with a 300-second life, so media stays private. * An `Idempotency-Key` header. Worth doing across all of v1 at once. * Bulk endpoints. Loop the single-resource ones — the rate limiter is sized for it. * Anything that crosses a workspace boundary. There is no such endpoint and there will not be one.