Developers के लिए WhatsApp API: curl, Node.js और Python से पहला template message भेजें

आप क्या बनाएँगे

WhatsApp template message api se kaise bheje, इस tutorial के अंत तक आप यही अपने server से करके देख लेंगे: एक order-shipped सूचना, जिसकी body में ग्राहक का नाम, header में product की फ़ोटो और tracking लिंक वाला button होगा। बिज़नेस WhatsApp पर बातचीत templates से ही शुरू करता है; free-form मैसेज सिर्फ़ ग्राहक के आख़िरी मैसेज के 24 घंटे के अंदर भेजे जा सकते हैं (24-hour customer service window)।

Broadchat आपके जुड़े नंबर के लिए एक channel endpoint देता है, जो Meta के Cloud API वाला request format लेता है और चैनल के credentials के साथ उसे Meta तक भेजता है। अगर आपने पहले Cloud API इस्तेमाल किया है, तो सिर्फ़ base URL और token बदलते हैं। दोनों developer विकल्पों (यह endpoint और API campaigns) का overview Broadchat REST API पेज पर है।

Step 1: channel access token बनाएँ

यह सिर्फ़ account owner कर सकता है:

1. Channels → All Channels खोलें।
2. अपने चैनल के कार्ड पर ⋮ मेन्यू खोलें और Access Token चुनें।
3. API Details विंडो में Access Token (यह bc_ से शुरू होता है), API URL, API Version, WABA ID, Phone Number ID और Business ID दिखते हैं। Copy Token दबाकर इसे अपने secret manager या environment variables में रखें।

API URL आपके पैनल का अपना पता और उसके बाद /api/meta होता है, जैसे https://app.yourpanel.in/api/meta। Token सिर्फ़ अपने चैनल की phone number id और WhatsApp Business account id के लिए काम करता है।

Step 2: template की हूबहू जानकारी पढ़ें

CRM → WhatsApp Templates खोलें और मंज़ूर template ढूँढें। चार बातें चाहिए, और हर एक हूबहू मिलनी चाहिए:

मंज़ूर body यह है: Hi {{1}}, your Rangoli Home order {{2}} has been shipped with {{3}}. Track it with the button below. मिलती-जुलती मंज़ूर wording order update templates में देखें।

Step 3: curl से request भेजें

curl -X POST "https://app.yourpanel.in/api/meta/v21.0/123456789012345/messages" \
  -H "Authorization: Bearer $BC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "919876543210",
    "type": "template",
    "template": {
      "name": "order_shipped",
      "language": { "code": "en" },
      "components": [
        {
          "type": "header",
          "parameters": [
            { "type": "image", "image": { "link": "https://cdn.rangolihome.in/products/cushion-48213.jpg" } }
          ]
        },
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "Priya" },
            { "type": "text", "text": "#48213" },
            { "type": "text", "text": "Delhivery" }
          ]
        },
        {
          "type": "button",
          "sub_type": "url",
          "index": "0",
          "parameters": [ { "type": "text", "text": "48213" } ]
        }
      ]
    }
  }'

Host, version और phone number id की जगह अपनी API Details विंडो की values डालें। Body के बारे में:

• to देश के कोड के साथ नंबर है, सिर्फ़ अंक (919876543210)।
• Body parameters क्रम से भरते हैं: पहला {{1}} भरता है, और इसी तरह आगे। ठीक उतने ही भेजें जितने template में हैं।
• Button का index उसकी जगह है, जो 0 से शुरू होती है, और उसका parameter URL के आख़िर वाला variable भरता है।
• Media सार्वजनिक HTTPS लिंक से जाता है। Channel endpoint से multipart media upload supported नहीं है, इसलिए फ़ोटो अपने CDN या storage पर रखें।

सफल call पर Meta का response लौटता है, जैसे:

