Skip to main content
Long polling lets your integration fetch outbound events instead of receiving webhooks.

​
Requirements

  • API key delivery mode must be polling
  • A bot can use either polling or webhooks, not both at the same time
  • Requests use the same auth/signature flow as the rest of the API:
    • Authorization: Bearer <API_KEY>
    • X-Timestamp: <Unix milliseconds>
    • X-Signature: HMAC-SHA256("{timestamp}.{uri}") for this GET endpoint

​
Endpoint

Use GET /v2/updates. Query parameters:
ParameterTypeDescription
offsetstringOpaque cursor from the previous response (nextOffset). Omit on first call.
limitintegerMax updates to return. Default 50, max 100.
timeoutintegerWait time in seconds when no updates are available. Default 0, max 30.
Behavior:
  • If updates exist after offset, response returns immediately
  • If no updates and timeout > 0, request waits up to timeout seconds
  • If still no updates, returns updates: [] and a nextOffset

​
Response Shape

{
  "updates": [
    {
      "updateId": "AAAAAAABAAAAAAAAAAABAA==",
      "eventType": "message.created",
      "createdAt": 1699564800000,
      "data": {
        "message": {
          "id": "660e8400-e29b-41d4-a716-446655440001",
          "topicId": "550e8400-e29b-41d4-a716-446655440000",
          "senderId": "u@550e8400-e29b-41d4-a716-446655440001",
          "senderType": "user",
          "senderName": "Alice Johnson",
          "type": "text",
          "text": "Hello team!",
          "createdAt": 1699564800000
        },
        "truncated": false
      }
    }
  ],
  "nextOffset": "AAAAAAABAAAAAAAAAAABAA=="
}
Use nextOffset from each response as the offset in your next request.

​
Event Payloads

Polling data payloads match webhook data payloads for the same event type. See Webhook Events for field-level payload details.

​
Attachments

Attachments are included directly in polling message events (message.created, message.updated) under data.message.attachments. Attachment fields:
FieldTypeDescription
idstringAttachment ID
typestringimage, file, video, audio
namestringOriginal filename (when available)
urlstringSigned download URL
transcriptionobjectAudio transcription status/details (voice messages only)
Example: 
{
  "eventType": "message.created",
  "data": {
    "message": {
      "type": "audio",
      "attachments": [
        {
          "id": "att_550e8400-e29b-41d4-a716-446655440088",
          "type": "audio",
          "name": "voice-note.mp3",
          "url": "https://storage.zenzap.co/attachments/...?token=...&expires=...",
          "transcription": {
            "status": "Pending"
          }
        }
      ]
    }
  }
}
Notes:
  • Attachment url is signed and expires (currently 60 minutes)
  • Voice transcription is asynchronous:
    • message.created usually arrives with transcription.status: "Pending"
    • message.updated can arrive later with status: "Done" and text
Supported event types:
  • message.created
  • message.updated
  • message.deleted
  • reaction.added
  • reaction.removed
  • member.added
  • member.removed
  • topic.updated

​
Errors

  • 400 bad request (invalid offset, limit, or timeout)
  • 401 unauthorized
  • 409 delivery mode is not polling, or provided offset is no longer available
  • 500 internal server error