ZEzenzap
Topics (group chats/channels/conversations)

Get topic messages

Get messages from a topic with cursor-based pagination. Messages are returned in the specified order.

Authorization: Your API key bot must be a member of the topic to access its messages.

Pagination: Use the cursor parameter with the value from nextCursor in the response to get the next page. The before and after parameters are mutually exclusive - use one or the other, not both.

Note: For security reasons, a 404 response is returned both when the topic does not exist and when your bot is not a member of the topic.

get/v2/topics/{topicId}/messages

Request

Path parameters

topicIdstring uuid required

The ID of the topic to get messages from

Query parameters

limitinteger

Maximum number of messages to return (default: 50, max: 100)

cursorstring

Opaque cursor for pagination. Use the value from nextCursor in the response. Cursors are cryptographically signed and validated server-side to prevent tampering.

beforeinteger

Return messages created before this timestamp (Unix milliseconds). Mutually exclusive with after.

afterinteger

Return messages created after this timestamp (Unix milliseconds). Mutually exclusive with before.

senderIdstring

Filter messages by sender ID

order'asc' | 'desc'

Sort order for messages (default: desc - newest first)

includeSystemboolean

Include system messages (default: true)

threadIdstring uuid

Filter to messages within a specific thread (replies to a parent message)

includeReactionUsersboolean

Include user IDs in reaction data (default: false, heavier payload)

Headers

X-Signaturestring
Example:a3d5f8e7c2b1d4f6a8e9c7b5d3f1a2e4b6c8d0f2e4a6b8c0d2e4f6a8b0c2d4e6

HMAC signature of the request for authentication and replay protection.

Required only when authenticating with a static API key. If you are using an OAuth access token (issued by POST /oauth/token), omit this header — the JWT carries all the authentication and integrity guarantees.

Replay Protection: The signature includes a timestamp to prevent replay attacks. Requests with timestamps older than 5 minutes are rejected.

The signature payload differs by HTTP method:

  • POST/PUT/PATCH/DELETE: HMAC-SHA256 of {timestamp}.{body}
  • GET: HMAC-SHA256 of {timestamp}.{uri}

The signature is calculated as:

  1. Get the current Unix timestamp in milliseconds
  2. Determine the payload:
    • For POST/PUT/PATCH/DELETE: Use {timestamp}.{body} where body is the request body
    • For GET: Use {timestamp}.{uri} where uri is the full request URI (e.g., /v2/members?limit=10)
  3. Calculate HMAC-SHA256 of the combined payload using your API secret
  4. Hex-encode the output
  5. Include the timestamp in the X-Timestamp header

Example for GET request to /v2/members?limit=10:

timestamp = 1699564800000
payload = "1699564800000./v2/members?limit=10"
signature = HMAC-SHA256(secret, payload)
X-Signature: hex(signature)
X-Timestamp: 1699564800000

Example for POST request with body {"topicId":"123","text":"Hello"}:

timestamp = 1699564800000
payload = '1699564800000.{"topicId":"123","text":"Hello"}'
signature = HMAC-SHA256(secret, payload)
X-Signature: hex(signature)
X-Timestamp: 1699564800000

For multipart/form-data requests, sign the exact raw request body bytes (including boundaries and file bytes) as transmitted.

X-Timestampinteger
Example:1699564800000

Unix timestamp in milliseconds when the request was created. Used for replay protection — requests older than 5 minutes are rejected.

Required only when authenticating with a static API key. Omit when using an OAuth access token.

Response

Messages retrieved successfully

nextCursorstring

Cursor for the next page. Pass this value to the cursor parameter to get the next page.

hasMoreboolean

Whether there are more messages to fetch

Example response

{
  "messages": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "topicId": "550e8400-e29b-41d4-a716-446655440000",
      "senderId": "550e8400-e29b-41d4-a716-446655440001",
      "senderName": "Alice Johnson",
      "senderType": "user",
      "type": "text",
      "text": "Hello team!",
      "createdAt": 1699564800000,
      "updatedAt": 1699564800000,
      "attachmentDetails": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440088",
          "type": "audio",
          "name": "voice-note.mp3",
          "url": "https://storage.zenzap.co/attachments/...",
          "transcription": {
            "status": "Done",
            "text": "Hey team, just a quick update on the project..."
          }
        }
      ],
      "mentionDetails": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440001",
          "name": "Alice Johnson"
        }
      ],
      "reactions": [
        {
          "emoji": "👍",
          "count": 3,
          "userIds": [
            "550e8400-e29b-41d4-a716-446655440001"
          ]
        }
      ],
      "poll": {
        "id": "770e8400-e29b-41d4-a716-446655440010",
        "title": "Lunch spot?",
        "options": [
          {
            "id": "opt-1",
            "text": "Tacos"
          }
        ]
      },
      "task": {
        "title": "Review documentation",
        "text": "Please review the API docs by Friday",
        "assignee": "550e8400-e29b-41d4-a716-446655440001",
        "dueDate": 1699651200000,
        "subItemsCount": 3
      },
      "contact": {
        "name": "John Doe",
        "phoneNumbers": [
          "+1234567890"
        ],
        "emails": [
          "john@example.com"
        ],
        "role": "Engineer",
        "location": "San Francisco",
        "linkedIn": "https://linkedin.com/in/johndoe",
        "profileId": "550e8400-e29b-41d4-a716-446655440001"
      },
      "location": {
        "latitude": "37.7749",
        "longitude": "-122.4194",
        "name": "San Francisco Office",
        "address": "123 Market St, San Francisco, CA"
      },
      "call": {
        "initiatorId": "550e8400-e29b-41d4-a716-446655440001"
      }
    }
  ],
  "nextCursor": "eyJ0IjoxNjk5NTY0NzAwMDAwLCJpZCI6IjY2MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMiIsIm8iOiJkZXNjIn0=",
  "hasMore": true
}

Changes

No recorded changes to this operation across all 1 revision of this API.