Pagkonekta ng iyong software sa WhatsApp

Ang API Management ang paraan kung paano nagpapadala ng WhatsApp messages ang ibang sistema — ang iyong billing software, ang iyong online store, ang sarili mong backend — sa pamamagitan ng WizMessage. Dito ka mag-iisyu ng API key para dito, dito mo sasabihin kung aling aprubadong WhatsApp template ang puwede nitong ipadala, at dito mo ito ituturo sa isang webhook para makabalik ang mga sagot. Dadaanan ng gabay na ito ang buong proseso, at pagkatapos ay idodokumento ang REST API na tatawagin ng iyong mga developer.

Ang dashboard

Kung saan matatagpuan ang iyong mga API key

Lahat ng key na na-isyu mo ay lalabas dito sa ilalim ng API Keys. Ipinapakita ng bawat row ang status ng key, ang public prefix nito (ang tanging bahagi ng key na muli mo pang makikita matapos mo itong gawin), at kung ilang calls na ang ginawa nito ngayong araw. Binubuksan ng "Manage" ang key; pinapahinto naman ng toggle ang key nang hindi ito binubura.

1. ▶ Kung saan matatagpuan ang iyong mga API key
2. ▶ Isang key na hindi pa tapos ayusin

Isang key na hindi pa tapos ayusin

Ang key na walang naka-map na template ay may "Needs setup" badge. Kaya nitong mag-authenticate, pero hindi ito makakapagpadala ng template message hangga't wala kang ni-map na isa — kaya agad-agad mong nakikita ang isang hindi pa kumpletong integration sa halip na bumagsak ito mamaya sa mismong oras ng pagpapadala.

Gabay sa pag-setup

Hakbang 1 — Ano ang kinokonekta mo?

Binubuksan ng "Connect your software" ang isang wizard na may apat na hakbang. Magsimula sa pagpapangalan sa key batay sa sistemang gagamit nito, at piliin ang preset na tumutugma. Nagmumungkahi lang ang mga preset ng makatuwirang mga field name — nagmumungkahi ang billing ng invoice_number, amount, due_date, customer_name — hindi nila nililimitahan kung ano ang puwede mong i-map.

1. ▶ Hakbang 1 — Ano ang kinokonekta mo?
2. ▶ Hakbang 2 — Piliin ang mensahe
3. ▶ Hakbang 3 — Saan dapat mapunta ang mga sagot?
4. ▶ Hakbang 4 — Mag-go live

Hakbang 2 — Piliin ang mensahe

Pumili ng isa sa iyong mga aprubadong WhatsApp template. Nasa Meta nakatira ang mga template, hindi dito — direktang kinukuha ang listahang ito mula sa iyong nakakonektang WhatsApp account, at ang APPROVED na mga template lang ang puwedeng ipadala. Opsyonal ang hakbang na ito: laktawan ito kung plain text lang naman ang ipinapadala ng key, at mag-map na lang ng template mamaya.

Hakbang 3 — Saan dapat mapunta ang mga sagot?

Kapag may sumagot sa iyong mensahe, o may bumalik na delivery report, ipo-POST namin ito sa isang URL na kontrolado mo. Huwag na itong isama kung puro pagpapadala lang ang ginagawa ng iyong sistema. Puwede mo itong idagdag mamaya mula sa Webhooks tab ng key — walang permanente rito.

Hakbang 4 — Mag-go live

Ang pagpindot ng Next sa nakaraang hakbang ang siyang talagang gumagawa ng key — kumpirmasyon lang ang screen na ito. Kopyahin mo na ngayon ang tatlong value: minsan lang ipinapakita ang API key, ang API secret, at ang webhook signing secret, at hindi na ito mababawi pagkatapos. Kung mawala mo ang secret, kailangan mo itong i-rotate, na ibig sabihin ay kailangan mong i-update ang kahit anong sistemang gumagamit nito.

Pamamahala ng key

Overview

Kapag binuksan mo ang isang key, mapupunta ka sa Overview: kung ano ang puwede nitong gawin, gaano ito kabigat ginagamit, at ang mga endpoint na puwede nitong tawagin. Binabasa ang usage counts mula sa request log, kaya totoong traffic ang ipinapakita ng mga ito.

1. ▶ Overview

Isang key na kailangan pang i-setup

Ang key na walang naka-map na template ay bubukas sa Setup tab — ang parehong wizard, inline lang. Pansinin na iba ang mga tab kumpara sa nakaraang screenshot: hangga't wala pang kahit isang template ang key, hindi inaalok ang Templates at Webhooks, dahil wala pa silang bagay na puwedeng pagtrabahuhan.