{
  "messaging_product": "whatsapp",
  "contacts": [ { "input": "919876543210", "wa_id": "919876543210" } ],
  "messages": [ { "id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQTQ1RkY2..." } ]
}

messages[0].id सेव करें। बाद में delivery statuses इसी से मिलाए जाते हैं।

Step 4: इसे Node.js या Python में ले जाएँ

Node.js 18 या उसके बाद के version में fetch पहले से मौजूद है:

// send-template.mjs
const API_URL = process.env.BC_API_URL;      // e.g. https://app.yourpanel.in/api/meta
const API_VERSION = process.env.BC_API_VERSION; // e.g. v21.0, from the API Details window
const PHONE_ID = process.env.BC_PHONE_NUMBER_ID;
const TOKEN = process.env.BC_TOKEN;

export async function sendOrderShipped({ to, name, orderNo, courier, imageUrl }) {
  const body = {
    messaging_product: 'whatsapp',
    to,
    type: 'template',
    template: {
      name: 'order_shipped',
      language: { code: 'en' },
      components: [
        { type: 'header', parameters: [{ type: 'image', image: { link: imageUrl } }] },
        { type: 'body', parameters: [name, `#${orderNo}`, courier].map((text) => ({ type: 'text', text })) },
        { type: 'button', sub_type: 'url', index: '0', parameters: [{ type: 'text', text: String(orderNo) }] },
      ],
    },
  };
  const res = await fetch(`${API_URL}/${API_VERSION}/${PHONE_ID}/messages`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  const data = await res.json().catch(() => ({}));
  if (!res.ok) {
    const e = data.error || {};
    throw Object.assign(new Error(`WhatsApp send failed: ${res.status} code ${e.code}: ${e.message}`), { status: res.status, code: e.code });
  }
  return data.messages[0].id; // save this with the order
}

Python में requests library के साथ:

# send_template.py
import os
import requests

API_URL = os.environ["BC_API_URL"]          # e.g. https://app.yourpanel.in/api/meta
API_VERSION = os.environ["BC_API_VERSION"]  # e.g. v21.0
PHONE_ID = os.environ["BC_PHONE_NUMBER_ID"]
TOKEN = os.environ["BC_TOKEN"]

def send_order_shipped(to, name, order_no, courier, image_url):
    body = {
        "messaging_product": "whatsapp",
        "to": to,
        "type": "template",
        "template": {
            "name": "order_shipped",
            "language": {"code": "en"},
            "components": [
                {"type": "header", "parameters": [{"type": "image", "image": {"link": image_url}}]},
                {"type": "body", "parameters": [{"type": "text", "text": t} for t in (name, f"#{order_no}", courier)]},
                {"type": "button", "sub_type": "url", "index": "0", "parameters": [{"type": "text", "text": str(order_no)}]},
            ],
        },
    }
    r = requests.post(
        f"{API_URL}/{API_VERSION}/{PHONE_ID}/messages",
        headers={"Authorization": f"Bearer {TOKEN}"},
        json=body,
        timeout=20,
    )
    data = r.json() if r.content else {}
    if not r.ok:
        err = data.get("error", {})
        raise RuntimeError(f"WhatsApp send failed: {r.status_code} code {err.get('code')}: {err.get('message')}")
    return data["messages"][0]["id"]

Step 5: errors और retries सँभालें

Errors Meta वाले ढाँचे {"error": {"message", "type", "code"}} में लौटते हैं, चाहे वे Broadchat की जाँच से आएँ या Meta से, इसलिए एक ही handler दोनों सँभाल लेता है:

Retry सिर्फ़ network errors और 5xx responses पर करें, exponential back-off के साथ, और कभी तंग loop में नहीं: कोई idempotency key नहीं है, इसलिए timeout के बाद आँख मूँदकर किया retry वही मैसेज दो बार भेज सकता है। Retry से पहले अपने logs में सेव की हुई message id देख लें। सभी API routes पर प्रति IP address प्रति मिनट 300 requests की साझा limit है; bulk sends को एक साथ चलाने की जगह queue में डालें। Meta के codes का विस्तार WhatsApp API error codes लेख में है।

Step 6: webhook से delivery ट्रैक करें

200 response का मतलब है कि Meta ने मैसेज स्वीकार किया, यह नहीं कि वह deliver हुआ। Statuses पाने के लिए:

1. Channels खोलें, अपना चैनल खोलें और Webhooks टैब पर जाएँ।
2. Add Webhook दबाएँ, एक Title और HTTPS URL डालें, और ज़रूरी Channel Events चुनें: Sent, Delivered, Read, Failed और जवाबों के लिए Incoming Messages।
3. Statuses Meta के webhook format में आते हैं, हर POST में एक change, और X-Webhook-Event जैसे headers के साथ। statuses[0].id को अपनी सेव की हुई message id से मिलाएँ।

Webhooks एक बार, 5 सेकंड के timeout के साथ भेजे जाते हैं और retry नहीं होते, इसलिए तुरंत 2xx से जवाब दें और प्रोसेसिंग बाद में करें। URL path ऐसा रखें जिसे अंदाज़ा लगाना मुश्किल हो, क्योंकि अभी requests में कोई signature नहीं आता जिसे आप verify कर सकें। हर event और payload WhatsApp webhooks integration पेज पर है; webhook का मतलब glossary में देखें।

आसान रास्ता: API campaign

अगर आपको सिर्फ़ "इस नंबर पर यह मंज़ूर template भेजो" और पैनल में रिपोर्ट चाहिए, तो API campaign की body ज़्यादा आसान है। इसे CRM → Bulk Campaign → Create New Campaign → API Campaign में बनाएँ (चैनल, नाम और Token Validity चुनें); रिपोर्ट पेज पर Endpoint, एक Campaign Token (bcc_ से शुरू, एक बार दिखता है) और Sample Request दिखते हैं:

curl -X POST "https://app.yourpanel.in/api/v1/campaigns/<CAMPAIGN_ID>/send" \
  -H "Authorization: Bearer $BC_CAMPAIGN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "919876543210",
    "name": "Priya Sharma",
    "template": "order_shipped",
    "language": "en",
    "variables": ["Priya", "#48213", "Delhivery"],
    "headerMedia": "https://cdn.rangolihome.in/products/cushion-48213.jpg",
    "buttons": ["48213"]
  }'

