Lumaktaw sa nilalaman
34 min read

Pagkonekta gamit ang Meta Graph API

I-point ang isang umiiral na WhatsApp Cloud API integration sa WizMessage nang hindi ito muling isinusulat — ang mga path ng Meta, mga request body ng Meta, error envelope ng Meta, mga webhook sa sariling format ng Meta, at ang mga account-management endpoint para sa mga template, business profile, mga QR code at mga flow.

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 WizMessage API kung ihahambing sa Meta Graph-compatible na APIPiliin ang tumutugma sa kung anong mayroon ka naWizMessage API/api/v1/externalmga pinangalanang template variablemapping UI sa dashboardreference field, paghahanap ng statussarili naming JSON envelopepinakamainam kung nagsisimula sa walaMeta Graph API/v26.0/{phone-number-id}/…mga request body ng Metaerror envelope ng Metapamahalaan ang mga template at profilemga webhook sa format ng Metapinakamainam kapag may Cloud API code ka naParehong mga key, parehong mga pahintulot, parehong mga rate limit. Gamitin ang dalawa kung gusto mo.
Dalawang surface, isang account. Walang mawawala sa dalawa.

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 v26 nang mag-isa. Hindi opsyonal ang minor number. Ayos lang ang v26.0, 404 ang v26.

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.

HeaderHalaga
AuthorizationBearer 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 190 na may 401. 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:

HeaderHalaga
X-Subscription-WarningSubscription 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"
	}
}
Ano ang nangyayari sa pag-access sa API pagkatapos mag-lapse ang subscriptionisang API keynormalwalang headerpalugit7 araw, gumagana pa rin ang mga tawagX-Subscription-Warning sa bawat tugontinanggihancode 10 sa 403unang tawag pagkatapos ng pagka-lapsedito magsisimula ang orasnagtatapos ang palugitwala nang karagdagang babalaAng pag-renew sa anumang punto ay nagpapanumbalik ng access sa loob ng ilang minuto.
Walang binabago ang pagka-lapse mismo. Magsisimula ang oras sa susunod mong tawag.

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-Warning ang tanging paunang abiso na mayroon — i-log ito, kundi ang una mong malalaman ay isang 403.

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 to ng 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.164 at tinatanggihan ang anupaman bukod doon, habang ipinapasa naman nito ang iyong halaga nang diretso sa Meta. Ang nag-iisang eksepsiyon ay ang POST /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 contacts array 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.

Kung paano nakakarating sa iyo ang isang error depende kung ang Meta ang gumawa nitoIsang error sa surface na itoTinanggihan ito ng Metaipinasa nang verbatimcode at subcode ng Metasariling fbtrace_id ng Metastatus ay sa Meta rinTinanggihan namin itoauth, permission, rate limitnakasulat sa mga code ng Metakaya sakop ng iisang handler ang dalawa401 · 403 · 429 · 400 · 500Huwag kailanman ipalagay na OAuthException ang type — marami ang ginagamit ng Meta.
Ipinapasa nang walang pagbabago ang sariling mga error ng Meta. Humihiram ang sa amin ng mga code ng Meta.

Mga error na inilalabas namin

codeHTTPKailan
190401Nawawala, 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.
10403Kulang 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.
4429Naubos na ang kada minuto o pang-araw-araw na allowance ng key.
100400Malformed na request, isang id sa path na hindi sa iyo, o isang endpoint na hindi sineserbisyuhan ng surface na ito.
2500May 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 type sa halimbawang iyon — GraphMethodException, hindi OAuthException. Gumagamit ang Meta ng ilang exception type at hindi namin bina-normalize ang mga ito. Mag-switch batay sa error.code, na isang numero at stable; ituring ang type bilang 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.

MethodPathAno ang ginagawa nito
POST/{version}/{phone-number-id}/mediaMag-upload ng file. Multipart, nagbabalik ng {"id": "…"}.
GET/{version}/{media-id}Metadata object ng Meta para sa file.
GET/{version}/{media-id}/downloadAng mga byte.
DELETE/{version}/{media-id}I-delete ito, nagbabalik ng {"success": true}.
Pag-upload ng file nang isang beses at paulit-ulit na pagpapadala nitoPOST /{v}/{pnid}/mediaang file mismo{ id }magagamit muliPOST /{v}/{pnid}/messagesi-reference ang idNaihatiddumarating ang mga status sa pamamagitan ng webhook
Nagbabalik ng id ang pag-upload. Ang id ang inilalagay mo sa isang mensahe.

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:

