Chakra Chat API: Complete Developer Guide for WhatsApp Automation

TL;DR: The Chakra Chat API sits on top of the WhatsApp Cloud API and adds what raw Meta access doesn't give you out of the box: role-scoped API keys, a friendlier webhook format alongside full Meta pass-through, built-in lead and campaign management, calling endpoints, and a broader Platform/CRM layer (processes, tasks, users) for building real workflows — not just sending messages. This guide covers authentication (API keys, roles, Bearer tokens), the six capability areas the API is organized around, rate limits (200 calls/minute), how inbound webhooks and HMAC validation work, when to reach for the official TS/JS SDK versus raw HTTP calls, and the integration patterns — CRM sync, automation triggers via tools like n8n, e-commerce platforms like Shopify, and broadcast sends — that cover most real-world use cases. This is the guide to read before opening the endpoint-level API docs — it explains the why and the shape of the system, not just the individual calls.

Introduction

If you're evaluating the Chakra Chat API, you've probably already looked at the WhatsApp Cloud API docs directly and are wondering what a BSP layer actually adds. This guide answers that, then walks through the practical mechanics — auth, architecture, rate limits, webhooks, the SDK, and the integration patterns most developers end up building. For endpoint-level detail (request/response schemas, parameters), the Chakra API docs are the reference to keep open alongside this guide.

What the Chakra API Enables vs. the WhatsApp Cloud API Directly

Meta's Cloud API is the foundational layer — it's what actually sends and receives WhatsApp messages, manages templates, and handles the phone number infrastructure. Every WhatsApp Business Solution Provider, including Chakra, is ultimately built on top of it. So why not integrate with Meta directly?

For some teams, that's a reasonable choice. But going direct means owning everything Meta doesn't provide natively: business verification and onboarding flow, template approval tooling, a human-usable inbox for the team members who aren't developers, and — critically for anything beyond a single automated flow — the surrounding business logic like lead tracking, campaign management, and CRM-style record keeping that Meta's API has no concept of.

What the Chakra API adds on top of raw Cloud API access:

• Both a pass-through and a friendlier webhook format. You can receive raw Meta-format events directly, or a normalized Chakra event format that's easier to work with — your choice, per use case.
• Role-scoped API keys instead of a single account-wide credential, so different integrations (a Shopify sync, an n8n automation, an internal dashboard) can each hold only the access they actually need.
• A Leads and Campaigns layer — first-class endpoints for creating and updating leads and managing lead campaigns, rather than building that data model yourself on top of raw messaging events.
• A Platform/CRM layer — Processes, Tasks, Users, and Background Jobs, giving you generic workflow and record-keeping primitives that sit alongside the WhatsApp-specific endpoints, useful when the WhatsApp integration is one part of a broader operational system.
• Calling API endpoints for WhatsApp's voice calling capability — settings, permissions, and call management — as a natively supported capability area rather than something bolted on separately.
• A shared inbox and non-developer tooling underneath the same account, so the API isn't the only way into the system — support and marketing teams work in the same platform your integrations are built against.

When direct Meta integration might still make sense: if you're building infrastructure at massive scale with a dedicated platform team, or you need Cloud API functionality the instant Meta ships it before any BSP layer catches up. For most product and growth teams — anyone building automation, CRM sync, or customer-facing flows without wanting to own the full messaging infrastructure stack — a BSP API like Chakra's is the faster, lower-maintenance path.

Authentication: API Keys, Roles, and Bearer Tokens

Every Chakra API call is authenticated with an API key, and the setup is intentionally structured around least-privilege access rather than a single all-powerful credential.

Creating an API key:

1. Go to the API Keys section in your Chakra Chat account.
2. Give it a meaningful name — since you'll likely end up with several keys over time, naming by use case ("n8n-support-bot," "shopify-order-sync") makes management far easier down the line than generic names.
3. Add an optional description for additional context.
4. Assign an Access Role. The key inherits exactly the privileges of the role you assign — nothing more.

Using the key: once created, open the key's detail view and find the Access Tokens section. The token there is what you pass as a Bearer token in the Authorization header of every API request:

Authorization: Bearer {your_access_token}

The core guideline that matters most in practice: always scope keys to the least privilege the use case actually needs. A few concrete habits this implies:

• Use separate keys per integration, not one shared key across every automation. If a specific integration is compromised or misbehaves, a scoped key limits the blast radius to that integration's permissions.
• Be especially careful with frontend-exposed keys. Any API key used in client-side code is visible to anyone inspecting network traffic — these should carry the minimum possible privilege, and ideally should never hold write access to sensitive operations like messaging or lead data.
• Review key roles periodically, especially as integrations evolve — a key created for a narrow initial use case sometimes accumulates broader responsibility over time without its role being revisited.

API Architecture: The Six Capability Areas

