ClanFee Business API

Deliver messages to ClanFee users from your own systems over HTTP — order updates, OTPs, alerts and two-way conversations, the way the WhatsApp Business Platform works.

Overview

A message you send lands in the recipient's ClanFee chat exactly like any other 1-to-1 message — with push notification and unread badge — from your business's identity, which the user can mute or block like any contact.

Base URL

https://api.clanfee.com

Two people are usually involved: the business owner, who signs up and gets verified, and their developer, who integrates the HTTP API below.

1. Create a business account

Onboarding is self-serve. Go to api.clanfee.com/business and:

1. Register — business name, email, password, website domain, a short description, and a logo.
2. Verify email — enter the 6-digit code sent to your address.
3. Verify phone — enter your mobile number and the SMS code.

Once both are verified your account activates automatically and your API credentials appear — a client_id and a client_secret.

Submitting business verification documents (legal entity, display name) is optional and raises your sending tier — see tiers. You can send at the entry tier without it.

2. Get an access token

Exchange your client credentials for a short-lived, scoped access token using the OAuth 2.0 client_credentials grant.

POST /api/business/oauth/token
# Content-Type: application/json
{
  "grant_type": "client_credentials",
  "client_id": "cfc_…",
  "client_secret": "cfs_…",
  "scope": "messages:send templates:read"
}

Response:

{
  "access_token": "cfb_…",
  "token_type": "Bearer",
  "scope": "messages:send templates:read",
  "expires_in": 5184000
}

Send it as a bearer token on every API call:

Authorization: Bearer cfb_…

Tokens default to a 60-day life (max 365). You can hold several at once, so rotate by issuing a new one, deploying it, then revoking the old — no downtime. Scopes: messages:send, messages:read, templates:read, templates:write, optins:write, webhooks:manage.

3. Consent & the 24-hour window

A business may not message just anyone. Every send must satisfy one of these:

• The user messaged you in the last 24 hours — the "customer-service window" is open, and you can reply free-form (any text).
• Otherwise you need a recorded opt-in for that user and you must send an approved template.

The recipient must already be a ClanFee user (matched by phone number) — the API never creates accounts. If they've blocked your business, the send is refused.

4. Send a message

Inside an open window — free-form text:

POST /api/business/v1/messages
# Authorization: Bearer cfb_…
{ "to": "919876543210", "type": "TEXT", "content": "Your order has shipped!" }

Outside the window — an approved template with its parameters:

POST /api/business/v1/messages
{ "to": "919876543210", "template": "order_shipped", "params": ["AC-1029"] }

Response:

{
  "status": "SENT",
  "messageId": 998877,
  "category": "UTILITY",
  "charged": "₹0.16",
  "conversationWindow": "CLOSED",
  "balance": "₹2,399.84"
}

to accepts any format — +91 98765 43210, 9198765 43210 and 9876543210 all resolve to the same user. Send to many at once with POST /api/business/v1/messages/bulk (to as an array, max 100).

Templates

Templates are pre-approved message bodies with {{1}}-style placeholders. They let us review content before it reaches users, which is why they're required outside the 24-hour window. Submit one for review:

POST /api/business/v1/templates
{
  "name": "order_shipped",
  "language": "en",
  "category": "UTILITY",
  "body": "Your order {{1}} has shipped and arrives in 2–3 days."
}

Categories: MARKETING, UTILITY, AUTHENTICATION, SERVICE — these set the price. A template can't be used until an admin approves it (GET /api/business/v1/templates shows status).

Opt-ins

Record a user's consent before first contact. You're asserting you captured it; the source is what you'd point to if that were ever questioned.

POST /api/business/v1/optins
{ "phone": "919876543210", "source": "checkout_form" }

Remove it with DELETE /api/business/v1/optins?phone=919876543210. A user blocking your business also revokes their opt-in automatically.

Webhooks

Receive user replies and delivery-status updates. Point us at an HTTPS endpoint:

PUT /api/business/v1/webhook
{ "url": "https://yourapp.com/clanfee/webhook", "active": true }

We POST two event types — message.inbound (a user replied) and message.status (delivery state). Each carries an X-ClanFee-Signature header: a hex HMAC-SHA256 of the exact request body, keyed with your webhook secret. Verify it to confirm the call came from us. Deliveries retry with backoff, so a brief outage on your side won't drop events.

Pricing & tiers

Billing is prepaid and charged per message by the template category:

Sending volume is capped by tier — new accounts start at 50 messages/day and step up automatically as you use your allowance and maintain quality (few blocks or reports). Verifying your business raises the ceiling. A poor quality rating throttles sending until it recovers. Check your standing any time:

GET /api/business/v1/me

All endpoints

Status codes