1. ▶ Isang key na kailangan pang i-setup

Templates

Ang bawat card ay isang template na puwedeng ipadala ng key na ito. Ang body text ay ang mensahe ayon sa pagkaaproba nito sa Meta, at ang mga chip sa ilalim nito ang mga variable name na ibibigay ng iyong sistema. Nagpapadala ng test ang "Try it", habang gumagawa naman ang "Get code" ng handa nang request sa walong wika.

1. ▶ Templates
2. ▶ Pagbasa ng mga variable — ang isang bagay na dapat pagtuunan ng pansin

Pagbasa ng mga variable — ang isang bagay na dapat pagtuunan ng pansin

Tingnan ang payment_failed_alert card. Ang takbo ng mensahe nito ay {{1}}, tapos {{3}}, tapos {{2}} — HINDI naka-numeric order ang mga placeholder sa teksto. Ang mga chip sa ibaba ay nakalista nang naka-numeric order: customer_name ang pumupuno sa {{1}}, renewal_date ang pumupuno sa {{2}}, plan_name ang pumupuno sa {{3}}. Itugma ang iyong mga value sa NUMERO, hindi kailanman sa pagkakasunod-sunod ng paglabas ng mga placeholder sa pangungusap. Dito madalas nagkakamali ang mga tao sa mga isinaling template, kung saan inililipat ng ayos ng mga salita ang kinalalagyan ng mga placeholder.

Ang tatlong button sa bawat template

"Try it" — magpadala ng test nang hindi nagsusulat ng code

Binubuksan ng paper-plane button ang template na ito na puno na ng sample value, isa sa bawat variable name. Ito ang pinakamabilis na paraan para tiyaking tama ang isang mapping bago pa ito hawakan ng iyong mga developer. Pansinin ang toggle: "Simulate Only" ang default at walang anumang lumalabas — ibinabalik lang sa iyo ng server ang iyong payload. Ilipat ito sa "Send Real Message" at tunay na WhatsApp message ang mapupunta sa numerong nasa kahon, at may bayad ito.

1. ▶ “Try it” — magpadala ng test nang hindi nagsusulat ng code
2. ▶ Ano ang ibinabalik ng isang simulated na pagpapadala
3. ▶ “Get code” — ang request, isinulat na para sa iyo
4. ▶ Pagpapalit ng wika
5. ▶ “Edit” — baguhin ang ipinapadala ng iyong sistema
6. ▶ Test API — parehong kasangkapan, kahit anong endpoint
7. ▶ Webhooks — pagpapabalik ng mga sagot

Ano ang ibinabalik ng isang simulated na pagpapadala

Ang pagpindot ng Send Request sa Simulate Only mode ay nagbabalik ng request ayon sa pagkatanggap dito ng platform, kasama ang HTTP status at round-trip time. Basahin ito bilang tsek sa hugis, hindi bilang ensayo: kinukumpirma nito na na-parse ang iyong JSON at tinanggap ang key, pero HINDI nito bine-validate ang mga variable name mo laban sa mapping at hindi ito kailanman kumokontak sa Meta. Ang payload na malinis sa simulation ay puwede pa ring tanggihan sa totoong pagpapadala. Para patunayan ang mismong mapping, i-on ang Send Real Message at magpadala sa sarili mong telepono.

"Get code" — ang request, isinulat na para sa iyo

Ang angle-brackets button ay gumagawa ng gumaganang request para mismo sa template na ito sa walong wika: cURL, JavaScript, Node.js, Python, PHP, Ruby, Go at C#. Ibigay ito sa kung sino man ang sumusulat ng integration. Lumalabas ang mga variable bilang {{placeholders}} na pinangalanan ayon sa iyong mapping, at naiiwang YOUR_API_KEY / YOUR_API_SECRET ang mga credential — hindi kailanman inilalabas ng dialog na ito ang totoo mong key, kaya ligtas i-paste ang snippet sa isang ticket.

Pagpapalit ng wika

I-click ang kahit anong wika sa itaas at isusulat muli ang snippet para dito — parehong tawag, parehong header, ang HTTP client ng wikang iyon. Ginagawa ang bawat isa sa unang pag-click mo, kaya normal ang maikling spinner sa unang paglipat. Kinukuha ng Copy ang snippet gaya ng nakikita: kumpleto ito, pati mga import, at kung nangangailangan ng signature ang key na ito, nandoon na ang signing step.

"Edit" — baguhin ang ipinapadala ng iyong sistema

