Long Polling

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:

Parameter	Type	Description
`offset`	string	Opaque cursor from the previous response (`nextOffset`). Omit on first call.
`limit`	integer	Max updates to return. Default `50`, max `100`.
`timeout`	integer	Wait 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": "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.

Mentions

Mentions are included in message events (message.created, message.updated).

data.message.mentions: mention objects (id, name)
data.message.mentionedProfiles: optional list of mentioned profile IDs

Example:

{
  "eventType": "message.created",
  "data": {
    "message": {
      "text": "Hi <@550e8400-e29b-41d4-a716-446655440001>, can you review this?",
      "mentionedProfiles": ["550e8400-e29b-41d4-a716-446655440001"],
      "mentions": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440001",
          "name": "Alice Johnson"
        }
      ]
    }
  }
}

data.message.text keeps the mention token format (<@profileId>), while mentions[] provides resolved display names.

Attachments

Attachments are included directly in polling message events (message.created, message.updated) under data.message.attachments. Attachment fields:

Field	Type	Description
`id`	string	Attachment ID
`type`	string	`image`, `file`, `video`, `audio`
`name`	string	Original filename (when available)
`url`	string	Signed download URL
`transcription`	object	Audio transcription status/details (voice messages only)

Example:

{
  "eventType": "message.created",
  "data": {
    "message": {
      "type": "audio",
      "attachments": [
        {
          "id": "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

Overview

Messages

Topics (group chats/channels/conversations)

Org units

Tasks

Members

Polls

OAuth

Agentic

Long Polling

Requirements

Endpoint

Response Shape

Event Payloads

Mentions

Attachments

Errors

​Requirements

​Endpoint

​Response Shape

​Event Payloads

​Mentions

​Attachments

​Errors

Requirements

Endpoint

Response Shape

Event Payloads

Mentions

Attachments

Errors