Skip to main content

WhatsApp Quickstart

MALIPOPAY gives you the WhatsApp Business Platform through the same API key you already use for payments. Send order confirmations, delivery updates, receipts and OTPs from your own business number, and receive replies.

Base URL and auth are unchanged:

https://core-prod.malipopay.co.tz/api/v1/waba
apiToken: YOUR_API_KEY

The one rule that governs everything​

WhatsApp is not SMS. You cannot message anyone you like, whenever you like.

  • Outside a conversation, you may only send a template that Meta has reviewed and approved.
  • Once a customer replies, a 24-hour service window opens and you may send free text.
  • When the window closes, you are back to templates.

Almost every "the message never arrived" report is a free-text send outside an open window. See Conversations.

Step 1: Connect a number​

In the dashboard, go to WhatsApp → Numbers and connect your business number through Meta's embedded signup. You will need access to the number to enter the verification code Meta sends, and Meta reviews your display name separately, which can take a while and can be rejected.

Two things to know before you start:

  • The number must not already have a WhatsApp account on it. If it does, delete that account first (WhatsApp → Settings → Account → Delete account) and wait a few minutes, or use Meta's migration flow.
  • If you do not connect your own number, sends fall back to the shared MALIPOPAY platform number. That works, but your customers see MALIPOPAY rather than you.

Check what you have connected. Do this first — it tells you what to put in from when you send, and whether your customers will see your brand or ours:

curl https://core-prod.malipopay.co.tz/api/v1/waba/phone-numbers \
  -H "apiToken: YOUR_API_KEY"
{
  "data": [
    {
      "msisdn": "255687128012",
      "ownership": "OWNED",
      "isDefaultSender": true,
      "connectionStatus": "CONNECTED"
    }
  ]
}

msisdn is the number you pass as from. ownership tells you whose number it is: OWNED is yours, GRANTED is one shared with you, and SHARED_PLATFORM is the MALIPOPAY number — if that is all you see, you have not connected your own yet and your customers will see MALIPOPAY as the sender.

Do not go looking for Meta's phoneNumberId. You never need it; from takes the number as you would write it, and 0687128012, 255687128012 and +255 687 128 012 all work.

Step 2: Get a template approved​

Create the template in WhatsApp → Templates, or over the API:

curl -X POST https://core-prod.malipopay.co.tz/api/v1/waba/templates \
  -H "apiToken: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_confirmation",
    "language": "en",
    "category": "UTILITY",
    "components": [
      {
        "type": "BODY",
        "text": "Hi {{1}}, we have received your payment of TZS {{2}}. Your order {{3}} is confirmed.",
        "example": { "body_text": [["John", "50,000", "ORD-001"]] }
      }
    ]
  }'

Templates start PENDING and must reach APPROVED before you can send them. Meta's rules are strict and the common rejections are avoidable. See Templates.

Step 3: Send it​

curl -X POST https://core-prod.malipopay.co.tz/api/v1/waba/messages/template \
  -H "apiToken: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "255712345678",
    "from": "255687128012",
    "templateName": "order_confirmation",
    "language": "en",
    "variables": { "1": "John", "2": "50,000", "3": "ORD-001" }
  }'

from is the msisdn from Step 1. Leave it out and your default sender is used.

A 202 means MALIPOPAY accepted it and handed it to Meta. Delivery is confirmed later by webhook. The response names the number it went out from:

{
  "from": "255687128012",
  "fromSharedPlatformNumber": false,
  "chargedCredits": 5
}

If from names a number that is not registered to you, the send is refused with a 400 rather than quietly going out from a different number. See Choosing the sender number.

Step 4: Reply in plain text​

Once the customer replies, a 24-hour window is open and you can send plain text with no template:

curl -X POST https://core-prod.malipopay.co.tz/api/v1/waba/messages \
  -H "apiToken: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "255712345678",
    "from": "255687128012",
    "type": "text",
    "text": { "body": "Thanks! Your order ships today." }
  }'

Try this before they have replied and it is refused, not silently dropped:

Free-text only reaches a customer inside an open 24-hour conversation.
Send an approved template to start one.

Nothing is sent and nothing is billed. See Send plain text.

Step 5: Receive replies​

Point a webhook at your server to receive inbound messages and delivery statuses. See WhatsApp Webhooks.

What it costs​

WhatsApp is billed per 24-hour conversation, not per message, at Meta's per-category rates plus the MALIPOPAY margin. Sending five messages inside one open window costs one conversation. Categories are MARKETING, UTILITY, AUTHENTICATION and SERVICE, and they are priced differently.

Charges come off your MALIPOPAY wallet at send time, and are refunded automatically if Meta rejects the send. Your own rollup:

curl https://core-prod.malipopay.co.tz/api/v1/waba/billing/conversations \
  -H "apiToken: YOUR_API_KEY"

Next steps​

Last updated on