Zivo WhatsApp API Developer Documentation

Quick start

Log in to Zivo and open Settings.
Make sure WhatsApp Cloud is connected and online-ready.
Open Send API and generate an API key.
Save the API key securely. It is shown only once.
Send a test message to https://zivo.co.ke/api/zivo/zchat/services/sendwhatsapp.
Optional: open Connected apps and add your reply webhook URL.

The API sends direct WhatsApp text messages and can forward inbound customer replies. The customer should already be in a valid WhatsApp service window unless your Meta account and templates allow otherwise.

Zivo API answers

Quick answers for teams deciding whether Zivo can connect WhatsApp messaging to an existing app, CRM, school system, billing system, or operations platform.

What can the Zivo WhatsApp API do?

The Zivo WhatsApp API lets a connected business system send WhatsApp messages through a Zivo workspace and keep the message recorded in the shared inbox.

Can Zivo receive customer replies by webhook?

Yes. Zivo can send inbound customer replies to a configured HTTPS callback after saving the message in the shared inbox.

How is the Zivo reply webhook secured?

When a signing secret is configured, Zivo signs webhook callbacks with X-Zivo-Signature using HMAC-SHA256 over the raw JSON body.

Can the API send bulk WhatsApp messages?

Yes. The bulk endpoint accepts a list of WhatsApp messages and returns a per-recipient response item.

Does the API expose private inbox data?

No. API credentials are scoped to the configured business and workspace, and webhook payloads include only the customer message context needed by the integration.

Authentication

Every request needs your Zivo partnerID and API key.

Field	Required	Description
`partnerID`	Yes	Your Zivo business ID, shown in Settings > Send API.
`apikey`	Yes	Your generated Zivo API key. You may also send it as a Bearer token.

Inbound reply webhooks are configured in Settings > Connected apps. Zivo signs callbacks with X-Zivo-Signature when you add a signing secret.

Send a WhatsApp message

POST https://zivo.co.ke/api/zivo/zchat/services/sendwhatsapp

Send one WhatsApp text message through the connected Zivo inbox.

curl -X POST "https://zivo.co.ke/api/zivo/zchat/services/sendwhatsapp" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerID": "123",
    "apikey": "zivo_live_xxx",
    "mobile": "254700000000",
    "message": "Hello, your order is ready.",
    "clientwhatsappid": "order-1001"
  }'

Response

{
  "responses": [
    {
      "response-code": 200,
      "respose-code": 200,
      "response-description": "Success",
      "mobile": "254700000000",
      "messageid": "88421",
      "provider_message_id": "wamid.xxx",
      "networkid": "whatsapp",
      "channel": "whatsapp",
      "status": "sent"
    }
  ]
}

Request fields

Field	Required	Description
`mobile`	Yes	Customer WhatsApp number. Use international format such as `2547...`. Kenyan local `07...` is accepted and normalized before sending.
`message`	Yes	The WhatsApp text to send.
`clientwhatsappid`	No	Your own reference ID for matching the message in your system.

Bulk WhatsApp send

POST https://zivo.co.ke/api/zivo/zchat/services/sendbulk

Send up to 100 WhatsApp messages in one request. Use whatsapplist. For compatibility, smslist is accepted but still sends WhatsApp messages only.

curl -X POST "https://zivo.co.ke/api/zivo/zchat/services/sendbulk" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerID": "123",
    "apikey": "zivo_live_xxx",
    "whatsapplist": [
      {
        "mobile": "254700000001",
        "message": "Hello Mary, your quote is ready.",
        "clientwhatsappid": "quote-101"
      },
      {
        "mobile": "254700000002",
        "message": "Hello John, your delivery has been scheduled.",
        "clientwhatsappid": "delivery-202"
      }
    ]
  }'

Receive customer replies

Enable a customer reply webhook in Zivo Settings to receive incoming WhatsApp replies in your own system after Zivo saves them in the shared inbox.