The Chakra API is organized around six practical capability areas. Understanding this shape upfront makes it much faster to find the right endpoint later, rather than searching the full reference each time.

1. Messaging — sending and receiving actual WhatsApp messages. This spans session (free-form, within the 24-hour window) messages, media upload and retrieval, WhatsApp Flows key management, and Groups management (create, list, manage participants and join requests). Both a Meta-format pass-through path and Chakra-native message endpoints are available here.

2. Templates — creating, listing, and updating WhatsApp message templates, plus dedicated endpoints for sending template messages either to a specific phone number or in the context of a Process (see Platform below). Template send and template management are deliberately separate endpoint groups, since the create/manage lifecycle (subject to Meta's approval process) is a different concern from the act of sending an already-approved template.

3. Leads — creating and updating lead records by phone number, giving you a structured way to track prospects and customers tied to WhatsApp conversations without building that data model from scratch on top of raw chat data.

4. Campaigns — adding or removing phone numbers from lead campaigns, the building block for structured outbound sequences (nurture flows, broadcast segments) rather than one-off sends.

5. Calling — the WhatsApp Calling API surface: fetching and configuring calling settings for a phone number, checking call permission state (whether a given contact has granted business-initiated calling permission), and managing active calls.

6. Platform/CRM — the generic workflow layer: Processes (create, update, list, bulk operations, delete — essentially configurable structured records), Tasks, Users, Photos, and Background Jobs. This is the part of the API that isn't WhatsApp-specific at all — it's a lightweight CRM/workflow primitive set that sits alongside the messaging capability, useful when you want the WhatsApp integration and your broader operational data living in the same system rather than stitched together across separate tools.

Alongside these six, two supporting areas are worth knowing about: Chat & Chat Messages (listing chats and message history for a phone number or conversation — useful for building custom inbox views or pulling context into another system) and Partner Access (Connect Token creation and WhatsApp plugin/WABA configuration management — relevant if you're building on top of Chakra as an embedded partner rather than a single-account integration).

Rate Limits and What They Mean in Practice

Chakra enforces a limit of 200 API calls per minute. This is the number to design around, not just be aware of.

What this means practically:

• Bulk operations need batching, not brute force. If you're syncing a large lead list or sending a broadcast to thousands of recipients, structure the work as batches with pacing built in, rather than firing every request as fast as your code can loop.
• Build in backoff handling. Any integration making frequent calls should handle rate-limit responses gracefully — retry with backoff rather than failing the whole operation or hammering the API immediately after a limit response.
• Webhook-driven architectures naturally stay under the limit for most use cases, since you're reacting to inbound events rather than polling — this is one more reason to lean on webhooks (covered next) over polling patterns for anything read-heavy, like checking for new messages or status updates.
• High-volume broadcast or sync jobs should run as background jobs, not inline with a user-facing request — the Platform layer's Background Job endpoints exist partly for this reason, letting you track long-running batch operations without blocking on the 200/minute ceiling in real time.

Webhooks: Inbound Events and What You Can Do With Them

WhatsApp — and by extension the Chakra API — operates asynchronously. When you send a message, the API accepts the request and later publishes events indicating whether it was sent, delivered, read, or failed. Inbound messages from customers are also delivered as events, not as something you poll for. This makes webhooks the backbone of any real-time integration.

There are two distinct webhook types, and picking the right one matters:

Pass-through events webhook — delivers Meta's raw event format directly to your endpoint, unmodified. This includes inbound messages, status events, template update notifications, and account-level updates. Configure it from the WhatsApp Setup page's "More" tab, under the pass-through webhook URL field. Because the format matches Meta's own documentation exactly, this is the right choice if you're already familiar with Cloud API payloads or need access to event types the normalized format doesn't cover.

Chakra events webhook — a friendlier, normalized format for a curated set of event types, configured from the same WhatsApp Setup page by enabling "Chakra Webhooks" and selecting which event types to receive. Events arrive with two consistent keys: event (one of message, status, message_echo, or smb_message_echo) and payload (the corresponding message or delivery status data). This is the better default for most integrations, since you're not parsing Meta's full nested event structure for simple use cases like "notify me when a customer replies."

A sample inbound text message event (pass-through format) gives a sense of the shape you're working with:

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "83784929738012",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "display_phone_number": "917259775805", "phone_number_id": "694794789348887" },
        "contacts": [{ "profile": { "name": "John" }, "wa_id": "919911223344" }],
        "messages": [{
          "from": "919911223344",
          "id": "wamid.xxxx",
          "timestamp": "1756322278",
          "text": { "body": "Hi, can you please help me out with an issue" },
          "type": "text"
        }]
      },
      "field": "messages"
    }]
  }]
}

Securing your webhook with HMAC validation. Since webhook endpoints need to be publicly accessible with no built-in authentication requirement, verifying that incoming requests genuinely originated from Chakra matters. The mechanism:

