Jika anda pernah menggunakan WhatsApp Cloud API, anda sudah tahu cara memanggil platform kami. Laluan yang sama, badan JSON yang sama, pengesahan Bearer yang sama — hanya halakan kod anda ke URL asas baharu dan semuanya siap.
02Hantar mesej pertama anda
Mesej teks biasa. Badan mesej adalah muatan standard Cloud API — kami memajukannya terus ke Meta tanpa sebarang perubahan.
cURL
curl -X POST https://api.smartsybox.com/v26.0/PHONE_NUMBER_ID/messages \
-H "Authorization: Bearer YOUR_DEVICE_KEY" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "15551234567",
"type": "text",
"text": { "body": "Hello from SyBox 👋" }
}'
C# · HttpClient
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "YOUR_DEVICE_KEY");
string json = @"{
""messaging_product"": ""whatsapp"",
""to"": ""15551234567"",
""type"": ""text"",
""text"": { ""body"": ""Hello from SyBox"" }
}";
var res = await http.PostAsync(
"https://api.smartsybox.com/v26.0/PHONE_NUMBER_ID/messages",
new StringContent(json, Encoding.UTF8, "application/json"));
Console.WriteLine(await res.Content.ReadAsStringAsync());
Respons API
Anda menerima jawapan tepat seperti yang dikembalikan oleh Meta, lengkap dengan status HTTP yang sama — membolehkan pustaka klien Cloud API sedia ada anda memprosesnya tanpa perubahan.
200 OK · application/json
{
"messaging_product": "whatsapp",
"contacts": [{ "input": "15551234567", "wa_id": "15551234567" }],
"messages": [{ "id": "wamid.HBgLMTU1NTEyMzQ1NjcVAgARGBI…" }]
}
04Pamerkan data sistem anda terus di sebelah sembang
Setiap kali ejen membuka perbualan, SyBox memanggil titik akhir sistem ANDA dan memaparkan maklumat yang dikembalikan tepat di sebelah sembang — pesanan pelanggan, baki akaun, atau tiket sokongan. Kami menghantar nombor telefon pelanggan, atau e-mel mereka untuk perbualan e-mel.
Request · SyBox → your endpoint
POST YOUR_ERP_URL
Authorization: Bearer YOUR_ERP_KEY
X-Sybox-Action: lookup
# body: { "data": "<json string>" } — the decoded "data":
{
"phone": "15551234567",
"email": "customer@example.com",
"ref": ""
}
Your reply · application/json
{
"renderAs": "table",
"content": [
{ "Order": "#10432", "Status": "Shipped", "Total": "$1,250.00" }
]
}
renderAs
Tetapkan renderAs untuk menentukan cara SyBox memaparkan kandungan anda — pilih salah satu:
table
Rows & columns. content = an array of flat objects (or { rows: [ … ] }). Object keys become the column headers.
cards · kpi
Compact tiles (a balance, an order count). content = an array of { label, value } (or { cards: [ … ] }).
feed · list · thread
A timeline of rich cards. content = an array of { title, text, date, tags, media:[{ type, url, name }] }.
message
A single message-style card (one record laid out as a note).
html
Your own trusted HTML — content = a string. Use only for markup you generate yourself.
sections
Several blocks at once: content = { sections: [ { title, renderAs, content } ] } — mix a table + cards + a feed in one reply.
json
The default when renderAs is omitted — SyBox pretty-prints your content as-is.
Tambah sybox_ref pada mana-mana baris jadual atau kad untuk menjadikannya boleh diklik — SyBox akan memanggil sistem anda semula dengan rujukan tersebut untuk memaparkan butiran rekod berkenaan.
Kami menghantar nombor telefon dan e-mel — salah satu mungkin kosong. Padankan dengan maklumat yang mengenal pasti pelanggan dalam sistem anda, dan balas dengan { renderAs, content }.
Carian produk (X-Sybox-Action: products)
Titik akhir yang sama juga boleh mengendalikan carian produk. Ejen hanya perlu menaip apa yang dicari oleh pelanggan, SyBox menghantarnya dalam parameter "q", dan respons anda dipaparkan sebagai kad produk kemas di sebelah sembang — lengkap dengan butang Hantar satu klik yang memasukkan pautan produk terus ke ruangan mesej.
Request · SyBox → your endpoint
POST YOUR_ERP_URL
Authorization: Bearer YOUR_ERP_KEY
X-Sybox-Action: products
# body: { "data": "<json string>" } — the decoded "data":
{
"q": "wireless keyboard",
"phone": "15551234567",
"email": "customer@example.com",
"ref": ""
}
Your reply · application/json
{
"content": [
{
"name": "Wireless Keyboard K380",
"price": 449,
"oldPrice": 520,
"currency": "USD",
"available": true,
"stock": 12,
"image": "https://cdn.example.com/k380.jpg",
"link": "https://shop.example.com/p/k380",
"note": "Ships in 24h"
}
]
}
name
Satu-satunya medan wajib. Produk yang hanya mempunyai nama tetap akan dipaparkan sebagai kad yang kemas.
price · oldPrice · currency
Gunakan nilai angka, bukan rentetan berformat. Hantar oldPrice hanya jika terdapat harga asal sebenar — lencana diskaun akan dikira secara automatik daripada perbandingan kedua-duanya.
available · stock
available bernilai true/false; manakala stock ialah jumlah pilihan yang dipaparkan di sebelahnya. Abaikan kedua-duanya jika anda tidak menguruskan inventori — medan yang tiada tidak akan memaparkan apa-apa dan tidak sekali-kali dianggap sebagai kehabisan stok.
image
Pautan imej https langsung. Sebarang imej yang gagal dimuatkan akan digantikan secara automatik dengan latar belakang neutral.
link
Pautan ke halaman produk. Tanpanya kad hanya untuk paparan — butang Hantar ke sembang hanya muncul apabila terdapat sesuatu untuk dihantar.
note
Satu baris teks ringkas di bawah harga — tempoh penghantaran, pilihan varian, atau syarat promosi.
Hanya gunakan titik akhir yang telah anda bina: URL yang sama, kunci yang sama, dan format { "data": "…" } yang sama. Rujuk pengepala X-Sybox-Action untuk membezakan antara carian produk dan semakan pelanggan. Balas dengan content dalam bentuk tatasusunan mudah (atau { items: [ … ] }).
05Buka kes sokongan terus daripada sistem anda
Ini ialah laluan yang digunakan oleh sistem ERP atau perakaunan anda. Perisian anda tidak perlu menghantar mesej biasa tentang aduan — sebaliknya ia meminta SyBox membuka kes secara rasmi. Satu rekod terpusat, satu tempat rujukan, dan satu nombor tiket yang boleh dirujuk oleh pasukan anda kepada pelanggan.
cURL
curl -X POST "https://api.smartsybox.com/v1/case" \
-H "Authorization: Bearer $SYBOX_CASE_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer_unique_id": "CUST-10432",
"header": "Screen replacement not delivered",
"description": "Paid on 12 Aug, promised in 3 days, still nothing.",
"ext_ref": "TICKET-99817"
}'
Medan data yang diperlukan
customer_unique_id
ID rekod pelanggan dalam sistem anda — kunci rujukan yang sama seperti penyelarasan pelanggan. Jika tiada ID, sistem akan menggunakan nombor telefon secara automatik.
header / description
Sekurang-kurangnya satu medan diperlukan. Tajuk ini ialah baris maklumat yang dilihat oleh pasukan anda dalam senarai.
ext_ref
Nombor tiket sistem anda. Sebarang cubaan semula dengan ext_ref yang sama akan mengembalikan kes sedia ada dan bukan mencipta salinan baharu — menjadikannya selamat untuk diulang jika berlaku tamat masa sambungan.
Pelanggan mestilah sudah wujud dalam sistem. Permintaan kes untuk pelanggan yang tidak ditemui akan ditolak bagi mengelakkan kekeliruan data. Cipta rekod pelanggan melalui POST /v1/sync terlebih dahulu.
Gunakan kunci jenis 'case'. Kunci penghantaran mesej biasa sengaja ditolak dengan ralat 403 demi keselamatan: kunci yang menghantar mesej kepada pelanggan tidak sepatutnya mempunyai akses untuk mengubah rekod sokongan dalam CRM anda.