Getting Started with the WhatsApp API — WhatsApp API Docs

StartMessaging is a WhatsApp CRM built on the official WhatsApp Business Platform (Cloud API). You connect your own WhatsApp Business Account (WABA) through Meta’s Embedded Signup, and your systems talk to it through a REST API and signed webhooks.

This guide takes you from sign-up to your first message sent over the API.

How billing works

Meta bills message charges directly to your WhatsApp Business Account, using the payment method you add in WhatsApp Manager.
StartMessaging charges only a flat subscription. There is no wallet, no credits and no per-message markup. The API never charges per message.
Plans: Developer (the API and a view-only dashboard, sized by API messages a month, including a free size), Team (adds the shared inbox, contacts, campaigns and auto-replies), Business (adds chatbot flows, WhatsApp Forms, advanced campaigns, the sales pipeline and conversions) and Enterprise (a custom contract). The developer API is on every plan.
Your first workspace starts with a 14-day free trial of Business for up to 3 people, 1,000 contacts and 1,000 API messages. The trial is once per account owner: a workspace you create after it starts on Developer Free.
When the trial ends, a subscription is cancelled or ends, or a checkout is never finished, the workspace moves to Developer Free: the API keeps working within that plan’s limits, and the dashboard becomes view-only. Choose a plan in Billing to get the rest back.
A failed renewal first shows as past due, and the workspace stays fully usable. If Razorpay gives up on the renewal, the workspace becomes read-only on its old plan: every change, sends included, answers 402 SUBSCRIPTION_REQUIRED until billing is fixed.

Before you start

You need:

A Facebook account that can manage (or create) a Meta Business portfolio.
A phone number for your business that can receive a verification code. If the number is currently used in the WhatsApp or WhatsApp Business app, Meta’s signup flow explains how to move it.
A payment method (card) to add in WhatsApp Manager. Meta needs it before you can send template messages.

Step 1: Create your account

Go to the sign-up page.
Enter your details and verify your email address.
Add your mobile number and enter the 6-digit code we send you by SMS. Your country is set from this number. Codes currently go only to Indian (+91) mobile numbers.

Outside India? Contact sales and we’ll open your workspace for you.

Step 2: Create a workspace

A workspace holds one WhatsApp Business Account, its team, contacts, templates and API keys.

Click Create workspace and give it a name.
If this is your first workspace, your 14-day free trial of Business starts: every Business feature, including the developer API, for up to 3 people, 1,000 contacts and 1,000 API messages. A later workspace starts on Developer Free.

Step 3: Connect WhatsApp

Open Connect in the workspace sidebar. Only Owners and Admins can connect.

Click Connect with Facebook. Meta’s Embedded Signup opens in a popup.
Log in with Facebook, then choose or create your Meta Business portfolio, WhatsApp Business Account and phone number.
Verify the phone number with the code Meta sends by SMS or voice call.
Back in StartMessaging, enter a 6-digit two-step verification PIN for the number. This registers it on the Cloud API. If you close the dialog, an Enter PIN prompt stays on the Connect page until the number is registered.

Once connected, the Connect page shows live account health from Meta: daily conversation limit, quality rating, business verification and account review. Use Refresh from Meta if you change something in WhatsApp Manager and the status looks out of date.

One WABA per workspace. Each workspace connects one WhatsApp Business Account, and an account can be connected to only one workspace. For a different WhatsApp Business Account, create another workspace.

Step 4: Add a payment method in WhatsApp Manager

After connecting, the Connect page shows a checklist item: Payment method added in Meta.

Click Open WhatsApp Manager →.
Add a credit card or other payment method to your WhatsApp Business Account.

Meta charges for delivered template messages directly against this payment method, utility templates included, even inside the customer’s 24-hour window. Free-form replies inside the window are free up to a monthly allowance per number. Without a payment method, Meta refuses template sends and the API answers 402 META_PAYMENT_REQUIRED. This is never a StartMessaging charge.

Step 5: Create a template and get it approved

To start a conversation (or message a customer whose 24-hour window has closed), WhatsApp only allows approved templates.

Open Templates and click Create template, or start from one of the examples.
Pick a category (Marketing, Utility or Authentication), a language, and write the body. Add a sample value for every variable so Meta can review it.
Click Submit to Meta.

Meta reviews every template. Review time is set by Meta, and the template shows as Pending review until Meta decides. Only templates with the status Approved can be sent. See Message Templates for categories, limits and button types.

Step 6: Create an API key

Open Developers → API keys. You need the Manager role or above.
Click Create key, give it a name and choose its access: Full access, Send only, Read only or Custom scopes.
Copy the key. It starts with sm_live_ and is shown only once. Store it in a secret manager or environment variable, never in browser or mobile app code.

See Authentication for scopes and key handling.