Binubuksan ng lapis ang mismong mapping. Ang phone mock-up sa itaas ay ang totoong mensahe na may kapalit na kasalukuyan mong mga pangalan, kaya makikita mo kung ano ang mababasa ng customer. Sa ilalim nito, ang bawat na-detect na variable ay puwedeng palitan ng pangalan, ayusin ang pagkakasunod, markahang required, o bigyan ng type — petsa, halaga ng pera, imahe. Ang pagpapalit ng pangalan ng variable ay nagpapalit din nito sa iyong API payload, kaya magsisimulang bumagsak ang sistemang nagpapadala pa ng lumang pangalan: palitan silang dalawa nang sabay.

Test API — parehong kasangkapan, kahit anong endpoint

Ang "Test API" sa itaas ng tab ay "Try it" na walang kandado sa template: pumili ng kahit alin sa tatlong send endpoint, magpalit ng template mula sa pangalawang dropdown, at malayang i-edit ang body. Gamitin ito para tsekin ang mga hilaw na tawag sa /messages/text o /messages/template, na walang sariling card dahil hindi sila nakatali sa isang mapping. Pansinin na body_1, body_2, body_3 pa rin ang tawag sa mga variable ng template na ito — ganito ang hitsura ng template na walang mapping, at ito ang inaayos ng "Edit".

Mga sagot

Webhooks — pagpapabalik ng mga sagot

Kalahati lang ng integration ang pagpapadala. Ituro ang webhook sa sarili mong HTTPS endpoint at ipo-POST doon ng WizMessage ang mga papasok na mensahe at delivery update. Minsan lang ipinapakita ang signing secret kapag na-generate ito; i-verify ito sa bawat delivery para masigurong talagang sa amin nanggaling ang tawag.

Aling mga kaganapan ang matatanggap mo

Piliin ang mga kaganapang dapat matanggap ng endpoint na ito. Dumarating ang bawat isa bilang sarili nitong POST.

Tandaan: Naihahatid lang ang message.received at ang papasok na message.reaction kapag naka-set sa Webhook ang chatbot system ng account. Kung iba ang naka-set, mapupunta sa bot ang mga papasok na mensahe at hindi kailanman tatawagin ang endpoint mo — nagbabala ang Webhooks tab kapag ganito ang sitwasyon. Ang mga reaction na ipinapadala mismo ng negosyo (direction: "outbound") ay hindi apektado ng setting na ito.

Tandaan: Ang mga reaction na ipinapadala ng negosyo mula sa sarili nitong telepono ay dating dumarating bilang message.sent na ang body ay "[Unsupported message type]". Ngayon dumarating na ang mga ito bilang message.reaction na may direction: "outbound". I-tsek ang bagong event kung umaasa ka roon dati.

At-least-once ang paghahatid. Mag-dedupe gamit ang event kasama ang data.message_id sa halip na ang X-Webhook-Id header lamang, at sumagot ng 2xx agad.

Sanggunian ng REST API

Kino-configure ng lahat ng nasa itaas ang key. Ito naman ang aktuwal na tinatawag ng iyong mga developer. Ang base URL ay https://wizmessage.com/api/v1/external. Kailangan ng bawat endpoint ang mga auth header sa ibaba, at saklaw ito ng rate limits ng key.

Pag-authenticate

Ipadala ang iyong API key sa bawat request. Kung naka-enable ang "Require signature" sa key, kailangan mo ring pirmahan ang request — at agad na tatanggihan ng key na naka-enable ito ang kahit anong hindi pirmadong tawag.

Paalala: Ipinapatupad lang ang mga signature kapag naka-enable ang require_signature sa key. Kung hindi ito naka-enable, sapat na ang API key mag-isa para makapagpadala ng mga mensahe — kaya nga sikreto ang key, hindi isang identifier. Ituring itong parang password: minsan lang itong ipinapakita, at kahit sinong may hawak nito ay puwedeng makapagmensahe sa iyong mga customer.

const crypto = require('node:crypto')

const body = JSON.stringify({ to: '+919876543210', message: 'Hello' })
const timestamp = Math.floor(Date.now() / 1000).toString()

const secretHash = crypto.createHash('sha256').update(API_SECRET).digest('hex')
const signature = crypto.createHmac('sha256', secretHash)
	.update(timestamp + '.' + body)
	.digest('hex')

await fetch('https://wizmessage.com/api/v1/external/messages/text', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json',
		'X-API-Key': API_KEY,
		'X-Timestamp': timestamp,
		'X-API-Signature': signature,
	},
	body,
})

Mga endpoint

Pagpapadala ng naka-map na template

