Skip to content
CognizyCognizyHelp
Sign in
In this area

Messages

Send and read messages, including SSE streaming.

List messages

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

Returns messages of a conversation in cursor-paginated form.

Parameters

idstringrequired· path
limitnumberoptional· query
Maximum number of messages to return (1–100).
cursorstringoptional· query
Pagination cursor — pass nextCursor from the previous response.
orderasc | descoptional· query
Sort order. Default asc (oldest first).

Responses

  • 200

Examples

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

Send message

post/v1/public/conversations/{id}/messages

Accepts Idempotency-Key

Sends a contact message and returns the AI reply (when AI is active on the conversation). Use the /stream variant for SSE streaming.

Parameters

idstringrequired· path

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

Responses

  • 201

Examples

bash
curl -X POST "https://api.cognizy.ai/api/v1/public/conversations/<id>/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"
    ]
  }
}'

Send message (streaming SSE)

post/v1/public/conversations/{id}/messages/stream

Streaming (SSE)Accepts Idempotency-Key

Sends a contact message and returns the AI reply via Server-Sent Events. Event types: token, done, error. Heartbeat every 15s as : keepalive comments.

Parameters

idstringrequired· path
Conversation ID

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

Responses

  • 200SSE stream with `token`, `done`, and (on failure) `error` events
  • 400Missing or invalid `message`
  • 404Conversation not found
  • 429Concurrent stream limit (20 per API key) reached

Examples

bash
curl -X POST "https://api.cognizy.ai/api/v1/public/conversations/<id>/messages/stream" \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Accept: text/event-stream" \
  -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"
    ]
  }
}' \
  --no-buffer

Full reference