> ## Documentation Index
> Fetch the complete documentation index at: https://docs.periskope.app/llms.txt
> Use this file to discover all available pages before exploring further.

# List All Notifications

> Returns group system events (participants added or removed, admin and setting changes) and call-log entries (type "call") across all chats, newest first. Call entries carry downloadable recording links in call_metadata; the Calls endpoints return calls in a cleaner shape with filters.



## OpenAPI

````yaml api-reference/openapi-generated.json GET /v1/chats/notifications
openapi: 3.0.3
info:
  title: Periskope API
  version: 1.0.0
  description: >-
    Periskope external API.


    Responses use a flat, unwrapped shape: most endpoints return the resource at
    the top level, and list endpoints return a wrapper object with pagination
    inline (e.g. `{ from, to, count, chats: [...] }`). The documented response
    schemas describe these shapes directly.
servers:
  - url: https://api.periskope.app
security:
  - bearerAuth: []
paths:
  /v1/chats/notifications:
    get:
      tags:
        - Chats
      summary: List notifications across chats
      description: >-
        Returns group system events (participants added or removed, admin and
        setting changes) and call-log entries (type "call") across all chats,
        newest first. Call entries carry downloadable recording links in
        call_metadata; the Calls endpoints return calls in a cleaner shape with
        filters.
      operationId: listChatNotifications
      parameters:
        - schema:
            type: integer
            nullable: true
            minimum: 0
            description: >-
              Number of records to skip before the first returned record. Use
              together with limit to paginate: page N is offset = N * limit.
              Defaults to 0.
            example: 0
          required: false
          description: >-
            Number of records to skip before the first returned record. Use
            together with limit to paginate: page N is offset = N * limit.
            Defaults to 0.
          name: offset
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 2000
            description: >-
              Maximum number of records to return in one page. Cannot exceed
              2000. Defaults to 1000.
            example: 1000
          required: false
          description: >-
            Maximum number of records to return in one page. Cannot exceed 2000.
            Defaults to 1000.
          name: limit
          in: query
        - schema:
            type: string
            description: >-
              Only return records at or after this time. Accepts ISO 8601 (e.g.
              2026-01-01T00:00:00Z) and common date formats (YYYY-MM-DD,
              YYYY-MM-DD HH:mm, DD/MM/YYYY). Epoch timestamps are not supported.
              Compared at minute precision.
            example: '2026-01-01T00:00:00Z'
          required: false
          description: >-
            Only return records at or after this time. Accepts ISO 8601 (e.g.
            2026-01-01T00:00:00Z) and common date formats (YYYY-MM-DD,
            YYYY-MM-DD HH:mm, DD/MM/YYYY). Epoch timestamps are not supported.
            Compared at minute precision.
          name: start_time
          in: query
        - schema:
            type: string
            description: >-
              Only return records at or before this time. Accepts ISO 8601 (e.g.
              2026-01-01T00:00:00Z) and common date formats (YYYY-MM-DD,
              YYYY-MM-DD HH:mm, DD/MM/YYYY). Epoch timestamps are not supported.
              Compared at minute precision.
            example: '2026-01-31T23:59:00Z'
          required: false
          description: >-
            Only return records at or before this time. Accepts ISO 8601 (e.g.
            2026-01-01T00:00:00Z) and common date formats (YYYY-MM-DD,
            YYYY-MM-DD HH:mm, DD/MM/YYYY). Epoch timestamps are not supported.
            Compared at minute precision.
          name: end_time
          in: query
        - schema:
            type: string
            description: >-
              Case-insensitive substring search across the notification type
              (and chat_id on the workspace-wide list). Composes with the other
              filters.
            example: hello
          required: false
          description: >-
            Case-insensitive substring search across the notification type (and
            chat_id on the workspace-wide list). Composes with the other
            filters.
          name: q
          in: query
        - schema:
            type: string
            example: '919876543210'
            description: >-
              Optional. Scope results to a single phone: country code + number
              without symbols or spaces (e.g. 911111111111), or a phone_id
              (phone-xxxxxxxxxxxx). Omit to return data across all phones the
              API token can access.
          required: false
          description: >-
            Optional. Scope results to a single phone: country code + number
            without symbols or spaces (e.g. 911111111111), or a phone_id
            (phone-xxxxxxxxxxxx). Omit to return data across all phones the API
            token can access.
          name: x-phone
          in: header
      responses:
        '200':
          description: >-
            Paginated list of notifications, newest first (under the messages
            key)
          content:
            application/json:
              schema:
                type: object
                properties:
                  from:
                    type: integer
                    description: >-
                      1-based index of the first record in this page (offset +
                      1).
                    example: 1
                  to:
                    type: integer
                    description: 1-based index of the last record in this page.
                    example: 20
                  count:
                    type: integer
                    description: >-
                      Number of records in this page — the length of the
                      `messages` array, not the total across all pages.
                    example: 20
                  start_time:
                    type: string
                    description: >-
                      Echo of the start_time filter, present only when it was
                      sent.
                    example: '2026-01-01T00:00:00Z'
                  end_time:
                    type: string
                    description: >-
                      Echo of the end_time filter, present only when it was
                      sent.
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChatNotification'
                    description: The messages in this page.
              examples:
                default:
                  summary: Response body
                  value:
                    from: 1
                    to: 20
                    count: 20
                    start_time: '2026-01-01T00:00:00Z'
                    end_time: null
                    messages:
                      - notification_id: >-
                          true_120363000000000000@g.us_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_911111111111@c.us_add
                        org_id: 00000000-0000-0000-0000-000000000000
                        org_phone: 911111111111@c.us
                        chat_id: 120363000000000000@g.us
                        author: 911111111111@c.us
                        body: null
                        type: add
                        recipientids:
                          - 922222222222@c.us
                        id:
                          id: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
                          fromMe: true
                          remote: 120363000000000000@g.us
                          serialized: >-
                            true_120363000000000000@g.us_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_911111111111@c.us_add
                        timestamp: '2026-01-15T09:30:00+00:00'
                        unique_id: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
                        metadata: null
                        call_metadata:
                          recording:
                            provider: gcs
                            bucket: periskope-call-attachments
                            path: >-
                              00000000-0000-0000-0000-000000000000/phone-aaaaaaaaaaaaaaaa/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.wav
                            url: >-
                              https://api.periskope.app/app/media/periskope-call-attachments/00000000-0000-0000-0000-000000000000/phone-aaaaaaaaaaaaaaaa/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.wav?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                            url_expires_at: '2026-01-15T10:30:00.000Z'
                            duration_seconds: 184
                            channels:
                              left: customer
                              right: agents
                            agent_tracks: []
                            recorded_at: '2026-01-15T09:33:10.000Z'
                            truncated: true
                          answered_by: agent@example.com
                          participants:
                            - agent_id: agent@example.com
                              role: Host
                          transcript:
                            status: done
                            utterances: []
                          summary:
                            text: >-
                              The customer asked about a delayed order. The
                              agent confirmed it ships tomorrow and shared the
                              tracking link.
                            tags: []
        '401':
          description: Invalid, expired or missing API token
          content:
            application/json:
              examples:
                error:
                  summary: Invalid, expired or missing API token
                  value:
                    code: UNAUTHORIZED_ERROR
                    message: Invalid bearer auth token
                    status: 401
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: UNAUTHORIZED_ERROR
                  message:
                    type: string
                    example: Invalid bearer auth token
                  status:
                    type: integer
                    example: 401
                example:
                  code: UNAUTHORIZED_ERROR
                  message: Invalid bearer auth token
                  status: 401
        '422':
          description: Request validation failed
          content:
            application/json:
              examples:
                error:
                  summary: Request validation failed
                  value:
                    code: VALIDATION_ERROR
                    message: Request validation failed
                    status: 422
                    fields:
                      body.chat_id:
                        message: chat_id is required
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: VALIDATION_ERROR
                  message:
                    type: string
                    example: Request validation failed
                  status:
                    type: integer
                    example: 422
                  fields:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        message:
                          type: string
                        value: {}
                    example:
                      body.chat_id:
                        message: chat_id is required
                example:
                  code: VALIDATION_ERROR
                  message: Request validation failed
                  status: 422
                  fields:
                    body.chat_id:
                      message: chat_id is required
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              examples:
                error:
                  summary: Rate limit exceeded
                  value:
                    code: RATE_LIMIT_ERROR
                    message: You can only make 100 requests per second
                    status: 429
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: RATE_LIMIT_ERROR
                  message:
                    type: string
                    example: You can only make 100 requests per second
                  status:
                    type: integer
                    example: 429
                example:
                  code: RATE_LIMIT_ERROR
                  message: You can only make 100 requests per second
                  status: 429
        '500':
          description: Internal server error
          content:
            application/json:
              examples:
                error:
                  summary: Internal server error
                  value:
                    code: UNKNOWN_ERROR
                    message: Internal server error
                    status: 500
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: UNKNOWN_ERROR
                  message:
                    type: string
                    example: Internal server error
                  status:
                    type: integer
                    example: 500
                example:
                  code: UNKNOWN_ERROR
                  message: Internal server error
                  status: 500
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: typescript
          label: TypeScript
          source: |-
            import { PeriskopeApi } from '@periskope/periskope-client';

            const client = new PeriskopeApi({
              authToken: 'YOUR_API_KEY',
              phone: '919876543210', // the phone to act with (x-phone)
            });

            async function main() {
              const response = await client.chats.listChatNotifications();
              console.log(response);
            }

            main();
        - lang: bash
          label: cURL
          source: |-
            curl -X GET 'https://api.periskope.app/v1/chats/notifications' \
              -H 'Authorization: Bearer YOUR_API_KEY' \
              -H 'x-phone: 919876543210'
