Messaging API

ZingaConnect exposes a messaging API so your own applications can send WhatsApp
messages and receive delivery/inbound events — using ZingaConnect as your
messaging provider. These endpoints live under /papi/v1/messaging and use the
messaging:* scopes (separate from data scopes).

Scopes

Endpoint	Scope required
List channels, read message status	`messaging:read`
Send a message	`messaging:send`
Manage webhooks	`messaging:webhooks`

A data:write:* key does not grant messaging; add the messaging scopes
explicitly when you create the key.

List channels

GET /papi/v1/messaging/channels

Returns the messaging channels configured in your entity (the WhatsApp numbers
and other channels you can send from). Use a channel's id as channelConfigId
when sending.

Send a WhatsApp message

POST /papi/v1/messaging/whatsapp/send      → 202 Accepted

The send is queued and returns 202; track delivery via the message status
endpoint or a webhook. The body:

Field	Notes
`to`	Recipient in E.164 format, e.g. `+14155551234`
`channelConfigId`	Which configured channel/number to send from
`type`	`text`, `template`, `media`, or `interactive` (inferred if omitted)
`text`	Message text (for `type: text`)
`template`	`{ name, language, params: [...] }` for a pre-approved template
`media`	`[ { url, filename, mime } ]` for media messages
`interactive`	Interactive message payload (buttons/lists)
`externalId`	Your own reference, echoed back in status events

# Simple text message
curl -X POST https://api-v1.zingasuite.com/papi/v1/messaging/whatsapp/send \
  -H "Authorization: Bearer zk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "channelConfigId": "<channel-id>",
    "type": "text",
    "text": "Your order #1042 has shipped!",
    "externalId": "ship-1042"
  }'

# Template message
curl -X POST https://api-v1.zingasuite.com/papi/v1/messaging/whatsapp/send \
  -H "Authorization: Bearer zk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "channelConfigId": "<channel-id>",
    "type": "template",
    "template": { "name": "order_shipped", "language": "en", "params": ["1042", "FedEx"] }
  }'

Read message status

GET /papi/v1/messaging/messages/{id}

Returns the current delivery state of a message you sent.

Webhooks

GET    /papi/v1/messaging/webhooks
POST   /papi/v1/messaging/webhooks
DELETE /papi/v1/messaging/webhooks/{id}

Create a webhook with a target url and (recommended) a secret:

curl -X POST https://api-v1.zingasuite.com/papi/v1/messaging/webhooks \
  -H "Authorization: Bearer zk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-app.example.com/hooks/zinga", "secret": "whsec_…" }'

Verifying webhook signatures

When a secret is set, each webhook request carries an HMAC-SHA256 signature of
the raw body in the X-Zinga-Signature header:

X-Zinga-Signature: sha256=<hex-digest>

Recompute the digest over the raw request body with your secret and compare in
constant time before trusting the payload. Deleting a webhook deactivates it.

Building on ZingaConnect

This is the same delivery pipeline ZingaConnect uses for its own campaigns and
inbox, so messages you send via the API appear alongside them. For the product
side — channels, templates, campaigns and the inbox — see the
ZingaConnect chapter.