Ito ang payload na katambal ng Templates tab. Ipinapadala mo ang mga variable ayon sa PANGALAN — ang mga pangalang ipinapakita bilang mga chip sa template card — at ang platform na ang bahalang bumuo ng mga component ng Meta para sa iyo. Iyan ang buong punto ng pag-map ng template: hindi na kailangang alam ng iyong billing system ang kahit ano tungkol sa component format ng Meta.

POST /api/v1/external/messages/template/send

{
	"to": "+919876543210",
	"template_name": "payment_failed_alert",
	"language": "en",
	"variables": {
		"customer_name": "Priya Sharma",
		"renewal_date": "12 Aug 2026",
		"plan_name": "Wiz Pro"
	},
	"reference": "invoice-2026-0817"
}

Paalala: Dapat eksaktong tumugma ang mga variable name sa mapping — binabalewala ang hindi nakikilalang pangalan, at tinatanggihan naman nang may 400 ang nawawalang required na pangalan. Sa iyo ang reference: ibinabalik ito sa mga webhook para maiugnay mo ang isang delivery report sa isang record sa sarili mong sistema.

Rate limits

May sariling limits ang bawat key, na makikita sa Overview tab — 60 requests/minute at 1,000 messages/day bilang default. Kasama sa mga response ang natitirang allowance, kaya bumagal na kapag paubos na ito sa halip na paulit-ulit mag-retry hanggang bumangga sa pader.

Pagpapadala ng mga file gamit ang API

Sa loob ng bukás na 24-oras na window, maaaring magpadala ang software mo ng file nang diretso — walang template, walang approval. Isang endpoint ang sumasaklaw sa dokumento, larawan, video at audio.

Ano ang puwede mong ipadala

Ang type na isinasaad mo sa request ang nagtatakda ng limitasyon. Anumang mas malaki, o nasa format na wala sa listahan, ay tinatanggihan bago pa makarating sa WhatsApp.

POST /api/v1/external/messages/media

{
	"to": "+919876543210",
	"type": "document",
	"link": "https://example.com/invoice-2026-0817.pdf",
	"filename": "Invoice 2026-0817.pdf",
	"caption": "Your invoice for August",
	"reference": "invoice-2026-0817"
}

I-upload minsan, ipadala nang paulit-ulit

Kung paulit-ulit mong ipinapadala ang parehong file — price list, katalogo, PDF ng mga tuntunin — i-upload ito minsan at itago ang id. Mananatili itong balido nang 30 araw at hindi na kailangang kunin muli ng WhatsApp ang URL mo sa bawat mensahe.

POST /api/v1/external/messages/media

{
	"to": "+919876543210",
	"type": "image",
	"media_id": "1234567890",
	"caption": "This month’s catalogue"
}

Kailan tinatanggihan ang pagpapadala

• Labas sa 24-oras na window. Kailangan ng bukás na usapan ang freeform media. Magpadala ng aprubadong template — tingnan ang gabay sa shared inbox.
• Walang send_media ang key. Tingnan ang mga permission chip sa Overview tab ng key.
• Caption sa audio. Hindi ito ipinapakita ng WhatsApp, kaya tinatanggihan sa halip na tahimik na itapon.
• Filename sa hindi dokumento. Dokumento lang ang nagpapakita ng pangalan.
• Walang media_id at walang link. Isa lang sa dalawa ang kailangan.

Tandaan: Masusubukan mo ang lahat ng ito nang hindi nagsusulat ng code. Buksan ang key, pindutin ang Test API, at piliin ang POST /messages/media sa listahan ng endpoint — nakahanda na ang body, at isusulat ng "Get code" ang parehong request sa walong wika.

Mga reaction

Ang reaction ay ang emoji na ipinapatong ng isang tao sa iisang mensahe — 👍 sa isang order confirmation, ❤️ sa isang larawan. Hindi ito mensaheng nakatayo mag-isa: itinuturo nito ang isang mensahe. Mababasa ng software mo ang mga reaction habang nangyayari ang mga ito, at makapagpapadala rin ito ng sarili.

Isang event, tatlong pinagmulan

Maaaring galing ang reaction sa customer mo, sa may-ari na pinindot ito sa telepono ng Business app, o sa sarili mong software sa pamamagitan ng API. Pare-parehong dumarating ang tatlo sa iisang event na message.reaction, kaya sapat na ang isang handler para sa lahat — sinasabi ng direction at source kung alin ang nasa harap mo.

Ang hitsura ng isang reaction webhook

Narito ang isang customer na nagdagdag ng 👍 sa mensaheng ipinadala mo sa kanya.

{
	"version": 1,
	"event": "message.reaction",
	"timestamp": "2026-08-01T09:14:22.031Z",
	"data": {
		"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQjkz…",
		"direction": "inbound",
		"from": "+919876543210",
		"to": "+911122334455",
		"reaction": {
			"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…",
			"emoji": "👍",
			"action": "added"
		},
		"contact": {
			"name": "Priya Sharma",
			"wa_id": "919876543210"
		}
	}
}