POST Your callback URL

Zivo sends a JSON payload for each new inbound WhatsApp message. Your callback URL must use HTTPS. Duplicate Meta callbacks are ignored before webhook delivery, but your system should still treat delivery_id or zivo_message_id as idempotency keys.

{
  "event": "whatsapp.message.received",
  "delivery_id": "zivo-whatsapp-9912",
  "partnerID": "123",
  "business": {
    "id": 123,
    "name": "Your Business"
  },
  "connected_app": {
    "name": "Partner CRM"
  },
  "workspace": {
    "id": 24,
    "name": "Main WhatsApp",
    "slug": "main-whatsapp"
  },
  "channel": {
    "id": 8,
    "name": "WhatsApp Inbox"
  },
  "from": "254700000000",
  "customer_name": "Mary Customer",
  "message": "Yes, send the invoice.",
  "message_type": "text",
  "zivo_message_id": 9912,
  "provider_message_id": "wamid.xxx",
  "reply_to_provider_message_id": "wamid.previous",
  "conversation_url": "https://zivo.co.ke/zchat/channels/8?wa_phone=254700000000",
  "received_at": "2026-06-26T16:00:00+03:00"
}

How delivery works

Zivo saves the customer message in the shared inbox first, then dispatches your webhook.
Your server should return any 2xx response quickly after accepting the event.
If your server returns a non-2xx response or times out, Zivo retries the delivery automatically.
Use delivery_id or zivo_message_id to avoid processing the same reply twice.

Webhook headers

Header	Description
`X-Zivo-Event`	Event name, for example `whatsapp.message.received`.
`X-Zivo-Delivery`	Stable delivery ID for idempotency.
`X-Zivo-Signature`	Present when a signing secret is configured. Format: `sha256=<hmac>`.

Verify X-Zivo-Signature by computing HMAC-SHA256 over the raw JSON request body using your webhook signing secret.

Signature check example

// Node.js / Express
const crypto = require('crypto');

const expected = 'sha256=' + crypto
  .createHmac('sha256', process.env.ZIVO_WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');
const received = req.header('X-Zivo-Signature') || '';

if (received.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
  return res.status(401).send('Invalid signature');
}

res.sendStatus(204);

Delivery report

GET https://zivo.co.ke/api/zivo/zchat/services/getdlr

Check the local Zivo send status for a message. Use the messageid returned from send.

curl "https://zivo.co.ke/api/zivo/zchat/services/getdlr?partnerID=123&apikey=zivo_live_xxx&messageID=88421"

Account status

GET https://zivo.co.ke/api/zivo/zchat/services/account

Confirm that the API key is valid, WhatsApp is enabled for the business, and the reply webhook is configured.

curl "https://zivo.co.ke/api/zivo/zchat/services/account?partnerID=123&apikey=zivo_live_xxx"

{
  "success": true,
  "partnerID": "123",
  "business": "Your Business",
  "whatsapp_enabled": true,
  "reply_webhook_enabled": true,
  "reply_webhook_configured": true
}

Error responses

Status	Meaning	Fix
`401`	Invalid `partnerID` or `apikey`.	Generate a new key in Zivo settings and update your integration.
`422`	Required field missing or invalid.	Send `mobile` and `message`.
`400`	WhatsApp send failed after authentication.	Check WhatsApp Cloud setup, service window, Meta token, and phone number ID.
`404`	Delivery report message was not found.	Use the Zivo `messageid` returned by send.

Security and limits

Keep the API key private. Do not expose it in frontend JavaScript.
Rotate the key if it is shared with the wrong person.
Requests are throttled to protect the workspace.
Use HTTPS only for API calls and reply webhook callback URLs.
Keep your reply webhook signing secret private and verify X-Zivo-Signature before processing events.
Process reply webhooks idempotently because retries can happen after network failures.
For automated marketing or template messages, confirm your Meta WhatsApp policy and approved templates first.