WhatsApp ওয়েবহুক স্ট্যাটাস: sent, delivered, read এবং failed
স্ট্যাটাস ওয়েবহুক জানায় WhatsApp Cloud API-এর মাধ্যমে কোনো ব্যবসার পাঠানো মেসেজের কী হলো। এগুলো messages ফিল্ডে আসে, messages array-র বদলে একটি statuses array সহ: sent (এক টিক), delivered (দুই টিক), read (দুই নীল টিক), ভয়েস মেসেজের জন্য played, এবং errors array সহ failed। statuses[].id-কে আপনার send রিকোয়েস্টের ফেরত দেওয়া wamid-এর সঙ্গে মেলান।
easyCoexistence আপনার ইতিমধ্যে ব্যবহৃত WhatsApp Business অ্যাপের নম্বরটিকে Coexistence-এর মাধ্যমে Meta-র Cloud API-র সঙ্গে সংযুক্ত করে।
Meta যে স্ট্যাটাস মান পাঠায়: sent, delivered, read, played (ভয়েস মেসেজের প্রথমবার চালানো) এবং failed।
একটি পাঠানো মেসেজ থেকে আলাদা স্ট্যাটাস ওয়েবহুক আসতে পারে: sent, delivered এবং read।
এই Graph API ভার্সন থেকে conversation অবজেক্ট বাদ দেওয়া হয়, তবে free entry point window-র মেসেজ ছাড়া।
অতীতের ওয়েবহুক ডেটা আনার জন্য কোনো API নেই; Meta চায় পেলোড আসার সঙ্গে সঙ্গেই আপনি সেগুলো ক্যাপচার ও সংরক্ষণ করুন।
ফরওয়ার্ড করা স্ট্যাটাসে X-EC-Event হেডার থাকে: স্ট্যাটাস messages ইভেন্টের ভেতরে value.statuses-এর অধীনে যায়।
WhatsApp স্ট্যাটাস ওয়েবহুক কোথায় আসে?
যে messages ফিল্ডে গ্রাহকের পাঠানো মেসেজ আসে, সেই একই ফিল্ডে, একই object, entry ও changes কাঠামোর ভেতরে। পার্থক্য value-এর ভেতরে: গ্রাহকের মেসেজে থাকে messages array, স্ট্যাটাসে থাকে statuses array। যে হ্যান্ডলার শুধু value.messages পড়ে, সে কোনো ত্রুটি ছাড়াই সব স্ট্যাটাস বাদ দিয়ে দেয়। metadata.phone_number_id বলে দেয় আপনার কোন নম্বর থেকে মেসেজটি পাঠানো হয়েছে, এবং সঙ্গে আসে একটি contacts array, যাতে গ্রাহকের প্রোফাইল নাম, wa_id ও BSUID থাকে। ব্যতিক্রম: ব্যর্থ স্ট্যাটাস এবং গ্রুপ মেসেজের sent স্ট্যাটাস। নিচে Meta-র একটি উদাহরণ, যেখানে একটি মার্কেটিং টেমপ্লেট Meta-র সার্ভার ছেড়ে গেছে:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [
{
"profile": {
"name": "Pablo M."
},
"wa_id": "16505551234",
"user_id": "US.13491208655302741918"
}
],
"statuses": [
{
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
"status": "sent",
"timestamp": "1750030073",
"recipient_id": "16505551234",
"recipient_user_id": "US.13491208655302741918",
"conversation": {
"id": "72b14d6bd5407799e66f64d1b338e567",
"expiration_timestamp": "1750116480",
"origin": {
"type": "marketing"
}
},
"pricing": {
"billable": true,
"pricing_model": "PMP",
"type": "regular",
"category": "marketing"
}
}
]
},
"field": "messages"
}
]
}
]
}প্রতিটি স্ট্যাটাস মান কী বোঝায়?
প্রতিটি মান WhatsApp-এ গ্রাহক যে চিহ্ন দেখেন তার সঙ্গে মেলে। একটি স্ট্যাটাস তখনই read গণ্য হয় যখন মেসেজটি delivered হয়ে গেছে। আর গ্রাহক যখন চ্যাট খোলা অবস্থায় মেসেজ পান, তখন Meta অভ্যন্তরীণ অপটিমাইজেশন হিসেবে আগে delivered ওয়েবহুক না পাঠিয়ে সরাসরি read পাঠায়। তাই একটি ট্র্যাকার delivered না এলেও read গ্রহণ করবে, এবং স্ট্যাটাসগুলোকে একটি নির্দিষ্ট ক্রমে একের পর এক আশা না করে তাদের অগ্রাধিকার অনুযায়ী বিবেচনা করবে।
একটি স্ট্যাটাস অবজেক্টে কোন ফিল্ড থাকে?
মেসেজের চেয়ে কম, এবং অনেকগুলো শর্তসাপেক্ষ। Meta-র রেফারেন্সে দেখানো আছে কখন কোনটি থাকে:
- id: আপনার পাঠানো মেসেজের wamid, যা দিয়ে মেলাতে হয়।
- status ও timestamp: মান এবং ওয়েবহুক চালু হওয়ার Unix সময়, স্ট্রিং হিসেবে।
recipient_id: ফোন নম্বর বা গ্রুপ আইডি; BSUID-তে পাঠালে এবং নম্বর না থাকলে বাদ যায়।recipient_user_id: গ্রাহকের BSUID; ফোন নম্বরে পাঠালে ব্যর্থ স্ট্যাটাসে বাদ যায়।recipient_typeওrecipient_participant_id: শুধু গ্রুপে পাঠানো মেসেজের জন্য।biz_opaque_callback_data: শুধু পাঠানোর রিকোয়েস্টে আপনি সেট করলে।- pricing: শুধু sent-এ এবং delivered বা read-এর একটিতে। errors: শুধু failed-এ।
একটি স্ট্যাটাসকে আপনার পাঠানো মেসেজের সঙ্গে কীভাবে মেলাবেন?
wamid দিয়ে। send রিকোয়েস্ট messages[0].id ফেরত দেয়, এবং ওই মেসেজের প্রতিটি স্ট্যাটাসে statuses[].id-তে একই মান থাকে। পাঠানোর সময় এটি আপনার নিজের রেকর্ডের পাশে সংরক্ষণ করুন, তারপর স্ট্যাটাস এলে রেকর্ড আপডেট করুন, এবং সর্বোচ্চ পৌঁছানো স্ট্যাটাসটি রাখুন, যাতে দেরিতে আসা delivered স্ট্যাটাস read-কে না সরিয়ে দেয়। যে wamid আপনার জানা নেই, সেটি নম্বরের অন্য কিছু, যেমন অটোমেশন, পাঠিয়েছে; সেটি উপেক্ষা বা লগ করা যায়।
// statuses.mjs: apply Meta status webhooks to the messages your system sent
const RANK = { sent: 1, delivered: 2, read: 3, played: 4 };
// value: change.value of a "messages" webhook; sends: Map of wamid -> your record
export function applyStatuses(value, sends) {
for (const s of value.statuses ?? []) {
const rec = sends.get(s.id); // the wamid your send request returned
if (!rec) continue; // sent by something else, such as an automation
if (s.status === "failed") {
rec.status = "failed";
rec.error = s.errors?.[0]?.code; // for example 131049, 131050 or 131026
} else if ((RANK[s.status] ?? 0) > (RANK[rec.status] ?? 0)) {
rec.status = s.status; // read arriving before delivered is fine; never step back
}
rec.updatedAt = Math.max(rec.updatedAt ?? 0, Number(s.timestamp));
}
}Coexistence নম্বরে কী বদলায়?
স্ট্যাটাস বর্ণনা করে API-র মাধ্যমে যা পাঠানো হয়েছে: আপনার অটোমেশনের উত্তর, আপনার AI যে মেসেজ MCP connector দিয়ে পাঠিয়েছে, এবং আপনার নিজের কোডের পাঠানো যেকোনো কিছু। WhatsApp Business অ্যাপে মালিক যা টাইপ করেন, তা সফটওয়্যারে আলাদাভাবে পৌঁছায়, smb_message_echoes হিসেবে, যা Meta-র ডকুমেন্টেশনে অ্যাপ থেকে পাঠানো মেসেজের প্রতিফলন। একবারের ইতিহাস ইমপোর্টে আসা মেসেজগুলোর নিজস্ব স্ট্যাটাস থাকে history ওয়েবহুকের ভেতরে, যার মানগুলো হলো delivered, read, played, pending ও error।
স্ট্যাটাস নম্বরের messages ফিল্ড যেখানে যায় সেখানেই যায়। সরাসরি ডেস্টিনেশনে Meta সেগুলো সরাসরি আপনার এন্ডপয়েন্টে পাঠায়, কারণ messages এমন একটি ফিল্ড যা Meta ডেস্টিনেশনে বদলে দেওয়া যায়। অটোমেশন চালু থাকলে এবং Forward URL সেট করা থাকলে সেগুলো ওই URL-এ messages ইভেন্ট হিসেবে পৌঁছায়।
আপনার AI বা অটোমেশন কীভাবে জানবে মেসেজ পৌঁছেছে?
পাঠানোর মাধ্যমে নয়, আপনার ডেস্টিনেশনের মাধ্যমে। যখন আপনার AI send_template বা send_message কল করে, টুলের ফলাফলে থাকে wamid এবং বলা হয় Meta মেসেজটি গ্রহণ করেছে; পৌঁছানো পরে গ্রাহকের ডিভাইসে নিশ্চিত হয় এবং স্ট্যাটাস হিসেবে জানানো হয়। easyCoexistence কোনো স্ট্যাটাস ইতিহাস রাখে না যা কুয়েরি করা যায়, এবং কোনো MCP টুল স্ট্যাটাস পড়ে না। তাই পৌঁছানোর নিশ্চিতকরণ দরকার এমন এজেন্টকে আপনার সিস্টেমের মাধ্যমে পাঠাতে হবে, অথবা Forward URL যেসব স্ট্যাটাস পায় সেগুলো পড়তে হবে।
অটোমেশনের ক্ষেত্রেও একই কথা: Runs ট্যাবের একটি রান তখনই উত্তরের ধাপ সম্পন্ন দেখায় যখন Meta মেসেজ গ্রহণ করে, এবং পরে জানানো ব্যর্থতা শুধু আপনার ডেস্টিনেশনে failed স্ট্যাটাস হিসেবে আসে।
সাধারণ ভুলগুলো
- আলাদা একটি statuses ফিল্ড খোঁজা। স্ট্যাটাস আসে messages-এ, তাই যে হ্যান্ডলার শুধু value.messages পড়ে, সে কোনো ত্রুটি ছাড়াই সেগুলো হারায়।
- read-এর আগে delivered দাবি করা। মেসেজ আসার মুহূর্তেই পড়া হলে Meta delivered ওয়েবহুক বাদ দেয়।
- send-এর উত্তরকে পৌঁছানো ধরা। wamid মানে Meta রিকোয়েস্ট গ্রহণ করেছে; ব্যর্থতা কয়েক মিনিট পরে failed স্ট্যাটাস হিসেবে আসতে পারে।
- শুধু recipient_id দিয়ে গ্রাহক চিহ্নিত করা। BSUID-তে পাঠালে এবং ফোন নম্বর না থাকলে এটি বাদ যায়; BSUID থাকে recipient_user_id-তে।
আপনার অটোমেশন, AI বা কোড যা পাঠায় তার স্ট্যাটাস আপনার সার্ভারে যায়: সরাসরি ডেস্টিনেশনে Meta থেকে, অথবা অটোমেশন চালু থাকলে আপনার Forward URL-এ পাঠানো হয় এবং X-EC-Signature দিয়ে সাইন করা হয়; ডিফল্টভাবে এগুলো সংরক্ষণ করা হয় না। প্রতি সংযুক্ত নম্বরে প্রতি মাসে US$ 9 থেকে কমে US$ 0.75, নম্বর যত বাড়ে তত কমে, প্রথম 3 দিন ফ্রি ট্রায়াল।
প্রায়শই জিজ্ঞাসিত প্রশ্ন
স্ট্যাটাস ওয়েবহুকে মেসেজের টেক্সট থাকে কি?
না। একটি স্ট্যাটাসে থাকে wamid, স্ট্যাটাস, প্রাপক, টাইমস্ট্যাম্প এবং প্রযোজ্য ক্ষেত্রে pricing ও errors। যা আপনি পাঠিয়েছেন তার নিজের কপি wamid দিয়ে সংরক্ষণ করুন, যদি স্ট্যাটাসের পাশে সেটি দেখাতে চান।
পরে Meta থেকে অতীতের স্ট্যাটাস আনা যাবে কি?
না। Meta-র ওয়েবহুক গাইড বলে ঐতিহাসিক ওয়েবহুক ডেটা আনার কোনো API নেই। তাই আপনার এন্ডপয়েন্ট যে স্ট্যাটাস ক্যাপচার করেনি, তা Meta পুনরায় চেষ্টা বন্ধ করলে, সর্বোচ্চ 7 দিন পরে, হারিয়ে যায়।
biz_opaque_callback_data কীসের জন্য?
এটি পাঠানোর সময় আপনার সেট করা একটি স্ট্রিং, যেমন আপনার নিজের অর্ডার বা টিকিট আইডি। Meta সেটি ওই মেসেজের statuses-এ ফেরত দেয়, তাই wamid আগে খোঁজা ছাড়াই স্ট্যাটাসটি আপনার রেকর্ডের সঙ্গে মেলানো যায়।
স্ট্যাটাস ওয়েবহুকের উত্তরে কি 200 দিতে হবে?
হ্যাঁ, যেকোনো ওয়েবহুক POST-এর মতো। Meta অন্য যেকোনো উত্তরকে ব্যর্থ ডেলিভারি ধরে আবার চেষ্টা করে, আর এভাবেই একই স্ট্যাটাস দুইবার আসার একটি কারণ তৈরি হয়।
আরও পড়ুন
শুরু করতে প্রস্তুত?
মাস নয়, কয়েক মিনিটেই WhatsApp Coexistence সেট আপ করুন। ফোনে অ্যাপটি কাজ করতে থাকে।
ফ্রি ট্রায়াল শুরু করুনযাচাই করা হয়েছে