May dalawang message_id sa payload na iyan at magkaiba ang ibig sabihin ng dalawa. Ito ang field na sulit basahin nang dalawang beses.

Tandaan: Karaniwang numero ng telepono ng customer ang data.from, pero hindi laging nagpapadala ng numero ang WhatsApp. Kapag hindi, ang WhatsApp user id nila ang makukuha mo — kaya ituring ang from bilang pagkakakilanlan, hindi bilang isang bagay na palagi mong matatawagan.

Pagdaragdag at pag-alis ng reaction

Sariling event ang pag-alis ng reaction, may walang lamang emoji at action: "removed".

{
	"event": "message.reaction",
	"data": {
		"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSN0U3…",
		"direction": "inbound",
		"reaction": {
			"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…",
			"emoji": "",
			"action": "removed"
		}
	}
}

Bawat pindot ay hiwalay na mensahe sa WhatsApp na may sariling id. Ang mag-react ng 👍, palitan ito ng ❤️, at saka alisin nang tuluyan ay nagbubunga ng tatlong event, at wala ni isa sa mga ito ang pumapalit sa iba sa imbakan mo. Gamiting susi ang data.reaction.message_id at itago ang pinakabago — iyon ang kasalukuyang reaction ng mensahe.

Pagpapadala ng reaction mula sa software mo

Ang parehong endpoint ang nagdaragdag at nag-aalis. Nakadepende lang kung alin ang mangyayari sa kung nagpapadala ka ba ng emoji.

POST /api/v1/external/messages/reaction

{
	"to": "+919876543210",
	"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…",
	"emoji": "👍",
	"reference": "invoice-2026-0817"
}

Ang message_id dito ay id ng WhatsApp — ang whatsapp_message_id mula sa isang send response, o ang data.reaction.message_id mula sa isang webhook. Hindi kailanman ito isa sa mga uuid namin. Ang permission na send_text ang ginagamit ng mga reaction, kaya kahit anong key na makakapagmensahe sa customer ay makakapag-react.

Tandaan: Hindi kailanman nagbubunga ng message.delivered o message.read ang isang reaction. Hindi ipinapadala ng WhatsApp ang mga iyon para sa reaction — ang tanging kasunod na event na posible ay message.failed, kapag tinanggihan ang reaction. Gumagana ang paghahanap dito sa GET /messages/:uuid gaya ng ibang padala.

Kapag tinanggihan ang isang reaction

May mga pagtanggi na dito nangyayari, bago pa may makarating sa WhatsApp. Nagbabalik ang mga ito ng error sa API call mo at walang anumang webhook na nabubuo — walang maiuulat, dahil walang naipadala.

• Walang send_text ang key. 403. Ginagamit muli ng mga reaction ang permission na iyon; walang hiwalay na ibibigay.
• Hindi E.164 ang to. 422. Parehong +… na format gaya ng ibang endpoint.
• Nawawala o walang laman ang message_id. 422. Hanggang 255 karakter.
• Nawawala ang emoji. 422. Para mag-alis ng reaction ipadala ang "emoji": "" — ipadala ang field na walang laman, huwag itong tanggalin. Hanggang 16 karakter.

Ang iba ay sa WhatsApp nangyayari, matapos naming tanggapin ang tawag. Makakakuha ka muna ng 200 at ng webhook na message.reaction, saka message.failed na may error na 131009 kapag tinanggihan ito ng WhatsApp.

• Mahigit 30 araw na ang mensahe. Limitasyon ito ng WhatsApp sa pag-react, hindi sa amin — hindi namin sinusuri ang edad nito.
• Wala sa usapang ito ang mensahe. wamid mula sa ibang chat, o isa sa mga uuid namin na naipasa nang mali.
• Nabura ang mensahe, o reaction mismo ito. Hindi ka puwedeng mag-react sa isang reaction.

Tandaan: Kung agad na nabigo ang padala sa halip na tanggihan mamaya, makakakuha ka ng 500 at ng message.failed na ang data.message_id ay uuid namin, hindi wamid — walang WhatsApp id na maiuulat, dahil hindi ito kailanman tinanggap ng WhatsApp.

Tandaan: Gaya ng ibang endpoint, masusubukan mo ito nang hindi nagsusulat ng code. Buksan ang key, pindutin ang Test API, at piliin ang POST /messages/reaction — mag-react sa isang mensahe sa sarili mong telepono at panoorin ang pagdating ng webhook.