1Base URL and authentication
Every request uses HTTPS and sends your API key as a bearer token in the Authorization header. You find the key in your dashboard under Website connection.
https://app.tskin.sa/api/v1/send-message.phpPOST /api/v1/send-message.php HTTP/1.1
Host: app.tskin.sa
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json2Send a template message
Send an approved Meta template, such as an order update, a verification code or an appointment reminder. Templates work at any time, even when the customer hasn't messaged you.
| Field | Type | Description | |
|---|---|---|---|
phone | string | Required | Number with country code, digits only, e.g. 966500000000. |
message_type | string | Required | "template" for templates. |
template_name | string | Required | The approved template name. |
language | string | Optional | Template language code, e.g. "ar" or "en_US". Defaults to your account language. |
params | array | Optional | Values for the body variables {{1}}, {{2}}… in order. |
{
"phone": "966500000000",
"message_type": "template",
"template_name": "order_update_notice",
"language": "ar",
"params": ["10024", "Leather Handbag", "250 SAR"]
}{
"status": "success",
"message_id": "wamid.HBgLOTY2...",
"recipient": "966500000000",
"type": "template"
}3Send a text message
Send free text when the customer has messaged you in the last 24 hours. Outside that window WhatsApp only accepts templates.
| Field | Type | Description | |
|---|---|---|---|
phone | string | Required | Number with country code. |
message_type | string | Optional | "text" (the default). |
message | string | Required | The message text. |
{
"phone": "966500000000",
"message_type": "text",
"message": "Hello! How can we help with your order today?"
}4Code examples
The same template request in four languages.
curl -X POST "https://app.tskin.sa/api/v1/send-message.php" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"phone":"966500000000","message_type":"template","template_name":"order_update_notice","language":"ar","params":["10024","Leather Handbag","250 SAR"]}'<?php
$apiKey = "YOUR_API_KEY";
$url = "https://app.tskin.sa/api/v1/send-message.php";
$payload = [
"phone" => "966500000000",
"message_type" => "template",
"template_name" => "order_update_notice",
"language" => "ar",
"params" => ["10024", "Leather Handbag", "250 SAR"],
];
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer {$apiKey}",
"Content-Type: application/json",
],
CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;const axios = require('axios');
axios.post('https://app.tskin.sa/api/v1/send-message.php', {
phone: '966500000000',
message_type: 'template',
template_name: 'order_update_notice',
language: 'ar',
params: ['10024', 'Leather Handbag', '250 SAR']
}, {
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
})
.then(res => console.log(res.data))
.catch(err => console.error(err.response ? err.response.data : err.message));import requests
url = "https://app.tskin.sa/api/v1/send-message.php"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
}
payload = {
"phone": "966500000000",
"message_type": "template",
"template_name": "order_update_notice",
"language": "ar",
"params": ["10024", "Leather Handbag", "250 SAR"],
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())5Signing requests (optional)
For extra protection, sign each request with your API key. When both headers are present, we reject a request whose signature doesn't match or whose timestamp is more than 10 minutes old.
The signature is HMAC-SHA256(body + timestamp, api_key) in hex.
$body = json_encode($payload, JSON_UNESCAPED_UNICODE);
$timestamp = (string) time();
$signature = hash_hmac('sha256', $body . $timestamp, $apiKey);
// send these two headers with the request (use the same $body)
// X-Tskin-Timestamp: $timestamp
// X-Tskin-Signature: $signature6Status codes
Errors return {"status": "error", "message": "…"} with one of these codes:
| Code | Meaning | What to do |
|---|---|---|
| 200 | OK | The message was accepted and sent to WhatsApp. |
| 400 | Bad Request | Check the JSON, the phone format, and the required fields. |
| 401 | Unauthorized | The API key is missing or wrong, or WhatsApp isn't connected on the account. |
| 403 | Forbidden | The account is inactive, the subscription expired, or the signature is invalid. |
| 500 | Server Error | WhatsApp returned an error (see details) or something failed on our side. Try again. |
Need help with the integration? support@tskin.sa
Email us