Pagkonekta gamit ang Meta Graph API
May dalawang paraan para magpadala ng mga mensahe sa WhatsApp sa pamamagitan ng WizMessage. Ang WizMessage API ang dapat piliin kung nagsisimula ka sa wala — nagbibigay ito sa iyo ng mga pinangalanang template variable, isang mapping UI, at isang reference field kung saan puwede mong i-key ang sarili mong mga record.
Idinodokumento ng page na ito ang isa pa. Sinasalamin nito ang WhatsApp Cloud API ng Meta nang ganoon kalapit kaya ang code na naisulat na para sa Meta ay gumagana rito pagkatapos baguhin ang dalawang bagay: ang base URL at ang token. Parehong mga path, parehong mga request body, parehong mga response body, parehong error envelope. Kung mayroon kang umiiral na integration, isang library, o isang developer na pamilyar na sa Cloud API, ito ang mas maikling ruta.
Hindi lang ito isang send surface. Kasabay ng pagmemensahe, dala nito ang mga account-management endpoint — paggawa at pagbura ng mga template, pagbasa at muling pagsulat ng business profile, mga QR code, mga setting ng commerce, ang block list, mga setting ng telepono at mga flow — lahat sa sariling mga path ng Meta. Ang Pamamahala sa account ang katalogo, at ang Kung ano ang hindi available dito ang kapantay na mahalagang kalahati.
Parehong gumagamit ang dalawang surface ng parehong mga API key, parehong mga pahintulot at parehong mga rate limit. Walang deprecated — pumili bawat integration, at puwede mong gamitin ang dalawa nang magkasabay.
Alin ang gusto mo
Ang mga pangunahing kaalaman
Base URL, at ang bersyon sa path
https://wizmessage.com/v26.0/{phone-number-id}/messages
Totoo at kinakailangan ang segment ng bersyon, ngunit walang binabago ang halaga nito. Tinutugma namin ito bilang v{major}.{minor} at pagkatapos ay binabalewala ito — ang platform ang nagpapasya kung aling bersyon ng Graph ang kakausapin nito sa upstream.
Dalawang kahihinatnan na dapat malaman:
- Patuloy na gagana ang pag-pin sa lumang bersyon. Kapag iniretiro ng Meta ang bersyong naka-hardcode sa iyong code, magpapatuloy pa rin ang mga tawag dito. Walang kailangang i-iskedyul.
- Tinatanggihan ang
v26nang mag-isa. Hindi opsyonal ang minor number. Ayos lang angv26.0, 404 angv26.
Dapat na ang {phone-number-id} ay ang WhatsApp number sa likod ng API key na ginagamit mo. Tatanggihan ang anupaman bukod doon — tingnan ang Kapag hindi sa iyo ang isang id.
Pag-authenticate
Ipadala ang iyong API key bilang isang bearer token, eksakto kung paano ka magpapadala ng access token sa Meta.
| Header | Halaga |
|---|---|
Authorization | Bearer pk_live_… — ang iyong buong API key, hindi ang prefix na ipinapakita sa dashboard. |
Tinatanggap din dito ang X-API-Key, kaya ang isang key na gumagana na sa WizMessage API ay hindi nangangailangan ng pagbabago sa header. Bearer ang anyong mas mainam: ito ang ipinapadala ng isang hindi binagong Meta SDK, na siyang layunin ng surface na ito.
Paalala: Dapat naka-off ang "Require signature" sa key. Hindi ito isang opsyon lang dito. Ang isang key kung saan naka-enable ito ay hindi makakapag-save ng webhook ng Meta Graph — tatanggi ang dashboard na may "Signed-request enforcement is not compatible with the Graph format — disable it on this key first" — at ang bawat unsigned na tawag na gagawin nito sa surface na ito ay tatanggihan bilang
code 190na may401. Hindi kayang gumawa ng isang karaniwang Cloud API client ng aming request signature, kaya sadya talagang hindi puwedeng magkasabay ang dalawa.
Ang iyong subscription
Kinakailangan ng API module ang isang aktibong subscription sa Wiz Bot o Wiz Pro. Nalalapat ito sa parehong surface — ang WizMessage API at ang isang ito — at sinusuri ito sa bawat tawag, hindi lamang kapag ginawa ang key.
Kung mag-lapse ang subscription, hindi hihinto ang API sa mismong sandaling iyon. Ang unang tawag pagkatapos ng pagka-lapse ay nagsisimula ng pitong araw na palugit at pinapapasok, at ang bawat tugon sa panahong iyon ay may dalang header:
| Header | Halaga |
|---|---|
X-Subscription-Warning | Subscription inactive. API access ends in 5 day(s). |
Pagkatapos ng palugit, tatanggihan ang mga tawag gamit ang Graph code 10 sa 403:
{
"error": {
"message": "(#10) Access denied. The API module requires an active Wiz Bot or Wiz Pro subscription. Renew at /subscriptions to restore access.",
"type": "OAuthException",
"code": 10,
"fbtrace_id": "AKnBaXsYl7FlmMVw3ql5Ywo"
}
}
Tatlong detalye na nagpapasya kung mapapansin mo ito sa tamang oras:
- Magsisimula ang oras sa iyong unang tawag, hindi sa petsa ng pagsingil. Ang isang key na nakatiwangwang nang dalawang linggo pagkatapos ng pagka-lapse ay makakakuha pa rin ng buong pitong araw nito, simula sa susunod nitong pagtawag.
- Ang palugit ay bawat API key, hindi bawat account. Ang bawat key ay nagpapatakbo ng sarili nitong orasan mula sa sarili nitong unang tawag, kaya ang isang key na sinusubukan mo at ang isang key na nagpapatakbo sa production ay mag-e-expire sa magkaibang araw. Suriin ang header sa key na mahalaga.
- Darating ang pagtanggi nang walang babala sa kahilingang nag-trigger nito. Ang
X-Subscription-Warningang tanging paunang abiso na mayroon — i-log ito, kundi ang una mong malalaman ay isang403.
Paalala: Tumatagal nang ilang minuto bago magkabisa ang pag-renew, hindi ilang segundo. Naka-cache ang sagot sa entitlement sa loob ng limang minuto at ang status ng subscription sa likod nito sa isa pang limang minuto, kaya ang isang pag-renew na ginawa habang pumapalya ang isang integrasyon ay hindi agad magiging maayos sa pinakaunang retry. Maghintay nang ilang minuto bago magpasyang hindi ito gumana.
Pagpapadala ng mensahe
POST /{version}/{phone-number-id}/messages, gamit ang body ng Meta. Hindi namin ito bini-validate maliban sa pagsusuri kung ito ay isang mensahe sa WhatsApp — ang Meta ang awtoridad sa kung ano ang hitsura ng isang wastong mensahe, at ang mga error nito ay mas maayos kaysa sa anupaman na maaari naming gawin.
POST https://wizmessage.com/v26.0/106540352242922/messages
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "919876543210",
"type": "text",
"text": { "preview_url": false, "body": "Your order has shipped." }
}
Paalala: Tumatanggap ang
tong mga digit lamang dito —919876543210, walang+. Ito ang format ng Meta, at ito ang nag-iisang pinakakaraniwang bagay na nagkakamali kapag lumilipat sa pagitan ng dalawang surface: kinakailangan ng WizMessage API ang+E.164at tinatanggihan ang anupaman bukod doon, habang ipinapasa naman nito ang iyong halaga nang diretso sa Meta. Ang nag-iisang eksepsiyon ay angPOST /messages/contacts, na tumatanggap ng alinmang anyo upang ang isang body ng Graph ay mailipat nang buo at walang pagbabago.
Ang pagpapadala ng template ay nasa anyo rin ng Meta — mga positional component, hindi mga pinangalanang variable. Walang mapping layer sa surface na ito, na siyang kapalit na tinatanggap mo para sa compatibility.
{
"messaging_product": "whatsapp",
"to": "919876543210",
"type": "template",
"template": {
"name": "payment_failed_alert",
"language": { "code": "en" },
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "Priya Sharma" },
{ "type": "text", "text": "12 Aug 2026" },
{ "type": "text", "text": "Wiz Pro" }
]
}
]
}
}
Pagpapadala ng contact card
Ang type: "contacts" ay isang vCard — isang pangalan, at anupaman na ilalakip mo. Matagal na itong gumagana sa surface na ito at gumagana pa rin, nang hindi binabago ang body ng Meta.
POST https://wizmessage.com/v26.0/106540352242922/messages
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "919876543210",
"type": "contacts",
"contacts": [
{
"name": {
"formatted_name": "Priya Sharma",
"first_name": "Priya",
"last_name": "Sharma"
},
"phones": [
{ "phone": "+911122334455", "type": "WORK", "wa_id": "911122334455" }
],
"emails": [
{ "email": "[email protected]", "type": "WORK" }
],
"org": { "company": "Acme Retail", "department": "Support", "title": "Account Manager" }
}
]
}
Ang name.formatted_name ang tanging field na kinakailangan ng WhatsApp. Ang phones[].wa_id ang sulit pa ring idagdag: kapag mayroon nito, ang card ay may dalang button na Message na nagbubukas ng chat sa taong iyon, kung wala nito, mase-save lamang ang card.
Nagpo-post din ang eksaktong body na iyon sa POST /messages/contacts sa WizMessage API — mga envelope key, to na mga digit lamang, at lahat. Ito ang nag-iisang endpoint sa surface na iyon na tumatanggap sa anyong ito, at umiiral ito dahil ang dalawang bagay na hindi maibibigay ng path na ito ay kapaki-pakinabang: ang pagpapadala rito ay hindi nakatala sa ilalim ng isang message_id, kaya walang status na hahanapin at walang message.sent webhook na itutugma, at bahagya lamang sinusuri ang body bago ito makarating sa Meta. Ang pagpapalit ng URL ang kabuuan ng paglipat.
Paalala: Ang pagpapadala ng ilang card sa iisang mensahe ay ang
contactsarray ng Meta, at tumatanggap ang Meta ng hanggang 257 sa mga ito. Nililimitahan ito ng endpoint ng WizMessage sa sampu — kaya ang maramihang pagpapadala ng card na gumagana rito ay isa sa iilang body na hindi maililipat nang walang pagbabago.
Pagmamarka sa mensahe bilang nabasa
Ang mga read receipt at typing indicator ay nagpo-post sa parehong endpoint, na may body na walang to o type. Umaasa ang markAsRead() ng bawat Cloud API SDK sa paggana nito, kaya sinusuportahan ito nang eksakto kung paano ito tinukoy ng Meta.
POST https://wizmessage.com/v26.0/106540352242922/messages
{
"messaging_product": "whatsapp",
"status": "read",
"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…"
}
Ang tugon ay {"success": true} — hindi ang send envelope sa ibaba. Mag-branch batay sa kung aling tawag ang ginawa mo sa halip na subukang basahin ang messages[0].id mula sa bawat tugon.
Ang ibinabalik
Ang tugon ng Meta, nang hindi binago:
{
"messaging_product": "whatsapp",
"contacts": [{ "input": "919876543210", "wa_id": "919876543210" }],
"messages": [{ "id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…" }]
}
Ang wamid na iyon ang tanging hawak mo sa mensahe. Sadya talagang walang reference field at walang status-lookup endpoint ang surface na ito — pareho itong mga karagdagan ng WizMessage na wala sa API ng Meta, kaya ang pagsasama sa mga ito ay sisira sa compatibility kung bakit umiiral ang surface na ito.
Upang masubaybayan ang kahihinatnan ng isang mensahe, itugma ang wamid sa mga delivery status na dumarating sa iyong webhook. Kung mas gusto mong magkaroon ng sarili mong field na pagbabatayan, para doon ang reference ng WizMessage API.
Mga Error
Bumabalik ang mga error sa envelope ng Meta, hindi kailanman sa amin. Kung saan nanggaling ang error ang nagtatakda kung gaano karami rito ang sa amin.
Mga error na inilalabas namin
code | HTTP | Kailan |
|---|---|---|
190 | 401 | Nawawala, hindi kilala, binawi, sinuspinde o nag-expire na key — o isang unsigned na call sa isang key na nangangailangan ng mga signature. Inilalabas din kapag ang WhatsApp account mismo ay nawalan ng koneksyon sa Meta; tingnan ang tala sa ibaba. |
10 | 403 | Kulang ang key sa permission na kailangan ng call na ito (tingnan ang Mga Permission), o ang nag-lapse na ang subscription ng account lagpas sa grace window nito. |
4 | 429 | Naubos na ang kada minuto o pang-araw-araw na allowance ng key. |
100 | 400 | Malformed na request, isang id sa path na hindi sa iyo, o isang endpoint na hindi sineserbisyuhan ng surface na ito. |
2 | 500 | May nagka-problema sa aming panig. Subukan muli. |
Tala: Dalawang magkaibang bagay ang nagbabalik ng
190, at kailangan ng magkasalungat na solusyon. Kung binabanggit ng mensahe ang key, i-rotate o muling ilagay ang key. Kung mababasa rito ang “the connection to this WhatsApp Business Account needs to be renewed”, maayos ang key at ang account ang nawalan ng link sa Meta — muling ikonekta ito mula sa dashboard. Ang pag-rotate ng gumaganang key bilang tugon sa pangalawa ay mag-aaksaya ng isang hapon at walang babaguhin.
Mga error na inilalabas ng Meta
Ipinapasa nang eksakto kung paano natanggap, kasama ang HTTP status ng Meta. Nananatili ang lahat ng ipinadala ng Meta — error_subcode, error_data.details, at ang sariling fbtrace_id ng Meta:
{
"error": {
"message": "Unsupported post request. Object with ID '106540352242922' does not exist, cannot be loaded due to missing permissions, or does not support this operation.",
"code": 100,
"type": "GraphMethodException",
"error_subcode": 33,
"fbtrace_id": "AKnBaXsYl7FlmMVw3ql5Ywo"
}
}
Tala: Pansinin ang
typesa halimbawang iyon —GraphMethodException, hindiOAuthException. Gumagamit ang Meta ng ilang exception type at hindi namin bina-normalize ang mga ito. Mag-switch batay saerror.code, na isang numero at stable; ituring angtypebilang isang label para sa mga tao.
Kapag ang isang id ay hindi sa iyo
Bawat id sa path — ang phone number id, ang WABA id, isang media id — ay sinusuri laban sa account sa likod ng iyong key bago ang anupaman. Ang mismatch ay nagbabalik ng code 100 na nakasaad sa paraan kung paano inilalarawan ng Meta ang isang object na hindi mo makita:
Unsupported post request. Object with ID '…' does not exist, cannot be loaded due to missing permissions, or does not support this operation.
Ang pananalitang iyon ay sadya sa panig ng Meta at sadyang kinopya rito: ang isang id na umiiral ngunit pag-aari ng iba at ang isang id na hindi umiiral ay dapat na hindi mapag-iba, kundi magiging paraan ang error upang matuklasan ang mga numero ng telepono ng ibang tao.
Media
Apat na endpoint, tumutugma sa Meta.
| Method | Path | Ano ang ginagawa nito |
|---|---|---|
POST | /{version}/{phone-number-id}/media | Mag-upload ng file. Multipart, nagbabalik ng {"id": "…"}. |
GET | /{version}/{media-id} | Metadata object ng Meta para sa file. |
GET | /{version}/{media-id}/download | Ang mga byte. |
DELETE | /{version}/{media-id} | I-delete ito, nagbabalik ng {"success": true}. |
Ang nag-iisang sadyang pagkakaiba
Nagbabalik ang GET /{version}/{media-id} ng metadata object ng Meta — messaging_product, mime_type, sha256, file_size, id — ngunit ang url ay nakaturo sa amin, hindi sa lookaside host ng Meta.
Kailangan itong maging ganoon. Ang media URL ng Meta ay maaari lamang ma-fetch gamit ang business token ng WhatsApp account, na nasa aming panig at hindi kailanman umaalis doon. Kaya binibigyan ka namin ng URL na puwede mong i-fetch: ang download endpoint sa itaas, sa parehong host at version segment na tinawag mo, na naka-authenticate gamit ang parehong bearer token na naipadala mo na.
Itinuturing ng mga client ang URL na iyon bilang opaque at simpleng nag-GET dito gamit ang kanilang token, kaya naman hindi ito napapansin ng isang unmodified na SDK. Kung gumagawa ng special case ang iyong code para sa hostname, iyon ang nag-iisang lugar kung saan kakailanganin nito ng pagbabago.
Mga Permission
Ang parehong mga permission chip gaya ng sa WizMessage API, sa parehong mga key. Kung saan binabasa ang permission ay depende sa call: kinukuha ito ng send endpoint mula sa request body, dahil inilalagay ng Meta ang bawat uri ng mensahe sa iisang path; sa lahat ng iba pa, nagmumula ito sa path at method.
Pagpapadala at media:
| Call | Permission |
|---|---|
POST /{v}/{pnid}/messages na may "type": "template" | send_template |
pareho, type na image, video, audio, document o sticker | send_media |
| pareho, anupamang iba — text, interactive, reaction, location, contacts, at mark-as-read | send_text |
POST /{v}/{pnid}/media — pag-upload | send_media |
DELETE /{v}/{media-id} | send_media |
GET /{v}/{media-id} at /download | view_messages |
Pamamahala ng account — tingnan ang Pamamahala sa account:
| Call | Permission |
|---|---|
GET /{v}/{waba-id}/message_templates | view_templates |
POST at DELETE /{v}/{waba-id}/message_templates | manage_templates |
GET /{v}/{waba-id}/template_analytics | view_analytics |
GET sa business profile, mga QR code, mga setting ng commerce, block list, mga setting ng telepono, at mga flow | view_templates |
POST sa parehong anim na iyon | manage_profile |
DELETE /{v}/{pnid}/message_qrdls/{code} at DELETE /{v}/{pnid}/block_users | manage_profile |
Iyon lamang ang dalawang DELETE sa panig ng pamamahala. Walang delete sa business profile, mga setting ng commerce, mga setting ng telepono, o mga flow — ang isang DELETE sa alinman sa mga ito ay tinatanggihan bilang code 100, katulad ng isang endpoint na hindi umiiral.
Tala: Nangangailangan dito ng
send_mediaang pag-upload ng media. Sa WizMessage API, hindi ito nangangailangan ng anumang permission, batay sa pangangatwiran na pinamamahalaan ngsend_mediaang pagpapadala ng file sa isang customer sa halip na paglalagay nito sa mga server ng Meta. Mas mahigpit ang panuntunan ng surface na ito. Kung naglilipat ka ng key at nagsimulang magbalik ng403ang mga pag-upload, ito ang dahilan.
Tala: Higit pa sa mga template ang binabantayan ng
view_templates. Ang pagbasa sa business profile, mga QR code, mga setting ng commerce, ang block list, mga setting ng telepono, at mga flow ay pawang nakapailalim dito. Makasaysayan ang pangalan — mas nauna ito kaysa sa lahat ng nasa ikalawang talahanayan. I-untick ito habang nililimitahan ang sakop ng isang key at anim na walang kaugnayang pagbasa ang magsisimulang magbalik ng403na may mensaheng tungkol sa mga template, na hindi nakakatulong na pahiwatig.
Tala: Tatlong chip ay para sa Meta Graph lamang. Walang binabantayan ang
manage_templates,manage_profile, atview_analyticssa WizMessage API — umiiral ang mga ito para sa mga endpoint sa page na ito. Ang bawat key na dati nang umiiral ay pinagkalooban ng tatlong ito, kaya walang gumaganang bagay ang huminto; ang paglilimita ay isang sadyang pag-untick sa edit form ng key.
Ang pagtanggi ay Graph code 10 sa 403 — hindi kailanman ang aming PERMISSION_DENIED. Sakop ng iisang error handler ang surface na ito nang buo.
Sinusuri ang pagmamay-ari bago ang permission. Kung ang id sa path ay hindi ang nasa likod ng iyong key, ang sagot ay code 100 at hindi nito kailanman ibinubunyag kung aling permission ang kulang sa iyo — kung hindi, ang mismong error ay magiging paraan upang magsiyasat sa mga account ng ibang tao.
Pamamahala sa account
Bukod sa pagpapadala, dala ng surface na ito ang mga account-management endpoint ng Meta sa sariling mga path ng Meta. Walong resource, at ang pahintulot na kailangan mo ay nakadepende kung nagbabasa ka o nagsusulat.
Tatlong bagay ang totoo sa bawat endpoint sa seksyong ito, at ang mga ito ang buong dahilan kung bakit ito puwedeng umiral:
- Ang request body ay sa Meta mismo, na ipinapasa nang walang pagbabago at hindi bini-validate. Hindi namin muling idinodokumento ang mga body ng Meta rito at hindi namin sinusuri ang mga ito. Ang reference ng Meta ang spec, at ang error ng Meta ang ibinabalik kung magkamali ka — na mas magandang error kaysa sa anupamang puwede naming maimbento.
- Ipinapadala lang ang body sa
POST. Ang body na nakakabit sa isangDELETEay inaalis bago umalis ang request sa amin. Tumatanggap ang template delete ng Meta ng?name=o?hsm_id=bilang mga query parameter, hindi body, kaya gumagana ito ayon sa dokumentado; ang anupamang umaasa sa isang delete body ay hindi gagana. - Ipinapasa ang iyong query string, minus ang
access_tokenatappsecret_proof. Inaalis ang dalawang iyon, dahil mas pinapaboran ng Meta ang query-string token kaysa saAuthorizationheader at kapag pinadaan ang mga ito ay magiging opsyonal ang iyong bearer. Ang client na nag-a-authenticate sa pamamagitan ng query string ay makikitang tahimik itong binabalewala — gamitin ang header.
Tandaan: Ang WABA id at phone number id sa mga path na ito ay dapat ang mismong nasa likod ng iyong key. Sinusuri iyon bago may umalis sa aming network, at ang mismatch ay ang parehong
code 100na inilarawan sa Kapag ang isang id ay hindi sa iyo.
Tandaan: Nakaturo ang
paging.nextsa Meta, hindi sa amin. Ibinabalik ang mga tugon nang eksakto kung paano ipinadala ng Meta ang mga ito, kaya angnextna link sa isang paged na tugon ay isang URL nggraph.facebook.com— at hindi nag-a-authenticate doon ang iyong API key. Mag-page sa pamamagitan ng pagkuha ngpaging.cursors.afterat muling pagpapadala ng request sa host na ito gamit ang?after=.
Mga Template
GET https://wizmessage.com/v26.0/{waba-id}/message_templates?limit=25
POST https://wizmessage.com/v26.0/{waba-id}/message_templates
DELETE https://wizmessage.com/v26.0/{waba-id}/message_templates?name=order_shipped
| Paraan | Pahintulot | Ibinabalik |
|---|---|---|
GET | view_templates | { data, paging } ng Meta |
POST | manage_templates | create response ng Meta |
DELETE | manage_templates | delete response ng Meta |
Tumatanggap ang GET ng limit (1–100, default na 25) at after para sa cursor pagination.
Tandaan: Tumatanggap lang ang
GETnglimitatafter. Ang iba pang mga filter ng Meta sa edge na ito —name,status,fields,language,category,name_or_content— ay tahimik na inaalis, hindi tinatanggihan. Ang isang request para sa?status=APPROVEDay nagbabalik ng200na nagdadala sa bawat template, naaprubahan man o hindi. Mag-filter sa iyong panig, o gamitin angafterpara i-page ang buong listahan. Ito ang nag-iisang lugar sa page na ito kung saan ang isang na-port na client ay nakakakuha ng maling sagot sa halip na error, kaya sulit na suriin ang iyong code para rito.
Analytics ng template
GET https://wizmessage.com/v26.0/{waba-id}/template_analytics
Kailangan ang view_analytics. Hinihiling ng Meta ang start, at sumasagot ng code 100 — "(#100) The parameter start is required" — kung wala ito. Ang granularity at ang mga natitirang parameter ay sa Meta; ipasa ang mga ito at darating ang mga ito nang walang pagbabago.
Business profile
GET https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_business_profile?fields=about,address,description,email,profile_picture_url,websites,vertical
POST https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_business_profile
Kailangan ng GET ang view_templates at ibinabalik ang { data } ng Meta. Kailangan ng POST ang manage_profile.
Mga QR code
GET https://wizmessage.com/v26.0/{phone-number-id}/message_qrdls
POST https://wizmessage.com/v26.0/{phone-number-id}/message_qrdls
DELETE https://wizmessage.com/v26.0/{phone-number-id}/message_qrdls/{code}
Kailangan ng GET ang view_templates at ibinabalik ang { data } ng Meta. Kailangan ng POST at DELETE ang manage_profile.
Ang path na /{code} ay DELETE lang. Walang GET o POST sa iisang code — basahin ang koleksyon at pumili mula roon.
Mga setting ng commerce
GET https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_commerce_settings
POST https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_commerce_settings
Kailangan ng GET ang view_templates at ibinabalik ang { data } ng Meta. Kailangan ng POST ang manage_profile.
Mga naka-block na customer
GET https://wizmessage.com/v26.0/{phone-number-id}/block_users
POST https://wizmessage.com/v26.0/{phone-number-id}/block_users
DELETE https://wizmessage.com/v26.0/{phone-number-id}/block_users
Kailangan ng GET ang view_templates at ibinabalik ang { data } ng Meta. Kailangan ng POST at DELETE ang manage_profile. Tandaan na ang pag-unblock ay isang DELETE sa mismong koleksyon, hindi sa path para sa bawat customer.
Mga setting ng numero ng telepono
GET https://wizmessage.com/v26.0/{phone-number-id}/settings
POST https://wizmessage.com/v26.0/{phone-number-id}/settings
Kailangan ng GET ang view_templates at ibinabalik ang { calling, storage_configuration }. Kailangan ng POST ang manage_profile.
Tandaan: Ang path ay
/settings. Tinatawag ito ng ilang third-party API reference nawhatsapp_calling_settings— hindi umiiral ang path na iyon sa Meta at nagbabalik ngcode 2500dito, dahil ipinapasa namin ito at tinatanggihan ito ng Meta. Tingnan ang Kung ano ang hindi available dito.
Mga Flow
GET https://wizmessage.com/v26.0/{waba-id}/flows
POST https://wizmessage.com/v26.0/{waba-id}/flows
Kailangan ng GET ang view_templates at ibinabalik ang { data, paging } ng Meta. Kailangan ng POST ang manage_profile.
Ang hindi available dito
Ang lahat ng nasa itaas ay kinumpirma laban sa isang live na WhatsApp account. Gayundin ang lahat ng nasa ibaba — kaya naman masasabi sa iyo ng seksyong ito kung bakit nawawala ang isang endpoint, at karaniwan ay iyon ang nagpapasiya kung ano ang susunod mong gagawin.
Kung ano ang ibinabalik ng isang hindi available na endpoint. Ang anumang wala sa listahan sa itaas ay sumasagot gamit ang sariling pananalita ng Meta para sa isang path na hindi nito ise-serve — code 100 sa 400:
Unsupported get request. Object with ID '…' does not exist, cannot be loaded due to missing permissions, or does not support this operation.
Ang isang path na sinusuportahan nga ngunit tinawag gamit ang isang method na hindi nito iniaalok ay nagbabalik ng parehong code na may mas maikling mensahe: "Unsupported delete request." Ang parehong ito ay sadyang hindi maipagkakaiba sa isang object na sadyang hindi mo makikita — ang isang error na magpapatunay kung aling mga endpoint ang umiiral ay magiging isang paraan upang mai-map ang surface.
Sadyang tinanggihan
Naka-block ang mga ito sa bawat method, bago pa man may maipasa:
| Path | Bakit |
|---|---|
register, deregister, request_code, verify_code | Ang isang coexistence number ay hinding-hindi dapat irehistro sa Cloud API. Ang paggawa nito ang mismong dahilan kung bakit nauuwi ang isang account sa pagpalya ng bawat pagpapadala na may error na 133010, at hindi ito maibabalik mula sa iyong panig. |
subscribed_apps | Lahat ng method, kabilang ang GET. Ang isang DELETE dito ay mag-a-unsubscribe sa aming mga webhook mula sa iyong sariling WhatsApp account at tahimik na sisira sa sarili mong integrasyon; hindi rin namin inaalok ang pagbasa, sa halip na mag-iwan ng path kung saan magagawa iyon ng isang pagkakamali. |
marketing_messages | Ang mga pagpapadala ng marketing ay dumadaan sa mga campaign tool ng dashboard, na nagpapatupad ng send rate para sa bawat account. |
/{template-id}/unpause | Tinutukoy ng Meta ang template gamit ang isang bare id na walang account sa path, kaya hindi namin mapapatunayan na sa iyo ang template bago ito aksyunan. I-unpause mula sa dashboard. |
messages sa anumang method maliban sa POST | Dala ng send path ang rate limiter at ang pangangasiwa sa suspensyon ng account. POST lang ang niruruta. |
Hindi available sa isang coexistence number
Ang sariling mga sagot ng Meta, na sinuri gamit ang isang live na account noong 10 Agosto 2026:
| Path | Sagot ng Meta |
|---|---|
/{phone-number-id}/conversational_automation | code 100 — "Tried accessing nonexisting field" |
/{phone-number-id}/calls | code 100 — "Tried accessing nonexisting field" |
/{phone-number-id}/groups | code 131000 sa isang 500 |
Ito ang mga paghihigpit ng Meta sa mga numerong gumagana sa coexistence sa WhatsApp Business app, hindi sa amin — ipinapasa namin ang request at ito ang bumabalik. Pinalalawak ng Meta ang availability paminsan-minsan, kaya kung mahalaga sa iyo ang isa sa mga ito, sulit itong muling subukan sa halip na umasa sa talahanayang ito nang palagian.
Mga path na hindi umiiral kahit saan
Bawat isa sa mga ito ay lumalabas sa mga third-party API reference at hindi isang endpoint ng Meta. Ang lahat ng apat ay nagbabalik ng code 2500, "Unknown path components":
| Kung ano ang maaaring nabasa mo | Kung ano ang gagamitin sa halip |
|---|---|
POST /{phone-number-id}/mark_message_as_read | POST /{phone-number-id}/messages na may status: "read" na body — tingnan ang Pagmarka sa isang mensahe bilang nabasa na |
GET /{phone-number-id}/message_status | Dumarating ang mga delivery status sa iyong webhook; tingnan ang Pagpili kung ano ang iyong matatanggap |
/{phone-number-id}/whatsapp_calling_settings | /{phone-number-id}/settings |
/{phone-number-id}/conversational_components | Wala — ang pinakamalapit na totoong path ay ang conversational_automation, na hindi available sa isang coexistence number |
Totoo sa Meta, wala sa aming listahan
Gumagana ang GET /{waba-id}/phone_numbers sa Meta at hindi ito naka-block o ipinapasa rito, kaya sumasagot ito ng code 100. Isa ito sa mga unang endpoint na tinatawagan ng isang Cloud API client, kaya nararapat itong banggitin: naka-pin na ang iyong key sa eksaktong isang numero ng telepono, at ang id nito ang inilalagay mo sa bawat path sa page na ito. Mababasa mo ito mula sa Overview tab ng key sa dashboard.
Mga bare node read
Gumagana ang GET /{v}/{waba-id}?fields=… at GET /{v}/{phone-number-id}?fields=… sa Meta ngunit hindi rito. Ang isang single-segment na path sa surface na ito ay isang media id — iyan ang ibig sabihin ng GET /{v}/{media-id} — kaya ang isang WABA id sa posisyong iyon ay hinahanap bilang media at pumapalya.
Nakakalito ang pagpalya kung hindi mo ito inaasahan: sinusuri muna nito ang view_messages, kaya ang isang key na walang ganoong pahintulot ay nakakatanggap ng 403 na nagpapangalan ng isang pahintulot na walang kinalaman sa hiniling. Gamitin sa halip ang mga edge form — /{waba-id}/message_templates, /{phone-number-id}/settings, at ang iba pa sa Pamamahala sa account.
Mga webhook sa format ng Meta
Bubukas ang tab ng webhook ng dashboard sa isang payload format. Ang WizMessage (v1) ang payload na idinodokumento ng kabilang page; ito ang ginagamit ng isang key hanggang sa baguhin mo ito.