CallPermission
POST /{v}/{pnid}/messages na may "type": "template"send_template
pareho, type na image, video, audio, document o stickersend_media
pareho, anupamang iba — text, interactive, reaction, location, contacts, at mark-as-readsend_text
POST /{v}/{pnid}/media — pag-uploadsend_media
DELETE /{v}/{media-id}send_media
GET /{v}/{media-id} at /downloadview_messages

Pamamahala ng account — tingnan ang Pamamahala sa account:

CallPermission
GET /{v}/{waba-id}/message_templatesview_templates
POST at DELETE /{v}/{waba-id}/message_templatesmanage_templates
GET /{v}/{waba-id}/template_analyticsview_analytics
GET sa business profile, mga QR code, mga setting ng commerce, block list, mga setting ng telepono, at mga flowview_templates
POST sa parehong anim na iyonmanage_profile
DELETE /{v}/{pnid}/message_qrdls/{code} at DELETE /{v}/{pnid}/block_usersmanage_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_media ang pag-upload ng media. Sa WizMessage API, hindi ito nangangailangan ng anumang permission, batay sa pangangatwiran na pinamamahalaan ng send_media ang 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 ng 403 ang 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 ng 403 na 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, at view_analytics sa 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.

Ang mga account management endpoint na nakapangkat ayon sa kailangang pahintulot ng bawat isaPagbasa ng kahit anolahat ng walong resourceprofile, mga QR code, commerceblock list, mga setting, mga flowmga templateview_templatesPagsulat sa accountprofile at presencebusiness profile, mga QR codecommerce, block listmga setting, mga flowmanage_profilePagsulat ng mga templategumawa at mag-deletemessage_templatesnakahiwalay ang analyticsmanage_templatesMay sariling chip ang template analytics: view_analytics.
Isang chip ang pagbasa. Ang pagsulat ay nahahati ayon sa kung ano ang isinusulat mo.

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 isang DELETE ay 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_token at appsecret_proof. Inaalis ang dalawang iyon, dahil mas pinapaboran ng Meta ang query-string token kaysa sa Authorization header 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 100 na inilarawan sa Kapag ang isang id ay hindi sa iyo.

Tandaan: Nakaturo ang paging.next sa Meta, hindi sa amin. Ibinabalik ang mga tugon nang eksakto kung paano ipinadala ng Meta ang mga ito, kaya ang next na link sa isang paged na tugon ay isang URL ng graph.facebook.com — at hindi nag-a-authenticate doon ang iyong API key. Mag-page sa pamamagitan ng pagkuha ng paging.cursors.after at 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
ParaanPahintulotIbinabalik
GETview_templates{ data, paging } ng Meta
POSTmanage_templatescreate response ng Meta
DELETEmanage_templatesdelete response ng Meta

Tumatanggap ang GET ng limit (1–100, default na 25) at after para sa cursor pagination.

Tandaan: Tumatanggap lang ang GET ng limit at after. 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=APPROVED ay nagbabalik ng 200 na nagdadala sa bawat template, naaprubahan man o hindi. Mag-filter sa iyong panig, o gamitin ang after para 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 na whatsapp_calling_settings — hindi umiiral ang path na iyon sa Meta at nagbabalik ng code 2500 dito, 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.

Kung bakit maaaring hindi available ang isang endpoint sa surface na itoisang endpoint na wala ritoTinatanggihan namin itoregistration, subscribed_appssisirain nito ang iyong accountwalang workaroundTinatanggihan ito ng Metawala sa isang coexistence numberconversational_automation, callssariling sagot ng MetaHindi ito umiiralapat na path mula sa mga API mirrorsumasagot ang Meta ng code 2500gamitin ang totoong pathAng ikaapat na grupo ay sadyang wala pa sa aming listahan — tingnan sa ibaba.
Apat na dahilan, at isa lang sa mga ito ang sa amin.

Sadyang tinanggihan

Naka-block ang mga ito sa bawat method, bago pa man may maipasa:

PathBakit
register, deregister, request_code, verify_codeAng 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_appsLahat 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_messagesAng mga pagpapadala ng marketing ay dumadaan sa mga campaign tool ng dashboard, na nagpapatupad ng send rate para sa bawat account.
/{template-id}/unpauseTinutukoy 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 POSTDala 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:

