WhatsApp Messages API - Session Messages भेजें

Overview

WhatsApp Messages API ऐसे ग्राहक को free-form WhatsApp संदेश (text, images, videos, audio और documents) भेजता है जिसने पिछले 24 घंटों में आपको लिखा है। यह Inbox से जवाब देने का API version है, और संदेश किसी भी agent reply की तरह बातचीत में सेव होता है।

24 घंटे की window के बाहर WhatsApp केवल approved templates स्वीकार करता है। उनके लिए WhatsApp Templates API का उपयोग करें।

ध्यान दें: Send Messages API WhatsApp सहित हर चैनल के लिए यही काम करता है, एक ही request ढाँचे और built-in सुरक्षित retries के साथ। अगर आप केवल WhatsApp और phone numbers के साथ काम करते हैं, तो इस पेज के endpoint का उपयोग करें।

ज़रूरी शर्तें

• API access वाले plan (Pro या उससे ऊपर) पर एक API key। ChatMaxima API देखें।
• Cloud API से जुड़ा एक WhatsApp account। WhatsApp channel setup देखें।
• एक खुली बातचीत। ग्राहक का आपको भेजा गया आखिरी संदेश 24 घंटे से कम पुराना होना चाहिए।

Session message भेजें

Text

curl -X POST https://chatmaxima.com/api/v2/whatsapp/messages/send/ \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "a1b2c3d4e5f6",
    "mobile_no": "+15550001111",
    "reference_id": "ticket-2042",
    "message": "Thanks Jane, your refund has been approved."
  }'

Image, video, audio या document

message को string के बजाय object के रूप में भेजें:

{
  "account_id": "a1b2c3d4e5f6",
  "mobile_no": "+15550001111",
  "reference_id": "invoice-1001",
  "message": {
    "type": "document",
    "media_url": "https://cdn.example.com/invoice-1001.pdf",
    "file_name": "invoice-1001.pdf",
    "caption": "Your invoice"
  }
}

Request fields

Field	Type	ज़रूरी	विवरण
mobile_no	string	हाँ	Country code के साथ ग्राहक का number।
account_id	string	अगर आपके पास कई numbers हैं	जिस WhatsApp account से भेजना है, Channel Accounts से।
reference_id	string	नहीं	आपका अपना id। अगर आप इस संदेश के लिए webhooks चाहते हैं तो ज़रूरी।
message	string या object	हाँ	String होने पर text भेजा जाता है। Object होने पर दिया गया type भेजा जाता है।
message.type	string	Object रूप में	text, image, video, audio या document।
message.text या message.caption	string	text के लिए	Text, या media के लिए caption।
message.media_url	string	Media के लिए	फ़ाइल का public https URL।
message.file_name	string	नहीं	Documents के लिए दिखाया जाने वाला फ़ाइल नाम।

Response

{
  "status": "success",
  "code": 201,
  "message": "Message sent",
  "data": {
    "message_id": "wamid.XXXXXXXX",
    "mobile_no": "15550001111",
    "account_id": "a1b2c3d4e5f6",
    "reference_id": "ticket-2042",
    "status": "sent",
    "created_datetime": "2026-11-03 10:05:00"
  }
}

ध्यान दें: Delivery, read और failure webhooks केवल उन session messages के लिए भेजे जाते हैं जिनमें reference_id शामिल हो। Template sends हमेशा इन्हें trigger करते हैं।

24 घंटे की window

ChatMaxima भेजने से पहले window जाँचता है। अगर ग्राहक ने आपको कभी नहीं लिखा, या उसका आखिरी संदेश 24 घंटे से पुराना है, तो request 422 WINDOW_CLOSED के साथ विफल होती है:

{
  "error": {
    "code": "WINDOW_CLOSED",
    "message": "The 24-hour customer service window is closed (last inbound message was 31.4 hours ago). Send an approved template to reopen the conversation.",
    "details": { "window_open": false, "hours_since_last_inbound": 31.4 }
  }
}

इसके बजाय WhatsApp Templates API से एक approved template भेजें। जब ग्राहक जवाब देता है, तो window फिर से 24 घंटे के लिए खुल जाती है।

संदेश का status जाँचें

अपने workspace के किसी भी WhatsApp संदेश को उसके wamid से देखें, चाहे वह API, bot या agent ने भेजा हो। Id को URL-encode करें।

curl https://chatmaxima.com/api/v2/whatsapp/messages/wamid.XXXXXXXX/status/ \
  -H "Authorization: YOUR_API_KEY"

{
  "status": "success",
  "code": 200,
  "data": {
    "message_id": "wamid.XXXXXXXX",
    "status": "delivered",
    "error": null,
    "created_datetime": "2026-11-03 10:05:00",
    "updated_datetime": "2026-11-03 10:05:04"
  }
}

Status	अर्थ
sent	WhatsApp ने संदेश स्वीकार कर लिया।
delivered	संदेश ग्राहक के phone तक पहुँच गया।
read	ग्राहक ने उसे खोला। चलाए गए voice notes भी read माने जाते हैं।
failed	WhatsApp उसे deliver नहीं कर सका। error में Meta की रिपोर्ट होती है।

Status केवल आगे बढ़ता है। देर से आया delivered update कभी read को overwrite नहीं करता। समय UTC में होते हैं।

Errors

HTTP	Code	कब होती है
422	MISSING_MOBILE_NO	mobile_no गायब है।
422	INVALID_MOBILE_NO	सफ़ाई के बाद number 7 से 15 अंकों का नहीं है।
422	UNSUPPORTED_MESSAGE_TYPE	message.type समर्थित types में से नहीं है।
422	MISSING_MESSAGE	Text खाली है।
422	MISSING_MEDIA_URL	Media type बिना media_url के भेजा गया।
422	INVALID_MEDIA_URL	media_url एक https URL नहीं है।
403	PLAN_EXPIRED	आपका plan समाप्त हो चुका है।
403	MESSAGE_LIMIT_REACHED	आपका मासिक message allowance खत्म हो चुका है।
422	ACCOUNT_RESOLUTION_FAILED	account_id आपके WhatsApp accounts में से नहीं है, कोई account जुड़ा नहीं है, या आपके पास कई accounts हैं और आपने कोई नहीं भेजा।
422	WINDOW_CLOSED	24 घंटे की window बंद है या कभी खुली ही नहीं।
422	WHATSAPP_SEND_REJECTED	Meta ने संदेश अस्वीकार कर दिया। details में Meta की error होती है।
502	SEND_UNCONFIRMED	ChatMaxima send की पुष्टि नहीं कर सका। Retry करने से पहले status जाँचें।
404	NOT_FOUND	Status lookup, आपके workspace में उस wamid का कोई संदेश नहीं है।

Authentication, plan और rate-limit errors API overview पर सूचीबद्ध हैं।

Best Practices

• हमेशा reference_id भेजें अगर आप delivery tracking के लिए webhooks पर निर्भर हैं।
• पहले अपने logic में window जाँचें अगर आप जानते हैं कि ग्राहक ने आखिरी बार कब लिखा, ताकि विफल calls से बचा जा सके।
• ज़्यादा volume के लिए status endpoint पर polling के बजाय webhooks चुनें।

अगले कदम

• WhatsApp Templates API →
• WhatsApp Webhooks →
• Send Messages API →