Whatsapp

TextCus WhatsApp API (v2)

Send WhatsApp messages from your own systems. Authentication, response shape and error handling match the TextCus SMS API, so if you have already integrated that, this will feel familiar.

Base URL: https://api.textcus.com/api/v2

---

Authentication

Send your API key as a Bearer token on every request. You'll find it in your dashboard under Settings.

Authorization: Bearer YOUR_API_KEY

A missing or unknown key returns 401.

Response shape

Every response uses the same envelope:

{ "status": true, "message": "1 message(s) sent successfully", "data": { } }

status is false for any failure, and message is safe to show to your own users.

---

Before you can send

WhatsApp is not SMS — you cannot send arbitrary text to someone who has not messaged you first. Two rules govern everything:

1. To start a conversation you must use a template Meta has approved. Create templates in your TextCus dashboard; approval usually takes minutes.

2. Once a customer replies, you have 24 hours in which you can send free-form text. After that window closes you need a template again.

Sending is charged per message against your WhatsApp balance, which is separate from your SMS balance and held in GHS. Prices depend on the template's category and drop as your monthly volume grows — call /whatsapp/balance to see your current rates.

---

POST /whatsapp/send

curl -X POST https://api.textcus.com/api/v2/whatsapp/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "233241234567",
    "recipient": "0244000001",
    "template": "order_shipped",
    "language": "en_US",
    "variables": { "body": ["Ama", "ORD-1042"] }
  }'

Field	Required	Notes
sender	yes	One of your connected WhatsApp numbers. 233241234567, [phone] and 0241234567 all work.
recipient	one of	A single destination number.
recipients	one of	Up to 1000 numbers. Duplicates are removed.
template	yes*	Template name. *Not needed when sending free-form text.
language	no	Defaults to en_US. Must match the template's language exactly.
variables	no	{"header": [...], "body": [...]} — plain lists, in order.
type	no	template (default) or text.
message	yes if type=text	Free-form body. Only valid inside an open 24-hour window.

Local numbers are converted to international format automatically, so 0244000001 becomes 233244000001.

Response

{
  "status": true,
  "message": "1 message(s) sent successfully",
  "data": {
    "sent": 1,
    "failed": 0,
    "messages": [
      { "recipient": "233244000001", "message_id": "wamid.HBgMMjMz...", "status": "sent" }
    ],
    "failures": [],
    "unit_price": 0.1003,
    "charged": 0.1003,
    "balance": 42.6,
    "currency": "GHS"
  }
}

Keep message_id — it is how you look a message up later, and it is the same id Meta uses.

Partial success

A bulk send is not all-or-nothing. Each recipient is charged and attempted independently, and anything Meta rejects is refunded immediately:

{
  "sent": 2,
  "failed": 1,
  "failures": [
    { "recipient": "233209999999", "error": "Recipient not on WhatsApp" }
  ]
}

You are never charged for a message Meta refused. Messages that fail later during delivery are refunded when Meta reports the failure, and show "refunded": true on the status endpoint.

---

GET /whatsapp/status/{message_id}

curl https://api.textcus.com/api/v2/whatsapp/status/wamid.HBgMMjMz... \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "status": true,
  "data": {
    "message_id": "wamid.HBgMMjMz...",
    "recipient": "233244000001",
    "status": "delivered",
    "charge": 0.1003,
    "refunded": false,
    "sent_at": "2026-09-05T14:12:03+00:00",
    "delivered_at": "2026-09-05T14:12:09+00:00",
    "read_at": null
  }
}

Statuses progress queued → sent → delivered → read, or end at failed. Inbound messages are recorded as received.

---

GET /whatsapp/messages

Paginated history. Optional filters: status, direction (outbound / inbound), recipient, per_page (max 200).

curl "https://api.textcus.com/api/v2/whatsapp/messages?status=failed&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Replies from your customers appear here with "direction": "inbound" and no charge.

---

GET /whatsapp/senders

{
  "data": [
    {
      "sender": "[phone]",
      "name": "Acme Ghana",
      "quality_rating": "GREEN",
      "verified": true,
      "active": true,
      "connected_at": "2026-09-01T09:14:22+00:00"
    }
  ]
}

quality_rating is Meta's health score for the number. GREEN is healthy; RED means your messaging limit is at risk.

---

GET /whatsapp/templates

Approved templates only by default. Pass ?include_unapproved=true to see pending and rejected ones too.

{
  "data": [
    {
      "name": "order_shipped",
      "language": "en_US",
      "category": "UTILITY",
      "status": "APPROVED",
      "body": "Hi {{1}}, order {{2}} shipped.",
      "variables": { "header": 0, "body": 2 }
    }
  ]
}

variables tells you how many values each section expects — body: 2 means send "variables": {"body": ["...", "..."]} in that order.

---

GET /whatsapp/balance

{
  "data": {
    "whatsapp_balance": 42.6,
    "currency": "GHS",
    "tier": "Starter",
    "monthly_volume": 1204,
    "rates": {
      "marketing": 0.38,
      "utility": 0.1003,
      "authentication": 0.1003,
      "service": 0
    }
  }
}

Rates shown are your current prices at your current volume tier, per message, in GHS.

---

Errors

Code	Meaning	What to do
401	Missing or invalid API key	Check the Authorization header.
402	Insufficient WhatsApp balance	Response includes required and balance. Top up.
404	Sender, template or message not found	Check the name; templates are per sender and per language.
422	Validation failed, or template not approved	message says exactly what is wrong.
429	Rate limited	60 requests per minute. Back off and retry.
500	Something broke on our side	Safe to retry. Contact support if it persists.

Nothing is charged on a 4xx.

---

Notes for production

• Rate limit is 60 requests/minute. Prefer one call with recipients over many calls with recipient — a single request can carry 1000 numbers.

• Retries are not deduplicated. If a request times out, check /whatsapp/messages?recipient=... before resending, or you may pay twice.

• Get consent before messaging. WhatsApp requires opt-in, and blocks or "report" taps push your quality rating down fast. A RED rating cuts how many people you can reach per day.