WhatsApp · API reference

In this area

Send WhatsApp messages directly, without creating an inbox conversation. Meta bills these to your own WABA account.

List connected WhatsApp numbers

get/v1/public/whatsapp/numbers

Returns the organization's WhatsApp numbers with their channel (CLOUD_API = official Meta, EVOLUTION = unofficial) and connection status. Use the id of a connected number as instanceId when sending through the Send API — required in practice for multi-number organizations, since otherwise the oldest connected number of the channel is used.

Parameters

No parameters.

Responses

200

Examples

bash

curl -X GET "https://api.cognizy.ai/api/v1/public/whatsapp/numbers" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

Send a WhatsApp message

post/v1/public/whatsapp/messages

Needs approvalAccepts Idempotency-Key

Sends a WhatsApp message directly (text, media or approved template) without creating an inbox conversation. Returns 202 with the queued message id; the final status is tracked on the message and pushed via webhooks. Pass an Idempotency-Key header to safely retry without duplicating the send. Use instanceId to choose which of your numbers sends (required in practice for multi-number organizations), or channel to pick a channel and let the oldest connected number of that channel be used. On the official CLOUD_API channel, free-form text/media require an open 24h session window with the recipient — outside it, use an approved template. The unofficial EVOLUTION channel has no window and no templates, but is subject to a per-number anti-ban rate cap.

Answers 202 with the request: the action only happens after someone approves it in To review or in the AI approvals tab.

Parameters

idempotency-keystringrequired· header

Field	In	Type	Description
`idempotency-key`required	header	string

Body (JSON)required

tostringrequired: Recipient in E.164 (digits)
instanceIdstringoptional: Send from this specific WhatsApp number (WhatsAppInstance id). Required in practice for multi-number organizations; omit it and the oldest-created connected number of the selected channel is used. Takes precedence over channel.
channelstringoptional: Which WhatsApp channel to send through when no instanceId is given. CLOUD_API is the official Meta channel (supports templates, subject to the 24h session window). EVOLUTION is the unofficial channel (free-form text/media only, no templates, subject to the instance's daily anti-ban cap). Defaults to CLOUD_API.CLOUD_APIEVOLUTION
typestringrequired: TEXTMEDIATEMPLATE
textstringoptional: Body for type=TEXT
mediaobjectoptional
media.urlstringrequired
media.typestringrequired: imagevideodocumentaudio
media.captionstringoptional
templateobjectoptional
template.namestringrequired: Approved Meta template name
template.languagestringoptional
template.variablesstring[]optional: Positional body variables, in order

Field	Type	Description
`to`required	string	Recipient in E.164 (digits)
`instanceId`optional	string	Send from this specific WhatsApp number (WhatsAppInstance id). Required in practice for multi-number organizations; omit it and the oldest-created connected number of the selected channel is used. Takes precedence over `channel`.
`channel`optional	string	Which WhatsApp channel to send through when no instanceId is given. CLOUD_API is the official Meta channel (supports templates, subject to the 24h session window). EVOLUTION is the unofficial channel (free-form text/media only, no templates, subject to the instance's daily anti-ban cap). Defaults to CLOUD_API.`CLOUD_APIEVOLUTION`
`type`required	string	`TEXTMEDIATEMPLATE`
`text`optional	string	Body for type=TEXT
`media`optional	object
`media.url`required	string
`media.type`required	string	`imagevideodocumentaudio`
`media.caption`optional	string
`template`optional	object
`template.name`required	string	Approved Meta template name
`template.language`optional	string
`template.variables`optional	string[]	Positional body variables, in order

Responses

202Message accepted and queued

Examples

bash

curl -X POST "https://api.cognizy.ai/api/v1/public/whatsapp/messages" \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "to": "5511999999999",
  "instanceId": "clx7k2p9a0001qwerty",
  "channel": "CLOUD_API",
  "type": "TEXT",
  "text": "Olá! Seu pedido saiu.",
  "media": {
    "url": "https://example.com/file.pdf",
    "type": "image",
    "caption": "texto"
  },
  "template": {
    "name": "order_update",
    "language": "pt_BR",
    "variables": [
      "Maria",
      "#1234"
    ]
  }
}'

Get the status of a sent message

get/v1/public/whatsapp/messages/{id}

Parameters

idstringrequired· path: OutboundMessage id returned by POST

Field	In	Type	Description
`id`required	path	string	OutboundMessage id returned by POST

Responses

200

Examples

bash

curl -X GET "https://api.cognizy.ai/api/v1/public/whatsapp/messages/<id>" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

Full reference