सफल होने पर {"success": true, "data": {"recipientId": "…", "status": "SENT", "messageId": "…"}} लौटता है। असफल भेजने पर, चाहे wallet balance कम हो या Meta reject करे, HTTP 502 के साथ success: false और message में कारण आता है, इसलिए retry से पहले message पढ़ें। Contact API को source मानकर बनता या अपडेट होता है, भेजा गया मैसेज campaign रिपोर्ट में दिखता है, और हर campaign प्रति मिनट 120 calls तक लेता है।

ख़र्च और नियम

Template sends Meta तक पहुँचने से पहले चैनल के wallet से कटते हैं और Meta के reject करने पर अपने आप वापस आ जाते हैं। Meta हर delivered मैसेज पर category के हिसाब से पैसे लेता है: India के लिए ₹0.115 per utility message और ₹0.8631 per marketing message (Meta rate card effective 1 Oct 2026, excl. GST); देखें WhatsApp API pricing। API आपके लिए सहमति की जाँच नहीं करती: सिर्फ़ उन्हें भेजें जिन्होंने opt-in किया है, और opt-out अपने system में दर्ज करें। प्लेटफ़ॉर्म की बुनियादी बातों के लिए WhatsApp Business API क्या है पढ़ें; जो SaaS कंपनियाँ अपने product के अंदर अपने ब्रांड के साथ WhatsApp sending देना चाहती हैं, वे white-label प्लेटफ़ॉर्म से कर सकती हैं।