Step 7: Make your first call

GET /api/v1/me needs no scope. It confirms your key works and shows your workspace, plan, the key’s scopes, rate limits, live usage and this month’s API messages against your plan’s allowance.

curl https://waba-api.startmessaging.com/api/v1/me \
  -H "Authorization: Bearer sm_live_your_api_key"

{
  "data": {
    "workspace": { "id": "6f1e2d3c-4b5a-4968-8776-5a4b3c2d1e0f", "name": "Meera Boutique", "slug": "meera-boutique" },
    "plan": { "code": "TRIAL", "name": "Free trial", "tier": 0 },
    "apiKey": { "id": "0e9d8c7b-6a5f-4e3d-2c1b-0a9f8e7d6c5b", "prefix": "sm_live_ab12", "scopes": ["messages:send", "messages:read"] },
    "limits": { "requestsPerMinute": 300, "sendsPerHour": 100 },
    "usage": { "requestsThisMinute": 1, "sendsThisHour": 0 },
    "messages": { "period": "2026-10", "sent": 0, "limit": 1000, "stopAt": 1000, "resetsAt": "2026-10-31T18:30:00.000Z" }
  },
  "meta": { "requestId": "b7c1e0d2-…", "timestamp": "2026-10-02T10:00:00.000Z" }
}

Step 8: Send your first template

Send an approved template with POST /api/v1/messages. Use the template’s name exactly as Meta approved it (shown in the template’s Send via API panel) and its language code. For a carousel template, don’t copy the panel’s request: it has no cards, and the panel still says carousels can’t be sent through the API. The API does send them, with every card in template.carouselCards (see Carousel templates).

curl -X POST https://waba-api.startmessaging.com/api/v1/messages \
  -H "Authorization: Bearer sm_live_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-919876543210" \
  -d '{
    "to": "+919876543210",
    "type": "template",
    "template": {
      "name": "order_confirmation",
      "language": "en_US",
      "parameters": [{ "text": "Aarti" }, { "text": "#1042" }]
    },
    "clientReference": "order-1042"
  }'

const res = await fetch('https://waba-api.startmessaging.com/api/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sm_live_your_api_key',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'welcome-919876543210',
  },
  body: JSON.stringify({
    to: '+919876543210',
    type: 'template',
    template: {
      name: 'order_confirmation',
      language: 'en_US',
      parameters: [{ text: 'Aarti' }, { text: '#1042' }],
    },
    clientReference: 'order-1042',
  }),
});
const { data } = await res.json();
console.log(data.id, data.status); // "3f6c2a1e-…" "sent"

import requests

res = requests.post(
    "https://waba-api.startmessaging.com/api/v1/messages",
    headers={
        "Authorization": "Bearer sm_live_your_api_key",
        "Idempotency-Key": "welcome-919876543210",
    },
    json={
        "to": "+919876543210",
        "type": "template",
        "template": {
            "name": "order_confirmation",
            "language": "en_US",
            "parameters": [{"text": "Aarti"}, {"text": "#1042"}],
        },
        "clientReference": "order-1042",
    },
)
print(res.json()["data"])

A 201 response means WhatsApp accepted the message. Delivery and read receipts follow; subscribe to the message.* webhooks or look the message up with GET /api/v1/messages/{id}.

The recipient is added to your contacts automatically (source api), and the message appears in the shared team inbox (on Team, Business, Enterprise and the free trial), so your team can pick up the reply.

Next steps

Authentication: API keys and scopes
Send Messages: text, media, interactive and template messages
Message Templates: categories, components and the OTP recipe
Webhooks: incoming messages and delivery receipts
Errors & Limits: error codes and rate limits

FAQ

Is there a sandbox or test number? No. You connect your own WhatsApp Business Account from the start. The 14-day free trial includes the developer API (300 requests per minute, 100 sends per hour, 1,000 API messages), which is enough to build and test an integration end to end. After it, Developer Free keeps the API on 100 messages a month.

Who pays for WhatsApp messages? Meta bills message charges directly to the payment method on your WhatsApp Business Account. StartMessaging charges only the subscription and never charges per message.

How long does template approval take? Meta reviews every template and sets the timing. The dashboard shows the template as Pending review until Meta decides, and the template.status_updated webhook tells your system when the status changes.

Can I connect more than one WhatsApp Business Account? Each workspace connects one WhatsApp Business Account. To use another account, create another workspace and run Connect there. It starts on Developer Free, because the free trial is used once per account owner; choose a plan for it in Billing.

What happens when my trial ends? If you don’t choose a plan, the workspace moves to Developer Free: your API keys keep working within its limits (100 API messages a month), and the dashboard becomes view-only. Choose Developer, Team or Business in Billing at any time.

Who can create API keys? Members with the Manager role or above, in Developers → API keys.