Overview
| Base URL | https://tavrosconnect.com/api/v1/ (Meta-style https://tavrosconnect.com/v23.0/ works too) |
|---|---|
| Authentication | Authorization: Bearer tc_live_… (or tc_test_… for test mode) |
| Format | HTTPS + JSON, UTF-8. Request and response bodies are exactly Meta’s WhatsApp Cloud API. |
| Languages | Any language that can make an HTTPS request — PHP, Python, Node.js, Java, C#/.NET, Go, Ruby, VB, Delphi… (TLS 1.2 or newer). |
| Receiving | We forward WhatsApp events (customer messages, delivery/read statuses, template updates) to your HTTPS URL, signed with X-Hub-Signature-256. |
Everything sent through the API also appears in your Tavros Connect Chats, so your team can see and continue the conversation.
| Endpoint | What it does | Key permission |
|---|---|---|
POST /{phone-number-id}/messages | Send any message type; mark a message as read | Send messages |
POST /{phone-number-id}/media | Upload an image / document / video / audio → media id | Media |
GET /{media-id}, GET /{media-id}/download | Info and bytes of media a customer sent you | Media |
GET /{waba-id}/message_templates | Your templates and their approval status | Templates |
POST /{waba-id}/message_templates | Create a template and submit it to Meta | Manage templates |
POST /{template-id} | Edit a template | Manage templates |
DELETE /{waba-id}/message_templates?name= | Delete a template | Manage templates |
POST /contacts | Save customer names / tags (shown in Chats) | Contacts |
GET /messages/{wamid} | Delivery status of one message (sent / delivered / read / failed, Meta’s timestamps) | Send messages |
POST /messages/status:batch | The same for up to 100 wamids | Send messages |
GET /messages | Sweep the messages you sent, with their status (cursor paging) | Send messages |
POST /webhooks/replay | Re-send stored status events to your webhook | Send messages |
GET /webhooks/deliveries | Every webhook attempt we made, with the HTTP code your server returned | Send messages |
POST /test/inbound | Test keys only: send a fake customer message to your webhook | Send messages |
Quick start — first message in 5 minutes
- Create an account and connect your WhatsApp number (Connect WhatsApp in the menu).
- Open Developers / API → Create API key → choose Test. Copy the key (
tc_test_…) — it is shown only once. Store it in an environment variable, e.g.TAVROS_API_KEY. - On the same page, copy your Phone number ID (it goes in the URL).
- Run the send a template example below. With a test key you get a fake message id and nothing is sent — perfect for building.
- When it works, create a Live key (
tc_live_…) and use it in production. Nothing else changes.
API keys & security
Live key tc_live_… | Test key tc_test_… | |
|---|---|---|
| Sends real WhatsApp messages | Yes | No — validated, then answered with a fake id |
| Meta message charges (billed by Meta to your account) | Yes (templates) | Never |
| Appears in Chats | Yes | No |
| Webhook events | Real events from WhatsApp | Simulated sent / delivered / read |
| Rate limit | By your package — see Rate limits | 60 requests / minute |
| How many keys | Bronze 1 · Silver 3 · Gold 10 | Don’t count toward the package’s keys |
- One secret key, no public key. Every request is made from your server, so a single secret key is enough. Never put a key in a website, a mobile app or a public repository.
- Permissions: when you create a key, tick only what it needs — Send messages, Media, Templates, Contacts. A billing system that only sends receipts needs just Send messages and Media.
- IP allowlist: optionally list your server’s public IPs (or ranges like
203.0.113.0/24, IPv6 too). Calls from any other IP get403— a stolen key is useless elsewhere. The API usage page shows the IPs that are calling you. - Rotation: create a new key, deploy it, then revoke the old one. Revoking takes effect immediately.
- Keys are stored only as a SHA-256 hash; we can’t show a key again after it is created.
Send a template message
Replace payment_receipt_v1, the language and the variables with one of your approved templates. The number of body parameters must match the {{1}}, {{2}}… in the template.
curl -X POST 'https://tavrosconnect.com/api/v1/PHONE_NUMBER_ID/messages' \
-H "Authorization: Bearer $TAVROS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"to": "919876543210",
"type": "template",
"template": {
"name": "payment_receipt_v1",
"language": { "code": "en" },
"components": [{ "type": "body", "parameters": [
{ "type": "text", "text": "Priya" },
{ "type": "text", "text": "2499" } ] }]
}
}'<?php
$apiKey = getenv('TAVROS_API_KEY'); // tc_test_… while building, tc_live_… in production
$body = [
'messaging_product' => 'whatsapp',
'to' => '919876543210',
'type' => 'template',
'template' => [
'name' => 'payment_receipt_v1',
'language' => ['code' => 'en'],
'components' => [[
'type' => 'body',
'parameters' => [
['type' => 'text', 'text' => 'Priya'],
['type' => 'text', 'text' => '2499'],
],
]],
],
];
$ch = curl_init('https://tavrosconnect.com/api/v1/PHONE_NUMBER_ID/messages');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey, 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($body),
]);
$res = json_decode((string) curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status === 200) {
echo 'Sent: ' . $res['messages'][0]['id']; // save this wamid to match webhook statuses
} else {
echo 'Error ' . $res['error']['code'] . ': ' . $res['error']['message'];
}import os
import requests # pip install requests
API_KEY = os.environ["TAVROS_API_KEY"] # tc_test_… while building, tc_live_… in production
body = {
"messaging_product": "whatsapp",
"to": "919876543210",
"type": "template",
"template": {
"name": "payment_receipt_v1",
"language": {"code": "en"},
"components": [{"type": "body", "parameters": [
{"type": "text", "text": "Priya"},
{"type": "text", "text": "2499"},
]}],
},
}
r = requests.post("https://tavrosconnect.com/api/v1/PHONE_NUMBER_ID/messages", json=body,
headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
data = r.json()
if r.ok:
print("Sent:", data["messages"][0]["id"]) # save this wamid to match webhook statuses
else:
print("Error", data["error"]["code"], data["error"]["message"])// Node.js 18+ (built-in fetch)
const API_KEY = process.env.TAVROS_API_KEY; // tc_test_… while building, tc_live_… in production
const res = await fetch("https://tavrosconnect.com/api/v1/PHONE_NUMBER_ID/messages", {
method: "POST",
headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
messaging_product: "whatsapp",
to: "919876543210",
type: "template",
template: {
name: "payment_receipt_v1",
language: { code: "en" },
components: [{ type: "body", parameters: [
{ type: "text", text: "Priya" },
{ type: "text", text: "2499" },
] }],
},
}),
});
const data = await res.json();
if (res.ok) console.log("Sent:", data.messages[0].id); // save this wamid to match webhook statuses
else console.error("Error", data.error.code, data.error.message);// Java 15+ (java.net.http)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class SendTemplate {
public static void main(String[] args) throws Exception {
String apiKey = System.getenv("TAVROS_API_KEY"); // tc_test_… while building, tc_live_… in production
String json = """
{
"messaging_product": "whatsapp",
"to": "919876543210",
"type": "template",
"template": {
"name": "payment_receipt_v1",
"language": { "code": "en" },
"components": [{ "type": "body", "parameters": [
{ "type": "text", "text": "Priya" },
{ "type": "text", "text": "2499" } ] }]
}
}""";
HttpRequest req = HttpRequest.newBuilder(URI.create("https://tavrosconnect.com/api/v1/PHONE_NUMBER_ID/messages"))
.header("Authorization", "Bearer " + apiKey)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
// 200 → {"messaging_product":"whatsapp","contacts":[…],"messages":[{"id":"wamid…"}]}
System.out.println(res.statusCode() + " " + res.body());
}
}// .NET 6+
using System.Net.Http.Headers;
using System.Net.Http.Json;
var apiKey = Environment.GetEnvironmentVariable("TAVROS_API_KEY"); // tc_test_… / tc_live_…
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
var body = new {
messaging_product = "whatsapp",
to = "919876543210",
type = "template",
template = new {
name = "payment_receipt_v1",
language = new { code = "en" },
components = new[] { new {
type = "body",
parameters = new[] {
new { type = "text", text = "Priya" },
new { type = "text", text = "2499" },
}
} }
}
};
var res = await http.PostAsJsonAsync("https://tavrosconnect.com/api/v1/PHONE_NUMBER_ID/messages", body);
// 200 → {"messaging_product":"whatsapp","contacts":[…],"messages":[{"id":"wamid…"}]}
Console.WriteLine($"{(int)res.StatusCode} {await res.Content.ReadAsStringAsync()}");package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
"os"
)
func main() {
body, _ := json.Marshal(map[string]any{
"messaging_product": "whatsapp",
"to": "919876543210",
"type": "template",
"template": map[string]any{
"name": "payment_receipt_v1",
"language": map[string]string{"code": "en"},
"components": []any{map[string]any{
"type": "body",
"parameters": []any{
map[string]string{"type": "text", "text": "Priya"},
map[string]string{"type": "text", "text": "2499"},
},
}},
},
})
req, _ := http.NewRequest("POST", "https://tavrosconnect.com/api/v1/PHONE_NUMBER_ID/messages", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("TAVROS_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
// 200 → {"messaging_product":"whatsapp","contacts":[…],"messages":[{"id":"wamid…"}]}
fmt.Println(res.StatusCode, string(out))
}Response
{
"messaging_product": "whatsapp",
"contacts": [{ "input": "919876543210", "wa_id": "919876543210" }],
"messages": [{ "id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSN0Y…", "message_status": "accepted" }]
}200 means WhatsApp accepted the message. Whether it was delivered and read arrives later as a webhook status with the same id.
Tip — customer names: add the header X-Contact-Name: Rahul%20Patil (URL-encoded) to any send, and Chats shows the name instead of the bare number.
Header media, buttons, currency/date parameters work exactly as in Meta’s template message reference — e.g. a PDF header: {"type":"header","parameters":[{"type":"document","document":{"id":"MEDIA_ID","filename":"Receipt.pdf"}}]}.
Other message types
Every send is the same request as above — POST /{phone-number-id}/messages — only the JSON body changes. Free-form messages (everything except templates) can only be sent within 24 hours of the customer’s last message.
Text
{ "messaging_product": "whatsapp", "to": "919876543210", "type": "text",
"text": { "body": "Your order #1042 is ready for pickup 🎉", "preview_url": false } }Image or document from a public URL
{ "messaging_product": "whatsapp", "to": "919876543210", "type": "image",
"image": { "link": "https://example.com/offer.jpg", "caption": "Diwali offer" } }Document you uploaded (see Upload media)
{ "messaging_product": "whatsapp", "to": "919876543210", "type": "document",
"document": { "id": "MEDIA_ID", "filename": "Receipt-1042.pdf", "caption": "Your receipt" } }Reply buttons (up to 3)
{ "messaging_product": "whatsapp", "to": "919876543210", "type": "interactive",
"interactive": {
"type": "button",
"body": { "text": "Confirm your appointment on 12 Oct, 5 PM?" },
"action": { "buttons": [
{ "type": "reply", "reply": { "id": "yes", "title": "Yes, confirm" } },
{ "type": "reply", "reply": { "id": "no", "title": "Reschedule" } } ] } } }Location
{ "messaging_product": "whatsapp", "to": "919876543210", "type": "location",
"location": { "latitude": 16.705, "longitude": 74.2433, "name": "FitZone Gym", "address": "Rajarampuri, Kolhapur" } }Mark a received message as read (blue ticks)
{ "messaging_product": "whatsapp", "status": "read", "message_id": "wamid.HBgM…" }Upload media
Upload a file once, get a media id, then send it in as many messages as you like (ids stay valid for 30 days). Max sizes: images 5 MB, documents 100 MB, video/audio 16 MB.
curl -X POST 'https://tavrosconnect.com/api/v1/PHONE_NUMBER_ID/media' \
-H "Authorization: Bearer $TAVROS_API_KEY" \
-F messaging_product=whatsapp \
-F type=application/pdf \
-F 'file=@Receipt.pdf;type=application/pdf'
# → {"id":"1234567890123456"} — use it as "document": {"id": "…"} in a send<?php
$ch = curl_init('https://tavrosconnect.com/api/v1/PHONE_NUMBER_ID/media');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('TAVROS_API_KEY')],
CURLOPT_POSTFIELDS => [
'messaging_product' => 'whatsapp',
'type' => 'application/pdf',
'file' => new CURLFile('Receipt.pdf', 'application/pdf', 'Receipt.pdf'),
],
]);
$mediaId = json_decode((string) curl_exec($ch), true)['id'];with open("Receipt.pdf", "rb") as f:
r = requests.post(
"https://tavrosconnect.com/api/v1/PHONE_NUMBER_ID/media",
headers={"Authorization": f"Bearer {API_KEY}"},
data={"messaging_product": "whatsapp", "type": "application/pdf"},
files={"file": ("Receipt.pdf", f, "application/pdf")},
timeout=60,
)
media_id = r.json()["id"]import { readFile } from "node:fs/promises";
const form = new FormData();
form.append("messaging_product", "whatsapp");
form.append("type", "application/pdf");
form.append("file", new Blob([await readFile("Receipt.pdf")], { type: "application/pdf" }), "Receipt.pdf");
const res = await fetch("https://tavrosconnect.com/api/v1/PHONE_NUMBER_ID/media", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.TAVROS_API_KEY}` },
body: form,
});
const { id: mediaId } = await res.json();String boundary = "----tavros" + System.currentTimeMillis();
byte[] file = Files.readAllBytes(Path.of("Receipt.pdf"));
var out = new ByteArrayOutputStream();
String head = "--" + boundary + "\r\nContent-Disposition: form-data; name=\"messaging_product\"\r\n\r\nwhatsapp\r\n"
+ "--" + boundary + "\r\nContent-Disposition: form-data; name=\"type\"\r\n\r\napplication/pdf\r\n"
+ "--" + boundary + "\r\nContent-Disposition: form-data; name=\"file\"; filename=\"Receipt.pdf\"\r\n"
+ "Content-Type: application/pdf\r\n\r\n";
out.write(head.getBytes(StandardCharsets.UTF_8));
out.write(file);
out.write(("\r\n--" + boundary + "--\r\n").getBytes(StandardCharsets.UTF_8));
HttpRequest req = HttpRequest.newBuilder(URI.create("https://tavrosconnect.com/api/v1/PHONE_NUMBER_ID/media"))
.header("Authorization", "Bearer " + System.getenv("TAVROS_API_KEY"))
.header("Content-Type", "multipart/form-data; boundary=" + boundary)
.POST(HttpRequest.BodyPublishers.ofByteArray(out.toByteArray()))
.build();
String json = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString()).body();
// json = {"id":"1234567890123456"}using System.Text.Json;
using var form = new MultipartFormDataContent();
form.Add(new StringContent("whatsapp"), "messaging_product");
form.Add(new StringContent("application/pdf"), "type");
var file = new ByteArrayContent(await File.ReadAllBytesAsync("Receipt.pdf"));
file.Headers.ContentType = new MediaTypeHeaderValue("application/pdf");
form.Add(file, "file", "Receipt.pdf");
var res = await http.PostAsync("https://tavrosconnect.com/api/v1/PHONE_NUMBER_ID/media", form);
var mediaId = (await res.Content.ReadFromJsonAsync<JsonElement>()).GetProperty("id").GetString();var buf bytes.Buffer
w := multipart.NewWriter(&buf)
w.WriteField("messaging_product", "whatsapp")
w.WriteField("type", "application/pdf")
h := make(textproto.MIMEHeader)
h.Set("Content-Disposition", `form-data; name="file"; filename="Receipt.pdf"`)
h.Set("Content-Type", "application/pdf")
part, _ := w.CreatePart(h)
data, _ := os.ReadFile("Receipt.pdf")
part.Write(data)
w.Close()
req, _ := http.NewRequest("POST", "https://tavrosconnect.com/api/v1/PHONE_NUMBER_ID/media", &buf)
req.Header.Set("Authorization", "Bearer "+os.Getenv("TAVROS_API_KEY"))
req.Header.Set("Content-Type", w.FormDataContentType())
res, _ := http.DefaultClient.Do(req)
var out struct {
ID string `json:"id"`
}
json.NewDecoder(res.Body).Decode(&out)Media your customers send you arrives in the webhook as an id. GET /{media-id} returns its details with a url on our domain; download it with the same API key (GET /{media-id}/download).
List templates
Returns your templates with their status (APPROVED, PENDING, REJECTED) and components. Filters: name, status, category, language, limit; paging with after.
curl 'https://tavrosconnect.com/api/v1/WABA_ID/message_templates?status=APPROVED&limit=50' \
-H "Authorization: Bearer $TAVROS_API_KEY"<?php
$ch = curl_init('https://tavrosconnect.com/api/v1/WABA_ID/message_templates?status=APPROVED&limit=50');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('TAVROS_API_KEY')]]);
foreach (json_decode((string) curl_exec($ch), true)['data'] as $t) {
echo $t['name'] . ' (' . $t['language'] . ') ' . $t['status'] . "\n";
}r = requests.get("https://tavrosconnect.com/api/v1/WABA_ID/message_templates",
params={"status": "APPROVED", "limit": 50},
headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
for t in r.json()["data"]:
print(t["name"], t["language"], t["status"])const res = await fetch("https://tavrosconnect.com/api/v1/WABA_ID/message_templates?status=APPROVED&limit=50", {
headers: { Authorization: `Bearer ${process.env.TAVROS_API_KEY}` },
});
for (const t of (await res.json()).data) console.log(t.name, t.language, t.status);Read one template’s status: ?name=order_ready&fields=name,language,status,category,rejected_reason — rejected_reason is filled when Meta rejects it.
Create, edit and delete templates
Needs the key permission Manage templates (tick it under Developers → your key → Edit access). Bodies are Meta’s. With a live key these are real submissions to Meta; with a test key they are only validated and nothing is sent or saved (you get a fake id and status PENDING). Meta’s review result arrives on your webhook as message_template_status_update (APPROVED / REJECTED with a reason), and you can also poll the status with the list call above.
# Create + submit. Every {{n}} in the BODY needs a sample in example.body_text.
curl -X POST 'https://tavrosconnect.com/api/v1/WABA_ID/message_templates' \
-H "Authorization: Bearer $TAVROS_API_KEY" -H 'Content-Type: application/json' \
-d '{ "name": "order_ready", "language": "en", "category": "UTILITY",
"components": [ { "type": "BODY", "text": "Hi {{1}}, your order {{2}} is ready.",
"example": { "body_text": [["Rahul", "A-1042"]] } } ] }'
# → {"id":"1234567890","status":"PENDING","category":"UTILITY"}
# Edit (Meta re-reviews it; status goes back to PENDING)
curl -X POST 'https://tavrosconnect.com/api/v1/TEMPLATE_ID' -H "Authorization: Bearer $TAVROS_API_KEY" -H 'Content-Type: application/json' \
-d '{ "components": [ { "type": "BODY", "text": "Hello {{1}}, order {{2}} is ready.", "example": { "body_text": [["Rahul", "A-1042"]] } } ] }'
# → {"success":true}
# Delete (all languages of the name; add &hsm_id=TEMPLATE_ID for one language)
curl -X DELETE 'https://tavrosconnect.com/api/v1/WABA_ID/message_templates?name=order_ready' -H "Authorization: Bearer $TAVROS_API_KEY"
# → {"success":true}Templates with an image, video or document header
A header of format IMAGE, VIDEO or DOCUMENT needs a sample file for Meta’s review. Meta only takes a sample as an upload handle from its own upload API, which is not exposed to API users — so Tavros does that step for you. Two ways:
- Send a link (simplest). Put a public
https://link to a sample file inexample.header_url. Tavros downloads it, uploads it to Meta and submits the template with the resulting handle. Allowed samples: JPEG/PNG up to 5 MB (IMAGE), MP4 up to 16 MB (VIDEO), PDF up to 20 MB (DOCUMENT). The link must be public (no login, no private network address) and on port 443; keep it live until the call returns. - Upload the file.
POST /{waba-id}/message_template_sampleswith a multipart fieldfilereturns{"h": "…"}; pass it asexample.header_handle.
# 1) Link: Tavros fetches the sample for you
curl -X POST 'https://tavrosconnect.com/api/v1/WABA_ID/message_templates' \
-H "Authorization: Bearer $TAVROS_API_KEY" -H 'Content-Type: application/json' \
-d '{ "name": "membership_invoice_pdf", "language": "en", "category": "UTILITY",
"components": [
{ "type": "HEADER", "format": "DOCUMENT",
"example": { "header_url": ["https://example.com/sample-invoice.pdf"] } },
{ "type": "BODY", "text": "Hi {{1}}, your invoice {{2}} is attached.",
"example": { "body_text": [["Priya", "INV-0001"]] } } ] }'
# → {"id":"1234567890","status":"PENDING","category":"UTILITY"}
# 2) Upload: get a handle, then use it as example.header_handle
curl -X POST 'https://tavrosconnect.com/api/v1/WABA_ID/message_template_samples' \
-H "Authorization: Bearer $TAVROS_API_KEY" -F file=@sample-invoice.pdf
# → {"h":"4::aW1hZ2U6..."}
# Sending it later: the header parameter goes in the message, as on Meta's Cloud API
curl -X POST 'https://tavrosconnect.com/api/v1/PHONE_NUMBER_ID/messages' \
-H "Authorization: Bearer $TAVROS_API_KEY" -H 'Content-Type: application/json' \
-d '{ "messaging_product": "whatsapp", "to": "919876543210", "type": "template",
"template": { "name": "membership_invoice_pdf", "language": { "code": "en" },
"components": [
{ "type": "header", "parameters": [ { "type": "document",
"document": { "link": "https://example.com/invoice-0001.pdf", "filename": "Invoice.pdf" } } ] },
{ "type": "body", "parameters": [ { "type": "text", "text": "Priya" }, { "type": "text", "text": "INV-0001" } ] } ] } }'Errors come back in Meta’s format, e.g. (#100) Invalid parameter: a DOCUMENT header needs a sample or … a DOCUMENT header sample must be application/pdf, but the link gave text/html. Test keys download and check the sample the same way but upload nothing to Meta. Editing a media-header template (POST /{template-id}) accepts header_url too. The PHONE_NUMBER_ID is the id of your number as listed in Tavros Connect (the same id /messages and /media use), not the phone number itself.
Save contacts
A Tavros Connect extension (not in Meta’s API): send your customers’ names and tags so Chats and campaigns show names. Up to 1,000 per call; existing numbers are updated, never duplicated. Numbers without a country code are treated as Indian (+91).
curl -X POST 'https://tavrosconnect.com/api/v1/contacts' \
-H "Authorization: Bearer $TAVROS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "contacts": [
{ "phone": "919876543210", "name": "Rahul Patil", "tags": ["members"] },
{ "phone": "9123456789", "name": "Sneha Joshi" } ] }'
# → {"success":true,"created":1,"updated":1,"invalid":0,"over_limit":0,"contacts":[…]}<?php
$ch = curl_init('https://tavrosconnect.com/api/v1/contacts');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('TAVROS_API_KEY'), 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['contacts' => [
['phone' => '919876543210', 'name' => 'Rahul Patil', 'tags' => ['members']],
['phone' => '9123456789', 'name' => 'Sneha Joshi'],
]]),
]);
print_r(json_decode((string) curl_exec($ch), true));r = requests.post("https://tavrosconnect.com/api/v1/contacts", headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30, json={
"contacts": [
{"phone": "919876543210", "name": "Rahul Patil", "tags": ["members"]},
{"phone": "9123456789", "name": "Sneha Joshi"},
]
})
print(r.json())const res = await fetch("https://tavrosconnect.com/api/v1/contacts", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.TAVROS_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ contacts: [
{ phone: "919876543210", name: "Rahul Patil", tags: ["members"] },
{ phone: "9123456789", name: "Sneha Joshi" },
] }),
});
console.log(await res.json());Webhooks — receive messages and statuses
- Build an HTTPS endpoint on your server (examples below).
- In Tavros Connect → Developers / API → Webhook, enter its URL, a verify token (any string you choose) and a signing secret. Press Verify and save — we call your URL with
GET ?hub.mode=subscribe&hub.verify_token=…&hub.challenge=123and your endpoint must answer with the challenge. - From then on we
POSTevery event to your URL, signed:X-Hub-Signature-256: sha256=HMAC_SHA256(raw body, signing secret). Always check it. - Answer
200within 10 seconds (do heavy work afterwards). Failed deliveries are retried 9 times over about 34 hours (1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h, 12 h) and listed under Recent webhook deliveries — and, with every attempt and your HTTP code, inGET /webhooks/deliveries.
| Event | Where in the body |
|---|---|
| Customer sent a message (text, image, button reply, location…) | entry[].changes[].value.messages[] (+ contacts[] with their profile name) |
| Your message was sent / delivered / read / failed | entry[].changes[].value.statuses[] — id is the wamid you got when sending |
| Template approved / rejected | changes[].field = "message_template_status_update" |
# What we send to your URL (a customer wrote "Hi"):
POST /whatsapp/webhook HTTP/1.1
Content-Type: application/json
X-Hub-Signature-256: sha256=5f8a3c… ← HMAC-SHA256 of the raw body with your signing secret
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WABA_ID",
"changes": [{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "912312950811", "phone_number_id": "PHONE_NUMBER_ID" },
"contacts": [{ "profile": { "name": "Rahul" }, "wa_id": "919876543210" }],
"messages": [{ "from": "919876543210", "id": "wamid.HBgM…", "timestamp": "1760000000",
"type": "text", "text": { "body": "Hi" } }]
}
}]
}]
}<?php
// webhook.php — URL, verify token and signing secret are set under Developers → Webhook
const VERIFY_TOKEN = 'my-verify-token';
$secret = getenv('TAVROS_WEBHOOK_SECRET');
if ($_SERVER['REQUEST_METHOD'] === 'GET') { // one-time handshake (PHP turns "hub.mode" into "hub_mode")
if (($_GET['hub_mode'] ?? '') === 'subscribe' && hash_equals(VERIFY_TOKEN, (string) ($_GET['hub_verify_token'] ?? ''))) {
echo $_GET['hub_challenge'];
} else {
http_response_code(403);
}
exit;
}
$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_HUB_SIGNATURE_256'] ?? '';
if (!hash_equals('sha256=' . hash_hmac('sha256', $raw, $secret), $sig)) {
http_response_code(401);
exit;
}
http_response_code(200);
$event = json_decode($raw, true);
foreach ($event['entry'] as $entry) {
foreach ($entry['changes'] as $change) {
$v = $change['value'];
foreach ($v['messages'] ?? [] as $m) { // a customer wrote to you
$text = $m['text']['body'] ?? '[' . $m['type'] . ']';
error_log("From {$m['from']}: $text");
}
foreach ($v['statuses'] ?? [] as $s) { // sent / delivered / read / failed
error_log("Message {$s['id']} is {$s['status']}");
}
}
}# Flask — pip install flask
import hashlib, hmac, os
from flask import Flask, request, abort
app = Flask(__name__)
VERIFY_TOKEN = "my-verify-token"
SECRET = os.environ["TAVROS_WEBHOOK_SECRET"].encode()
@app.get("/whatsapp/webhook")
def verify():
if request.args.get("hub.mode") == "subscribe" and request.args.get("hub.verify_token") == VERIFY_TOKEN:
return request.args.get("hub.challenge", "")
abort(403)
@app.post("/whatsapp/webhook")
def receive():
expected = "sha256=" + hmac.new(SECRET, request.get_data(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("X-Hub-Signature-256", "")):
abort(401)
for entry in request.json["entry"]:
for change in entry["changes"]:
v = change["value"]
for m in v.get("messages", []): # a customer wrote to you
print("From", m["from"], m.get("text", {}).get("body", f"[{m['type']}]"))
for s in v.get("statuses", []): # sent / delivered / read / failed
print("Message", s["id"], "is", s["status"])
return "", 200// Express — npm install express
import express from "express";
import crypto from "node:crypto";
const app = express();
const VERIFY_TOKEN = "my-verify-token";
const SECRET = process.env.TAVROS_WEBHOOK_SECRET;
app.get("/whatsapp/webhook", (req, res) => {
if (req.query["hub.mode"] === "subscribe" && req.query["hub.verify_token"] === VERIFY_TOKEN) {
return res.send(req.query["hub.challenge"]);
}
res.sendStatus(403);
});
// The raw body is needed to check the signature.
app.post("/whatsapp/webhook", express.raw({ type: "application/json" }), (req, res) => {
const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
const got = req.get("X-Hub-Signature-256") || "";
if (got.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) {
return res.sendStatus(401);
}
res.sendStatus(200); // answer fast, then process
const event = JSON.parse(req.body);
for (const entry of event.entry) {
for (const { value: v } of entry.changes) {
for (const m of v.messages ?? []) console.log("From", m.from, m.text?.body ?? `[${m.type}]`);
for (const s of v.statuses ?? []) console.log("Message", s.id, "is", s.status);
}
}
});
app.listen(3000);// Spring Boot 3 / Java 17+
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/whatsapp/webhook")
public class WhatsAppWebhook {
private static final String VERIFY_TOKEN = "my-verify-token";
private final String secret = System.getenv("TAVROS_WEBHOOK_SECRET");
private final ObjectMapper json = new ObjectMapper();
@GetMapping
public ResponseEntity<String> verify(@RequestParam("hub.mode") String mode,
@RequestParam("hub.verify_token") String token,
@RequestParam("hub.challenge") String challenge) {
return "subscribe".equals(mode) && VERIFY_TOKEN.equals(token)
? ResponseEntity.ok(challenge) : ResponseEntity.status(403).build();
}
@PostMapping
public ResponseEntity<Void> receive(@RequestBody byte[] body,
@RequestHeader(value = "X-Hub-Signature-256", defaultValue = "") String sig) throws Exception {
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
String expected = "sha256=" + HexFormat.of().formatHex(mac.doFinal(body));
if (!MessageDigest.isEqual(expected.getBytes(StandardCharsets.UTF_8), sig.getBytes(StandardCharsets.UTF_8))) {
return ResponseEntity.status(401).build();
}
for (JsonNode entry : json.readTree(body).path("entry")) {
for (JsonNode change : entry.path("changes")) {
JsonNode v = change.path("value");
for (JsonNode m : v.path("messages"))
System.out.println("From " + m.path("from").asText() + ": " + m.path("text").path("body").asText());
for (JsonNode s : v.path("statuses"))
System.out.println("Message " + s.path("id").asText() + " is " + s.path("status").asText());
}
}
return ResponseEntity.ok().build();
}
}// ASP.NET Core minimal API (.NET 6+)
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
var app = WebApplication.Create(args);
const string VerifyToken = "my-verify-token";
var secret = Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable("TAVROS_WEBHOOK_SECRET")!);
app.MapGet("/whatsapp/webhook", (HttpRequest req) =>
req.Query["hub.mode"] == "subscribe" && req.Query["hub.verify_token"] == VerifyToken
? Results.Text(req.Query["hub.challenge"].ToString())
: Results.StatusCode(403));
app.MapPost("/whatsapp/webhook", async (HttpRequest req) =>
{
using var ms = new MemoryStream();
await req.Body.CopyToAsync(ms);
var body = ms.ToArray();
var expected = "sha256=" + Convert.ToHexString(HMACSHA256.HashData(secret, body)).ToLowerInvariant();
var got = req.Headers["X-Hub-Signature-256"].ToString();
if (!CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(expected), Encoding.UTF8.GetBytes(got)))
return Results.StatusCode(401);
using var doc = JsonDocument.Parse(body);
foreach (var entry in doc.RootElement.GetProperty("entry").EnumerateArray())
foreach (var change in entry.GetProperty("changes").EnumerateArray())
{
var v = change.GetProperty("value");
if (v.TryGetProperty("messages", out var msgs))
foreach (var m in msgs.EnumerateArray())
Console.WriteLine($"From {m.GetProperty("from")}: {(m.TryGetProperty("text", out var t) ? t.GetProperty("body").GetString() : "[" + m.GetProperty("type") + "]")}");
if (v.TryGetProperty("statuses", out var sts))
foreach (var s in sts.EnumerateArray())
Console.WriteLine($"Message {s.GetProperty("id")} is {s.GetProperty("status")}");
}
return Results.Ok();
});
app.Run();package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"io"
"log"
"net/http"
"os"
)
const verifyToken = "my-verify-token"
var secret = []byte(os.Getenv("TAVROS_WEBHOOK_SECRET"))
type event struct {
Entry []struct {
Changes []struct {
Value struct {
Messages []struct {
From string `json:"from"`
Type string `json:"type"`
Text struct {
Body string `json:"body"`
} `json:"text"`
} `json:"messages"`
Statuses []struct {
ID string `json:"id"`
Status string `json:"status"`
} `json:"statuses"`
} `json:"value"`
} `json:"changes"`
} `json:"entry"`
}
func webhook(w http.ResponseWriter, r *http.Request) {
if r.Method == http.MethodGet {
q := r.URL.Query()
if q.Get("hub.mode") == "subscribe" && q.Get("hub.verify_token") == verifyToken {
io.WriteString(w, q.Get("hub.challenge"))
return
}
w.WriteHeader(http.StatusForbidden)
return
}
body, _ := io.ReadAll(r.Body)
mac := hmac.New(sha256.New, secret)
mac.Write(body)
expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
if !hmac.Equal([]byte(expected), []byte(r.Header.Get("X-Hub-Signature-256"))) {
w.WriteHeader(http.StatusUnauthorized)
return
}
var ev event
json.Unmarshal(body, &ev)
for _, e := range ev.Entry {
for _, c := range e.Changes {
for _, m := range c.Value.Messages {
log.Printf("From %s: %s", m.From, m.Text.Body)
}
for _, s := range c.Value.Statuses {
log.Printf("Message %s is %s", s.ID, s.Status)
}
}
}
w.WriteHeader(http.StatusOK)
}
func main() {
http.HandleFunc("/whatsapp/webhook", webhook)
log.Fatal(http.ListenAndServe(":8080", nil))
}A status event looks like {"statuses":[{"id":"wamid…","status":"delivered","timestamp":"…","recipient_id":"919876543210","pricing":{"billable":true,"category":"utility"}}]}. A failed status carries errors[] with Meta’s error code (see Errors).
Delivery status & webhook replay
Every message you send gets a wamid. Its life is accepted (we took your request) → sent (one grey tick) → delivered (two grey ticks) → read (two blue ticks), or failed. You get each step as a webhook status — and you can also pull it at any time, e.g. to reconcile messages whose webhook your server missed. All five calls need the key permission Send messages and only see messages sent with that key.
sent_at, delivered_at, read_at and failed_at are Meta’s own statuses[].timestamp (UTC) — never the time we received the event (that is received_at). ?refresh=true is accepted and adds a refresh block saying exactly this; it does not (cannot) ask Meta. We keep message and status data for at least 90 days (unless you chose a shorter period in settings) and the webhook delivery log for 30 days.GET /messages/{wamid}
curl "https://tavrosconnect.com/api/v1/messages/wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSM0E4" \
-H "Authorization: Bearer tc_live_YOUR_KEY"{
"wamid": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSM0E4",
"phone_number_id": "PHONE_NUMBER_ID",
"to": "919876543210",
"type": "template",
"template": "payment_receipt_v1",
"status": "delivered", // highest state reached: accepted | sent | delivered | read | failed
"timestamps": {
"accepted_at": "2026-11-15T08:34:18Z", // when we accepted your API request
"sent_at": "2026-11-15T08:34:19Z", // Meta status=sent timestamp
"delivered_at": "2026-11-15T08:34:21Z", // Meta status=delivered timestamp
"read_at": null,
"failed_at": null
},
"error": null, // failed: {"code":131026,"title":"Message undeliverable","message":"…","details":"…"}
"events": [ // raw history, ordered by Meta timestamp; out-of-order events are kept
{"status": "sent", "timestamp": "2026-11-15T08:34:19Z", "received_at": "2026-11-15T08:34:20Z"},
{"status": "delivered", "timestamp": "2026-11-15T08:34:21Z", "received_at": "2026-11-15T08:34:21Z",
"conversation": {"id": "…", "origin": {"type": "utility"}}, "pricing": {"billable": true, "category": "utility"}}
]
}404 if the wamid is unknown, was sent with another key, or is past retention. Status rules: status is the furthest of sent → delivered → read that Meta reported; it is failed only if Meta reported failed and never delivered/read. If read arrives before delivered, both are shown as received — nothing is inferred or dropped. Test-key messages (wamid.TEST_…) are not stored.
POST /messages/status:batch
curl -X POST "https://tavrosconnect.com/api/v1/messages/status:batch" \
-H "Authorization: Bearer tc_live_YOUR_KEY" -H "Content-Type: application/json" \
-d '{"wamids":["wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSM0E4","wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSM0E5"]}'{"data": [ { …same object as above… }, … ],
"not_found": ["wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSM0E5"]}1 to 100 wamids per request. Counts as one read call (see Rate limits; every package allows at least 60 read calls a minute).
\GET /messages — sweep everything from the last N hours
curl "https://tavrosconnect.com/api/v1/messages?since=2026-11-15T00:00:00Z&status=failed&limit=100" \
-H "Authorization: Bearer tc_live_YOUR_KEY"\
# next page: …&cursor=NEXT_CURSOR_FROM_PREVIOUS_RESPONSE| Query | |
|---|---|
since, until | ISO 8601 (2026-11-15T09:30:00Z); filter on the time we accepted the message. No zone = UTC. |
status | accepted, sent, delivered, read or failed (the message’s current status) |
to | One recipient, country code + number |
limit | 1–200, default 100 |
cursor, order | Pass next_cursor back to continue; order=asc (default, oldest first — best for sweeps) or desc |
{"data": [ { …message object… }, … ], "next_cursor": "bTQyMA", "has_more": true}A page can hold fewer than limit items when you filter by status; keep following next_cursor until has_more is false.
POST /webhooks/replay — recover from downtime
Re-sends the stored status events to your configured webhook URL, signed with the same X-Hub-Signature-256. Each event is its own delivery, in Meta’s exact format (statuses[] holds exactly one object, timestamp / errors / conversation / pricing unchanged), oldest first. Your receiver should dedupe on wamid + status.
# by message
curl -X POST "https://tavrosconnect.com/api/v1/webhooks/replay" -H "Authorization: Bearer tc_live_YOUR_KEY" \
-H "Content-Type: application/json" -d '{"wamids":["wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSM0E4"]}'
# by time window: events we RECEIVED between these times (your downtime)
curl -X POST "https://tavrosconnect.com/api/v1/webhooks/replay" -H "Authorization: Bearer tc_live_YOUR_KEY" \
-H "Content-Type: application/json" -d '{"since":"2026-11-15T09:00:00Z","until":"2026-11-15T11:00:00Z"}'{"queued": 3, "skipped": 0, "matched": 1, "not_found": [], "note": "…"} // HTTP 202Up to 500 wamids, or at most 1000 events per call (narrow the window if you get an error); 5 requests per minute. Delivery is asynchronous — follow it with GET /webhooks/deliveries?replay=true. Your webhook must be set and turned on.
GET /webhooks/deliveries — what we sent you and what you answered
curl "https://tavrosconnect.com/api/v1/webhooks/deliveries?since=2026-11-15T00:00:00Z&status=failed" \
-H "Authorization: Bearer tc_live_YOUR_KEY"{"data": [{
"id": 4812, "created_at": "2026-11-15T08:34:20Z",
"status": "delivered", // pending (will retry) | delivered | failed (gave up)
"replay": false, "attempts": 2, "last_http_status": 200, "last_error": null,
"delivered_at": "2026-11-15T08:35:21Z", "next_attempt_at": null,
"events": [{"field": "messages", "wamid": "wamid.…", "status": "delivered", "timestamp": "1794731541"}],
"attempt_log": [
{"attempt": 1, "at": "2026-11-15T08:34:20Z", "http_status": 503, "error": "HTTP 503", "ms": 214},
{"attempt": 2, "at": "2026-11-15T08:35:21Z", "http_status": 200, "error": null, "ms": 96}
]}],
"next_cursor": null, "has_more": false}Newest first. Filters: since, until, status (pending, delivered, failed), replay (true/false), wamid, include_payload=true, limit (1–100), cursor. http_status is null when we could not reach your server (DNS, timeout, TLS). Kept 30 days.
Webhook format guarantees. Statuses are forwarded as Meta sent them: sent, delivered, read and failed each as its own event (one status per changes[] entry, never merged), with Meta’s timestamp (epoch seconds, as a string), errors[], conversation and pricing untouched. We never reorder or drop events — a read may reach you before its delivered; use the timestamps. Non-2xx answers are retried as described in Webhooks.
Test mode
Create a Test key (tc_test_…) and build your whole integration without sending a single real message. The URLs, bodies and responses are the same as live.
- Sends are validated, not sent. We check the phone number id belongs to you, the
tonumber, the message body, and for templates: the name, the language, that it is approved and that the number of body parameters matches. Errors are the same codes as live (e.g.132001,132000). - A valid send answers
200with a fake idwamid.TEST_…and then pushes sent → delivered → read statuses to your webhook. - Magic numbers: any
toending in0000(e.g.919800000000) gets a failed status with error131026— use it to test your failure handling. - Media uploads return a fake id (nothing stored). Contacts are a dry run: the answer says what would be created or updated, with
"test": true, and nothing is saved. - Template list and media downloads return real data — they only read.
- Nothing is sent to Meta, no Active Day is used, nothing appears in Chats, and test calls are marked test in your API log and usage reports. Responses carry the header
X-Tavros-Mode: test.
Simulate a customer writing to you
curl -X POST 'https://tavrosconnect.com/api/v1/test/inbound' \
-H "Authorization: Bearer $TAVROS_TEST_KEY" \
-H 'Content-Type: application/json' \
-d '{ "from": "919876543210", "name": "Rahul", "text": "Hi, is my membership active?" }'
# → {"success":true,"delivery_id":123} — your webhook received a real-looking "messages" eventr = requests.post("https://tavrosconnect.com/api/v1/test/inbound", timeout=30,
headers={"Authorization": f"Bearer {os.environ['TAVROS_TEST_KEY']}"},
json={"from": "919876543210", "name": "Rahul", "text": "Hi, is my membership active?"})
print(r.json()) # {"success": true, "delivery_id": 123}const res = await fetch("https://tavrosconnect.com/api/v1/test/inbound", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.TAVROS_TEST_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ from: "919876543210", name: "Rahul", text: "Hi, is my membership active?" }),
});
console.log(await res.json()); // { success: true, delivery_id: 123 }Optional field phone_number_id picks which of your numbers it is sent to (default: the first).
Rate limits
Limits are per business (all its live keys together) and depend on its package (the free trial has Silver’s):
| Limit | Bronze | Silver | Gold |
|---|---|---|---|
Send speed (POST …/messages; bursts of up to 10) | 2 msg/sec | 10 msg/sec | 40 msg/sec |
| Unique recipients per day (resets at midnight India time; a repeat recipient counts once) | 1,000 | 10,000 | No cap from us |
| Read calls (mark as read, templates, media, contacts) per minute | 60 | 300 | 1,000 |
| Live API keys | 1 | 3 | 10 |
Test keys: 60 requests per minute, no daily cap. Need more for large campaigns? Write to us — we can raise it per business. Every response tells you where you stand:
X-RateLimit-Limit: 10 ← messages/sec (sends) or calls/min (reads)
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1 ← seconds until the limit is fully available againOver a limit you get 429 with error code 4, a Retry-After header and error.type saying which limit:
rate_limited— send speed or read calls. WaitRetry-Afterseconds and retry (our PHP SDK does this for you).daily_api_quota_exceeded— today’s unique recipients are used. Messages to people you already messaged today still go through; new recipients wait until midnight India time (Retry-After) or a bigger package. Don’t retry in a loop.
HTTP/1.1 429 Too Many Requests
Retry-After: 1
{"error":{"message":"(#4) Bronze allows 2 messages/sec. Retry after 1s or upgrade to Silver.","type":"rate_limited","code":4,"fbtrace_id":"TC…"}}
HTTP/1.1 429 Too Many Requests
Retry-After: 30240
{"error":{"message":"(#4) Bronze allows 1,000 unique recipients a day through the API, and today’s are used (1,000). …","type":"daily_api_quota_exceeded","code":4,"fbtrace_id":"TC…"}}<?php
function tavros_post(string $url, array $body, int $tries = 3): array {
for ($i = 1; ; $i++) {
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HEADER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('TAVROS_API_KEY'), 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($body),
]);
$raw = (string) curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$headers = substr($raw, 0, curl_getinfo($ch, CURLINFO_HEADER_SIZE));
if ($status !== 429 || $i >= $tries) return [$status, json_decode(substr($raw, strlen($headers)), true)];
sleep(preg_match('/^Retry-After:\s*(\d+)/mi', $headers, $m) ? (int) $m[1] : 5);
}
}import time
def tavros_post(url, body, tries=3):
for i in range(tries):
r = requests.post(url, json=body, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
if r.status_code != 429 or i == tries - 1:
return r
time.sleep(int(r.headers.get("Retry-After", "5")))async function tavrosPost(url, body, tries = 3) {
for (let i = 1; ; i++) {
const res = await fetch(url, {
method: "POST",
headers: { Authorization: `Bearer ${process.env.TAVROS_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify(body),
});
if (res.status !== 429 || i >= tries) return res;
await new Promise((r) => setTimeout(r, 1000 * Number(res.headers.get("Retry-After") ?? 5)));
}
}WhatsApp has its own limits on top of ours: a new number can message 250 unique customers per 24 h (rising to 1K, 10K, 100K with good quality), and about 80 messages per second per number. Those errors come back as Meta codes 131056, 130429 or 80007.
Errors
Errors always have Meta’s shape, so existing error handling keeps working:
{ "error": { "message": "(#132001) Template name does not exist in the translation", "type": "OAuthException", "code": 132001, "fbtrace_id": "TC9F2A…" } }From Tavros Connect
| HTTP | code | Meaning | What to do |
|---|---|---|---|
| 401 | 190 | API key missing, wrong or revoked | Send Authorization: Bearer tc_live_…; create a new key if it was revoked |
| 403 | 10 | The key lacks the permission, or the request came from an IP not in its allowlist | Edit the key under Developers (permissions / IPs) |
| 403 | 200 | Your plan doesn’t include the API, or the subscription expired | Renew or upgrade under Billing |
| 400 | 131042 | Meta couldn’t charge your WhatsApp account (payment method / eligibility) | Add or update a payment method in WhatsApp Manager (Meta) |
| 403 | 200 | No Active Days left (sending paused) | Recharge Active Days under Billing |
| 429 | 4 | rate_limited: your package’s send speed or read calls per minute (or too many invalid keys from your IP) | Wait Retry-After seconds and retry |
| 429 | 4 | daily_api_quota_exceeded: today’s unique API recipients are used | Wait until midnight India time or move to a bigger package; repeat recipients still work |
| 400 | 100 | Bad request — unknown phone number id, missing field, wrong format | Read the message; check the phone number id on the Developers page |
| 500 | 2 | Temporary problem at Tavros Connect or Meta | Retry after a few seconds |
Common WhatsApp (Meta) errors — passed through unchanged
| code | Meaning | What to do |
|---|---|---|
| 131047 | More than 24 hours since the customer’s last message | Send a template instead of free text |
| 132001 | Template doesn’t exist in that language (or not approved) | Check the name + language code on the Templates page |
| 132000 | Wrong number of template parameters | Send one parameter per {{n}} |
| 132012 | A parameter has the wrong format (e.g. empty text, new lines) | Remove line breaks / tabs; no empty values |
| 131026 | Message undeliverable (not on WhatsApp, old app, blocked you) | Use another channel for this customer |
| 131049 | Meta held back a marketing message to protect engagement | Don’t retry immediately; send fewer marketing messages to this user |
| 131050 | The customer stopped marketing messages from you | Mark them opted-out |
| 131056 | Too many messages to the same customer in a short time | Slow down for that number |
| 130429 | Throughput limit (messages per second) reached | Retry with back-off |
| 131053 | Media upload error (unsupported / too big) | Check type and size (images: JPEG/PNG ≤ 5 MB) |
| 131031 | Your WhatsApp account is locked or restricted | Check WhatsApp Manager / contact us |
| 368 | Temporarily blocked for policy violations | Review quality and template content |
Migrating to Tavros Connect
From Meta’s WhatsApp Cloud API — 3 changes
- Replace
https://graph.facebook.comwithhttps://tavrosconnect.com. Paths stay the same (/v23.0/{phone-number-id}/messages). - Replace Meta’s access token with a Tavros Connect API key.
- Enter your webhook URL in Tavros Connect instead of the Meta app (use your Meta app secret as the signing secret to keep your signature check).
From WATI, Interakt, AiSensy or another provider
Your WhatsApp Business Account, number and approved templates belong to you — connect the same account to Tavros Connect and they come along. Then point your code at one endpoint:
| You call today | Call instead |
|---|---|
WATI sendTemplateMessage (template_name, parameters[{name,value}]) | POST /api/v1/{phone-number-id}/messages with "type":"template" — put the values, in order, in components[0].parameters (example) |
Interakt /v1/public/message/ (type: "Template", bodyValues) | |
AiSensy campaign API (campaignName, destination, templateParams) | |
| Session / free-text message endpoints | Same endpoint with "type":"text" |
| Provider-specific webhook format | Meta’s standard format (above) — signed with X-Hub-Signature-256 |
| Contact / attribute APIs | POST /api/v1/contacts |
Phone numbers are always country code + number without + (e.g. 919876543210). Need a hand? Our team helps you migrate for free — book a call.
SDK, OpenAPI & Postman
Questions or something missing? Email tavrosconnect@gmail.com.