1. Set an HMAC secret under Admin → Team → Secrets in your Chakra account. Once set, every webhook event includes an X-Chakra-Signature-256 header.
2. On your end, compute an HMAC-SHA256 hash of the raw request body string (not a parsed/re-serialized JSON object — many HTTP frameworks transform the body, which breaks the comparison) using your secret as the key.
3. Compare your computed hash to the value in X-Chakra-Signature-256 (note: the header value has no sha256= prefix, unlike some other providers' conventions). A match confirms the payload is authentic and untampered.

The SDK — When to Use It vs. Raw API Calls

Chakra publishes an official TypeScript/JavaScript SDK, @chakrahq/chakra-chat-sdk, usable in both server-side and client-side JavaScript environments.

npm i @chakrahq/chakra-chat-sdk

All requests through the SDK authenticate with the same Bearer access token used for raw API calls, provided once at initialization rather than attached to every individual call manually.

When the SDK is the better choice:

• You're building in a Node.js or JavaScript/TypeScript environment and want typed request/response shapes rather than hand-rolling HTTP calls and parsing raw JSON.
• You're calling multiple endpoints within the same service and want a single initialized client rather than repeating auth header logic everywhere.
• You want to move faster during initial development and are fine with the SDK's release cadence for newer endpoints.

When raw HTTP calls make more sense:

• You're integrating from a non-JS environment (Python, Ruby, Go, or a low-code tool like n8n's HTTP Request node) — the API is fully usable via plain HTTP requests, and this is actually the more common pattern for automation-platform integrations, since tools like n8n work natively with HTTP nodes rather than importing an npm package.
• You need an endpoint that's available in the raw API surface but not yet wrapped in the current SDK version.
• You're doing a lightweight, one-off integration where pulling in a full SDK dependency isn't worth it for a handful of calls.

In practice, most teams end up using both: the SDK for a core backend service that talks to Chakra regularly, and raw HTTP calls for lighter integrations like automation platform workflows or serverless functions triggered by webhooks.

Common Integration Patterns

CRM sync. Use the Leads endpoints (Create a lead, Update Lead By Phone Number) to keep a customer or prospect record in sync as WhatsApp conversations progress, and pair this with the Platform layer's Process/Task endpoints if you want structured records and workflow state tracked in the same system rather than round-tripping to an external CRM for every update.

Automation triggers via n8n. A common pattern: configure the pass-through webhook to point at an n8n webhook trigger node, filter for message events, feed the message content into an AI Agent node (or any processing logic), then send the response back via an HTTP Request node hitting the messages endpoint directly:

POST https://api.chakrahq.com/v1/ext/plugin/whatsapp/{pluginId}/api/v22.0/{whatsappPhoneNumberId}/messages
Authorization: Bearer {chakraAccessToken}
Content-Type: application/json

The pluginId and whatsappPhoneNumberId values are both available from the WhatsApp Setup page in your Chakra account — the plugin ID via the three-dot menu next to Save, and the phone number's Meta ID via the gear icon next to the phone number list. This pattern — webhook in, process, HTTP call out — generalizes well beyond n8n to any workflow automation tool that supports webhook triggers and HTTP request nodes.

E-commerce order lifecycle automation (Shopify-type integration). Rather than building this from raw webhooks, platforms like Shopify typically connect through a no-code sync layer that maps order lifecycle events (created, fulfilled, shipped, delivered) to template message sends automatically, alongside abandoned checkout events feeding into cart-recovery template sequences. For custom or non-Shopify e-commerce platforms without a native integration, the same pattern is buildable directly on the API: an order-status webhook from your platform triggers a server-side handler that calls the template send endpoint with the right variables populated from the order data.

Broadcast via API. For sending a Marketing or Utility template to a segment of contacts — rather than a single conversational reply — the pattern is: build the recipient list (often via the Campaigns endpoints, adding phone numbers to a lead campaign), then loop through sends to the template-send endpoint, respecting the 200-calls-per-minute rate limit with batching and backoff as covered above. For large lists, running this as a background job rather than a synchronous loop keeps the operation resilient to partial failures and rate-limit pauses.

Where to Go From Here

This guide covers the architecture and reasoning — the endpoint-level detail (exact request bodies, response schemas, and the full list of available operations within each capability area) lives in the Chakra API documentation. A few docs worth bookmarking directly as you start building:

• API Keys — creating and scoping keys
• Inbound Events Webhook — full webhook and HMAC validation reference
• API Rate Limits
• Chakra Chat SDK
• How to figure out pluginId and whatsappPhoneNumberId — needed for most direct HTTP integrations

For a hands-on walkthrough of a specific automation build, the n8n AI Agent integration guide and the Shopify integration guide both build directly on the concepts covered here — start with this guide for the shape of the system, then use those for a concrete, step-by-step build.