Skip to main content

Conversations

The 24-hour window​

WhatsApp is built around consent. When a customer messages you, a 24-hour service window opens with them. Inside it, you may send free text and anything else you like. Outside it, only an approved template will be delivered.

The window is extended by each new inbound message, not by anything you send. A conversation with a customer who never replies closes 24 hours after their last message, however much you send in the meantime.

MALIPOPAY accepts and bills a free-text send whether or not a window is open. Meta is what silently drops it. If a message "vanished", check whether the window was open before you look anywhere else.

A conversation is a billing window, not a thread​

This trips people up. A WabaConversation is a per-category 24-hour billing window, so one customer can have several open at once (a MARKETING window and a SERVICE window), and a single ongoing chat spans many conversations over time.

Read a customer's history by their number, not by conversation id, or you will see fragments and wonder where the rest went.

List conversations​

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

Filter by phoneNumberId, contactWaId and category; paginated.

Read a timeline​

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

Reply inside an open window​

curl -X POST https://core-prod.malipopay.co.tz/api/v1/waba/conversations/{id}/reply \
  -H "apiToken: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Thanks, your refund is on its way." }'

This is the free-text path, and it only works while the window is open. If it has closed, send a template with /waba/messages/template instead.

PATCH /api/v1/waba/conversations/{id}/read clears the unread badge, for building your own inbox.

Inbound media​

An inbound media message carries a Meta media id, not the file. Fetch the bytes with:

curl https://core-prod.malipopay.co.tz/api/v1/waba/messages/{id}/media \
  -H "apiToken: YOUR_API_KEY" \
  -o attachment.jpg

Do this promptly. Meta expires media ids after 30 days.

Billing​

Conversations are what you pay for, priced per category:

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

Five messages inside one open window cost one conversation. Batching updates into a single window is genuinely cheaper than spreading them out, which is worth designing for.

Last updated on