PathSagot ng Meta
/{phone-number-id}/conversational_automationcode 100 — "Tried accessing nonexisting field"
/{phone-number-id}/callscode 100 — "Tried accessing nonexisting field"
/{phone-number-id}/groupscode 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 moKung ano ang gagamitin sa halip
POST /{phone-number-id}/mark_message_as_readPOST /{phone-number-id}/messages na may status: "read" na body — tingnan ang Pagmarka sa isang mensahe bilang nabasa na
GET /{phone-number-id}/message_statusDumarating 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_componentsWala — 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.

Ang tab ng Webhooks na nakatakda ang payload format sa WizMessage, na nagpapakita ng mga checkbox ng v1 event

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.

Ang tab ng Webhooks sa format na Meta Graph, na nagpapakita ng verify token at ng siyam na field name ng Meta na puwedeng i-subscribe

Bago ka makapag-save ng isa

Tatlong bagay ang kailangan, at sasabihin sa iyo ng dashboard kung alin ang kulang:

Ang kailangang maihanda bago mai-save ang isang Meta Graph webhookWebhook secretsusi para sa signatureVerify tokennagpapatunay na sa iyo ang URLIsang live na URLtinatawagan namin ito bago mag-saveNai-save namagsisimula na ang mga deliveryHindi puwedeng i-save ang URL na hindi pa sumasagot. Mag-deploy muna, pagkatapos ay mag-configure.
Sinusuri ang tatlo kapag pinindot mo ang save, sa ganitong pagkakasunod-sunod.
  • 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=.

HeaderHalaga
X-Hub-Signature-256sha256= + HMAC-SHA256 ng raw body, na naka-key sa iyong webhook secret, lowercase hex.
X-Webhook-Eventmeta.<field> — kung aling field ang dala ng delivery na ito.
X-Webhook-IdNatatanging id para sa pagtatangkang ito ng delivery. Mag-dedupe batay dito.
User-Agentfacebookplatform/1.0 (+http://developers.facebook.com)

Tandaan: Hindi ito katulad ng derivation ng format ng WizMessage. Nilalagdaan niyon ang timestamp + "." + rawBody at 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.

FieldKung ano ang dumarating
messagesMga papasok na mensahe at mga delivery status. Basahin ang paalala sa ibaba.
message_statusMga delivery status, bilang sarili nilang field.
smb_message_echoesMga mensaheng ipinadala ng negosyo mula sa WhatsApp Business app sa kanilang telepono.
smb_app_state_syncMga pagbabago sa address book na ginawa sa teleponong iyon.
user_id_updateNabago ang WhatsApp identity ng isang contact.
message_template_status_updateNaaprubahan, tinanggihan, o na-pause ang isang template.
message_template_quality_updateGumalaw ang quality score ng isang template.
account_updateNaikonekta, nadiskonekta, nalimitahan, o na-offboard ang WhatsApp account.
historyMga 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 messages ng mga delivery status. Ipinapadala ng Meta ang pareho sa ilalim ng "field": "messages" — mga papasok na mensahe sa isang messages array, mga ulat ng delivery sa isang statuses array sa parehong value object. Kaya sapat na ang default na subscription para maiugnay ang wamid na nakuha mo mula sa isang pagpapadala. Ang message_status ay isang karagdagang field, hindi ang kailangan mo para sa pangunahing pagsubaybay sa status. Basahin ang value.statuses bago 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.

Tatlong gawi na naiiba sa pagitan ng dalawang format ng webhookWalang chatbot gateinihahatid sa alinmang paraanKailangan ng v1 ang bot mode = WebhookHindi pinapansin ng Graph ang setting na iyonMakukuha mo ang sentat mga status ng campaignSinasala ng v1 ang parehoIpinapasa ng Graph ang lahatWalang synthetic sentMga sariling event ng Meta sa halipsmb_message_echoesat mga statusAsahan ang mas maraming traffic sa Graph format kaysa sa nagawa ng parehong account sa v1.
Lahat ng tatlo ay nagiging dahilan para maghatid ang Graph format nang mas marami, hindi mas kaunti.
  • 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 ang smb_message_echoes at ang sent status, 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.

Ang Test API dialog sa Meta Graph mode, na nagpapakita ng read-only na messages endpoint at isang Meta-shaped na request 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.