Developer API & Webhooks
The HK Reach Developer API allows you to programmatically send WhatsApp messages and receive real-time events in your own applications.
🛠️ Technical Administrator's Guide (Deep-Dive)
This section is intended for developers building integrations with HK Reach.
1. Authentication
All API requests must include the following headers for authentication:
| Header | Description |
|---|---|
X-App-Name | Your unique HK Reach application identifier. |
X-API-Key | Your secret API key (found in App Settings). |
2. Sending Messages (Templates)
To send a WhatsApp template, use the send/template endpoint. HK Reach automatically handles media downloads and Meta API formatting.
Endpoint: POST /api/external/send/template
Request Body:
{
"to": "919999999999",
"templateName": "order_confirmation",
"languageCode": "en",
"thirdPartyAppName": "MyStore_ERP",
"bodyParams": ["John Doe", "ORD-12345"],
"headerText": "Thank you for your order!"
}
3. Sending Templates with Media
You can also send templates that have Image, Video, or Document headers.
Endpoint: POST /api/external/send/document
Format: multipart/form-data
| Parameter | Type | Description |
|---|---|---|
file | File | The document or image to send as the header. |
to | String | Recipient phone number with country code. |
templateName | String | Name of the template in Meta. |
headerMediaFilename | String | (Optional) The name the user will see for the document. |
4. Real-time Webhooks
HK Reach can push events (like status updates or new messages) to your server in real-time.
Webhook Security
If a WebhookSecret is configured, HK Reach signs every payload using HMAC-SHA256. You should verify this signature to ensure the request is genuine.
- Signature Header:
X-HKReach-Signature - Verification: Compute the HMAC-SHA256 of the raw JSON body using your secret and compare it to the header.
Supported Events
messages.received: Triggered when a customer sends a message.messages.status: Triggered when a message status changes (sent,delivered,read,failed).leads.status: Triggered when a lead moves through the pipeline.
5. Message Status Tracking
You can poll for the status of any message using the messageId returned in the send response.
Endpoint: GET /api/external/message/status?messageId={ID}
Response:
{
"status": "read",
"messageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
[!NOTE] HK Reach maintains an internal "Outbox" that handles retries and logging. Even if the Meta API is temporarily down, HK Reach will queue your message and attempt delivery once the connection is restored.