components:
  schemas:
    ChatNotification:
      type: object
      properties:
        notification_id:
          type: string
          description: >-
            Unique id of the notification, in the form
            <from_me>_<chat_id>_<wa_id>_<author>_<type>
          example: >-
            true_120363000000000000@g.us_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_911111111111@c.us_add
        org_id:
          type: string
          format: uuid
          description: Id of the organization the notification belongs to
          example: 00000000-0000-0000-0000-000000000000
        org_phone:
          type: string
          description: >-
            Org phone (WhatsApp account) the notification was observed on, as
            country code + number suffixed with @c.us
          example: 911111111111@c.us
        chat_id:
          type: string
          description: Chat the notification belongs to
          example: 120363000000000000@g.us
        author:
          type: string
          description: Participant who performed the action (<countrycode><number>@c.us)
          example: 911111111111@c.us
        body:
          type: string
          description: Text of the notification, when WhatsApp provides one
        type:
          type: string
          description: >-
            Kind of event: a group event such as 'add', 'remove', 'promote',
            'demote', 'leave', 'invite', 'create', 'subject', 'picture',
            'memberaddmode_true', 'memberaddmode_false', or 'call' for a
            call-log entry (see call_metadata, or use the Calls endpoints).
          example: add
        recipientids:
          type: array
          items:
            type: string
          description: >-
            Participants affected by the event (e.g. the contacts that were
            added or removed).
          example:
            - 922222222222@c.us
        id:
          type: object
          properties: {}
          description: >-
            Raw WhatsApp id object of the notification (id, remote, fromMe,
            serialized)
          example:
            id: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
            fromMe: true
            remote: 120363000000000000@g.us
            serialized: >-
              true_120363000000000000@g.us_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_911111111111@c.us_add
        timestamp:
          type: string
          description: When the event happened, as an ISO 8601 UTC timestamp
          example: '2026-01-15T09:30:00+00:00'
        unique_id:
          type: string
          description: WhatsApp id of the notification without the id prefix
          example: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
        metadata:
          description: >-
            Extra event metadata, when present. On call rows: direction, result
            and timing as reported by WhatsApp.
        call_metadata:
          $ref: '#/components/schemas/NotificationCallMetadata'
      description: >-
        A chat notification — a group system event such as participants being
        added or removed, admin changes or setting changes, or a call-log entry
        (type "call"). Stored in tbl_chat_notifications.
    NotificationCallMetadata:
      type: object
      properties:
        recording:
          type: object
          properties:
            provider:
              type: string
              description: >-
                Where the recording is stored ('gcs'). Internal; use url to
                download.
              example: gcs
            bucket:
              type: string
              description: >-
                Private storage bucket of the recording. Internal and not
                publicly readable; use url to download.
              example: periskope-call-attachments
            path:
              type: string
              description: >-
                Object path of the recording inside bucket. Internal; use url to
                download.
              example: >-
                00000000-0000-0000-0000-000000000000/phone-aaaaaaaaaaaaaaaa/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.wav
            url:
              type: string
              description: >-
                Downloadable link to the call recording, a stereo WAV file,
                added by the API beside the stored location. When the
                organization's media privacy is on, the link carries an access
                token, opens without other credentials and stops working 1 hour
                after the response (url_expires_at); fetch the call again for a
                fresh link. When media privacy is off, it is a plain link that
                opens without credentials and does not expire.
              example: >-
                https://api.periskope.app/app/media/periskope-call-attachments/00000000-0000-0000-0000-000000000000/phone-aaaaaaaaaaaaaaaa/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.wav?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
            url_expires_at:
              type: string
              description: >-
                When url (and every agent_tracks url) stops working, as an ISO
                8601 UTC timestamp: 1 hour after the response. Present only when
                the organization's media privacy is on; without it the links do
                not expire.
              example: '2026-01-15T10:30:00.000Z'
            duration_seconds:
              type: integer
              description: Length of the recording in seconds.
              example: 184
            channels:
              type: object
              properties:
                left:
                  type: string
                right:
                  type: string
              description: >-
                What each stereo channel carries: left is the customer, right is
                every Periskope member on the call mixed together.
              example:
                left: customer
                right: agents
            agent_tracks:
              type: array
              items:
                type: object
                properties:
                  agent_id:
                    type: string
                    description: Email of the member this track belongs to.
                    example: agent@example.com
                  path:
                    type: string
                    description: >-
                      Object path of this member's track inside the recording's
                      bucket. Internal; use url to download.
                    example: >-
                      00000000-0000-0000-0000-000000000000/phone-aaaaaaaaaaaaaaaa/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.agent-0.wav
                  url:
                    type: string
                    description: >-
                      Downloadable link to this member's own audio, a mono WAV.
                      Added by the API. When the organization's media privacy is
                      on, the link carries an access token, opens without other
                      credentials and stops working 1 hour after the response
                      (url_expires_at); fetch the call again for a fresh link.
                      When media privacy is off, it is a plain link that opens
                      without credentials and does not expire.
                    example: >-
                      https://api.periskope.app/app/media/periskope-call-attachments/00000000-0000-0000-0000-000000000000/phone-aaaaaaaaaaaaaaaa/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.agent-0.wav?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
              description: One separate recording per member on the call, when captured.
            recorded_at:
              type: string
              description: When the recording was saved, as an ISO 8601 UTC timestamp.
              example: '2026-01-15T09:33:10.000Z'
            truncated:
              type: boolean
              description: >-
                true when the recording hit the size cap and stops before the
                call ended. Absent otherwise.
              example: true
          description: The call recording, when the call was recorded in Periskope.
        answered_by:
          type: string
          description: Email of the member who answered or placed the call in Periskope.
          example: agent@example.com
        participants:
          type: array
          items:
            type: object
            properties:
              agent_id:
                type: string
                description: Email of the member.
                example: agent@example.com
              role:
                type: string
                description: >-
                  'Host' for the member who answered or placed the call,
                  'Joined' for members who joined later.
                example: Host
          description: Periskope members on the call, in join order.
        transcript:
          type: object
          properties:
            status:
              type: string
              description: '''pending'', ''done'' or ''failed''.'
              example: done
            utterances:
              type: array
              items:
                type: object
                properties:
                  t:
                    type: number
                    description: >-
                      Offset into the recording where this line starts, in
                      seconds.
                    example: 12.4
                  speaker:
                    type: string
                    description: The customer's name (or number), or a member's email.
                    example: John Doe
                  text:
                    type: string
                    description: What was said.
                    example: Hi, I wanted to check on my order.
              description: The transcript, line by line, once status is done.
        summary:
          type: object
          properties:
            text:
              type: string
              example: >-
                The customer asked about a delayed order. The agent confirmed it
                ships tomorrow and shared the tracking link.
            tags:
              type: array
              items:
                type: string
              description: >-
                Topic tags, present only on summaries generated before tags were
                discontinued (September 2026). Returned as stored.
          description: AI summary of the call, once generated.
      description: >-
        On call rows handled in Periskope: the recording as stored plus a
        downloadable url, participants, transcript and summary. null on other
        rows.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your Periskope API token, sent as `Authorization: Bearer <token>`.
        Generate one from the Periskope dashboard under **Settings → API &
        Webhooks**. API access requires an active Pro or Enterprise plan.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.