Piliin ang Meta Graph at titigil ang iyong endpoint sa pagtanggap ng aming {version, event, timestamp, data} payload at magsisimulang tumanggap ng envelope na ipinadala sa amin ng Meta, na ipinapasa nang verbatim — isang delivery bawat pagbabago.
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"time": 1770000123,
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [{ "profile": { "name": "Priya Sharma" }, "wa_id": "919876543210" }],
"messages": [
{
"from": "919876543210",
"id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAEhgg…",
"timestamp": "1770000123",
"type": "text",
"text": { "body": "Has it shipped yet?" }
}
]
},
"field": "messages"
}
]
}
]
}
Kung mayroon ka nang Cloud API webhook handler, iyon ang anyo kung para saan ito isinulat.
Binabago rin ng pagpapalit ng format ang hinihingi sa iyo ng tab: pinapalitan ang mga checkbox ng event ng mga sariling field name ng Meta, at lumalabas ang isang verify token.

Bago ka makapag-save ng isa
Tatlong bagay ang kailangan, at sasabihin sa iyo ng dashboard kung alin ang kulang:
- Isang webhook secret. Ito lamang ang nag-ki-key sa
X-Hub-Signature-256, kaya kung wala ito, hindi lalagdaan at hindi mabe-verify ang delivery. Mag-generate ng isa sa tab ng Webhooks ng key. - Isang verify token. Anumang string na piliin mo; dapat alam din ito ng iyong endpoint.
- Isang URL na sumasagot na. Tingnan sa ibaba.
Ang verification handshake
Kapag nag-save ka, tinatawagan namin ang iyong URL nang eksakto kung paano ito gagawin ng Meta:
GET https://your-server.example/webhooks
?hub.mode=subscribe
&hub.verify_token=<the token you set>
&hub.challenge=482910337
Dapat suriin ng iyong endpoint na tumutugma ang hub.verify_token sa na-configure mo, pagkatapos ay sumagot ng 200 na ang hub.challenge ang buong response body — walang JSON wrapper, walang panipi, wala nang iba pa. Ang challenge ay isang 9-digit na numero, kaya ang isang handler na nagsu-parseInt bago mag-echo ay naibabalik ito nang walang pagbabago.
Kung hindi eksaktong maibabalik ang challenge, tatanggihan ang pag-save at walang maiimbak. Ito ang pumipigil sa sinuman na ituro ang aming delivery queue sa isang URL na hindi nila kontrolado.
// express
app.get('/webhooks', (req, res) => {
if (req.query['hub.mode'] === 'subscribe' && req.query['hub.verify_token'] === VERIFY_TOKEN) {
return res.status(200).send(req.query['hub.challenge'])
}
res.sendStatus(403)
})
Pag-verify sa signature
Bawat delivery ay may dalang X-Hub-Signature-256, na kinakalkula sa paraang kinakalkula ito ng Meta: HMAC-SHA256 ng raw request body, na naka-key sa iyong webhook secret, hex, na may prefix na sha256=.
| Header | Halaga |
|---|---|
X-Hub-Signature-256 | sha256= + HMAC-SHA256 ng raw body, na naka-key sa iyong webhook secret, lowercase hex. |
X-Webhook-Event | meta.<field> — kung aling field ang dala ng delivery na ito. |
X-Webhook-Id | Natatanging id para sa pagtatangkang ito ng delivery. Mag-dedupe batay dito. |
User-Agent | facebookplatform/1.0 (+http://developers.facebook.com) |
Tandaan: Hindi ito katulad ng derivation ng format ng WizMessage. Nilalagdaan niyon ang
timestamp + "." + rawBodyat ipinapadala ang timestamp sa sarili nitong header; nilalagdaan naman nito ang body lamang, nang walang timestamp saanman. Kung nagpapatakbo ka ng parehong format laban sa iisang server, panatilihing magkahiwalay ang dalawang verifier — mabibigo ang pinagsaluhang verifier sa alinman kung saan hindi ito isinulat.
Lagdaan ang mga raw byte kung paano natanggap. Binabago ng pag-parse ng JSON at muling pag-serialize ang pagkakasunod-sunod ng key at spacing, at hindi kailanman tutugma ang signature.
const crypto = require('node:crypto')
// express: app.post('/webhooks', express.raw({ type: 'application/json' }), ...)
function verify(req) {
const provided = req.get('X-Hub-Signature-256') || ''
if (!provided.startsWith('sha256=')) return false
const expected = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(req.body) // the raw Buffer, not a parsed object
.digest('hex')
// Constant-time compare — a plain === leaks timing information.
const a = Buffer.from(expected, 'hex')
const b = Buffer.from(provided.slice('sha256='.length), 'hex')
return a.length === b.length && crypto.timingSafeEqual(a, b)
}
Pagpili sa kung ano ang iyong matatanggap
Sa WizMessage format, mga event ang nilalagyan mo ng tsek. Dito, ang nilalagyan mo ng tsek ay ang mga field name ng Meta, na tumutugma sa kung ano ang isa-subscribe mo sa sariling App Dashboard ng Meta.
| Field | Kung ano ang dumarating |
|---|---|
messages | Mga papasok na mensahe at mga delivery status. Basahin ang paalala sa ibaba. |
message_status | Mga delivery status, bilang sarili nilang field. |
smb_message_echoes | Mga mensaheng ipinadala ng negosyo mula sa WhatsApp Business app sa kanilang telepono. |
smb_app_state_sync | Mga pagbabago sa address book na ginawa sa teleponong iyon. |
user_id_update | Nabago ang WhatsApp identity ng isang contact. |
message_template_status_update | Naaprubahan, tinanggihan, o na-pause ang isang template. |
message_template_quality_update | Gumalaw ang quality score ng isang template. |
account_update | Naikonekta, nadiskonekta, nalimitahan, o na-offboard ang WhatsApp account. |
history | Mga nakaraang pag-uusap, sa panahon ng inisyal na pag-sync. Malalaking payload — mag-opt in lamang kung gusto mo ang mga ito. |
Nagsisimula ang mga bagong graph webhook na naka-subscribe sa messages lamang. Ang pag-clear sa bawat field ay nagpapatay sa mga delivery nang hindi binubura ang configuration.
Tandaan: Naglalaman na ang
messagesng mga delivery status. Ipinapadala ng Meta ang pareho sa ilalim ng"field": "messages"— mga papasok na mensahe sa isangmessagesarray, mga ulat ng delivery sa isangstatusesarray sa parehong value object. Kaya sapat na ang default na subscription para maiugnay angwamidna nakuha mo mula sa isang pagpapadala. Angmessage_statusay isang karagdagang field, hindi ang kailangan mo para sa pangunahing pagsubaybay sa status. Basahin angvalue.statusesbago ipalagay na may kulang kang subscription.
Tatlong bagay na naiiba sa format ng WizMessage
Sulit basahin kung naglilipat ka ng integration, dahil tahimik na binabago ng bawat isa kung ano ang lumalabas.
- Hindi nakasalalay ang delivery sa sistema ng chatbot. Sa WizMessage format, dumarating lamang ang mga papasok na mensahe sa iyong endpoint kapag nakatakda ang sistema ng chatbot ng account sa Webhook. Ganap na binabale-wala ng Graph format ang setting na iyon — ang pag-configure ng isang URL at pag-subscribe sa isang field ang buong pag-opt in.
- Matatanggap mo ang
status: "sent"at mga status ng campaign. Sadya itong inaalis ng WizMessage format. Dito, makukuha mo kung ano ang ipinadala ng Meta, na nangangahulugang kapansin-pansing mas maraming status traffic sa isang account na nagpapatakbo ng mga bulk campaign. - Walang synthetic na
message.sent. Gumagawa ang WizMessage format ng isa para sa mga mensaheng ipinadala mula sa API, sa dashboard, o sa telepono. Sinasaklaw ng Meta ang parehong sitwasyon gamit angsmb_message_echoesat angsentstatus, kaya walang iniimbento rito.
Delivery, mga retry, at pag-off
Kapareho ng format ng WizMessage — ang parehong talahanayan ang nalalapat. Sa madaling sabi: naghihintay kami nang 10 segundo, hindi kailanman sumusunod sa mga redirect, nagre-retry ng 5xx/408/429/timeouts nang limang beses nang may backoff, hindi kailanman nagre-retry ng iba pang 4xx, at itinuturing ang 410 Gone bilang “i-off ang webhook na ito”.
At-least-once ang mga delivery. Mag-dedupe batay sa X-Webhook-Id, at mabilisang sumagot ng 2xx.
Pagsubok nito nang hindi nagsusulat ng code
May kontrol na API Format ang Test API dialog ng key. I-set ito sa Meta Graph at mapapalitan ang endpoint picker ng totoong target para sa iyong account — POST /v26.0/{your phone number id}/messages — na may pre-filled na Meta-shaped body.

Ibinabalik ng "Simulate Only" ang request nang hindi kinokontak ang Meta; ang paglipat sa Send Real Message ay nagpapadala nito at nagpapakita sa iyo ng aktwal na tugon ng Meta, kasama ang error envelope at lahat.
Nakatarget ang dialog sa POST /{phone-number-id}/messages at wala nang iba, kaya hindi maaabot mula rito ang mga endpoint sa pamamahala ng account — subukan ang mga iyon gamit ang curl o ang sarili mong client.
Taglay rin ng Get code ang parehong kontrol, kaya tina-target ng nabuong snippet kung alinmang surface ang piliin mo, sa alinman sa walong wika. Iwanang naka-off ang "Require signature" sa key na balak mong gamitin dito — kapag naka-on ito, pipirmahan din ng nabuong Graph snippet ang request, na siyang tanging bagay na hindi kayang gawin ng isang hindi binagong Cloud API client.