Skip to main content
Node.js
import { PeriskopeApi } from '@periskope/periskope-client';

const client = new PeriskopeApi({
  authToken: 'YOUR_API_KEY',
  phone: 'YOUR_PHONE_NUMBER', // Optional for this endpoint — omit to return notifications across all phones your token can access
});

async function getNotifications() {
  const response = await client.chat.getNotifications();

  console.log(response);
}

getNotifications();
# x-phone is optional for this endpoint — omit it to return notifications across all phones your token can access
curl -X GET \
  https://api.periskope.app/v1/chats/notifications \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'x-phone: YOUR_PHONE_NUMBER' \
{
  "count": 5,
  "from": 1,
  "messages": [
    {
      "author": "918527184400@c.us",
      "body": null,
      "chat_id": "120363371308389685@g.us",
      "id": {
        "fromMe": true,
        "id": "fa3c48a78cc64e139e5737f7057235ea",
        "remote": "120363371308389685@g.us",
        "serialized": "true_120363371308389685@g.us_fa3c48a78cc64e139e5737f7057235ea_918527184400@c.us_remove"
      },
      "notification_id": "true_120363371308389685@g.us_fa3c48a78cc64e139e5737f7057235ea_918527184400@c.us_remove",
      "org_id": "2997dd64-89bf-48d3-9a22-b314fca017e5",
      "org_phone": "918527184400@c.us",
      "recipientids": [
        "919537851844@c.us"
      ],
      "timestamp": "2025-01-11T11:52:27.231+00:00",
      "type": "remove",
      "unique_id": "fa3c48a78cc64e139e5737f7057235ea"
    },
    {
      "author": "918527184400@c.us",
      "body": null,
      "chat_id": "120363371308389685@g.us",
      "id": {
        "fromMe": true,
        "id": "fd73a0384afe4bc89991c3303cacab4b",
        "remote": "120363371308389685@g.us",
        "serialized": "true_120363371308389685@g.us_fd73a0384afe4bc89991c3303cacab4b_918527184400@c.us_remove"
      },
      "notification_id": "true_120363371308389685@g.us_fd73a0384afe4bc89991c3303cacab4b_918527184400@c.us_remove",
      "org_id": "2997dd64-89bf-48d3-9a22-b314fca017e5",
      "org_phone": "918527184400@c.us",
      "recipientids": [
        "919535999383@c.us"
      ],
      "timestamp": "2025-01-11T11:52:27.127+00:00",
      "type": "remove",
      "unique_id": "fd73a0384afe4bc89991c3303cacab4b"
    },
    {
      "author": "918527184400@c.us",
      "body": null,
      "chat_id": "120363371308389685@g.us",
      "id": {
        "fromMe": true,
        "id": "05f652baf6e54522b855d70ad43b813c",
        "remote": "120363371308389685@g.us",
        "serialized": "true_120363371308389685@g.us_05f652baf6e54522b855d70ad43b813c_918527184400@c.us_add"
      },
      "notification_id": "true_120363371308389685@g.us_05f652baf6e54522b855d70ad43b813c_918527184400@c.us_add",
      "org_id": "2997dd64-89bf-48d3-9a22-b314fca017e5",
      "org_phone": "918527184400@c.us",
      "recipientids": [
        "919537851844@c.us"
      ],
      "timestamp": "2025-01-11T11:52:16.859+00:00",
      "type": "add",
      "unique_id": "05f652baf6e54522b855d70ad43b813c"
    },
    {
      "author": "918527184400@c.us",
      "body": null,
      "chat_id": "120363371308389685@g.us",
      "id": {
        "fromMe": true,
        "id": "686bd17a4c3b4d7e9e84e5fe884de8bc",
        "remote": "120363371308389685@g.us",
        "serialized": "true_120363371308389685@g.us_686bd17a4c3b4d7e9e84e5fe884de8bc_918527184400@c.us_memberaddmode_false"
      },
      "notification_id": "true_120363371308389685@g.us_686bd17a4c3b4d7e9e84e5fe884de8bc_918527184400@c.us_memberaddmode_false",
      "org_id": "2997dd64-89bf-48d3-9a22-b314fca017e5",
      "org_phone": "918527184400@c.us",
      "recipientids": null,
      "timestamp": "2025-01-11T11:51:59.974+00:00",
      "type": "memberaddmode_false",
      "unique_id": "686bd17a4c3b4d7e9e84e5fe884de8bc"
    },
    {
      "author": "918527184400@c.us",
      "body": null,
      "chat_id": "120363371308389685@g.us",
      "id": {
        "fromMe": true,
        "id": "8c04cef4f58148ae91fc2654260bae55",
        "remote": "120363371308389685@g.us",
        "serialized": "true_120363371308389685@g.us_8c04cef4f58148ae91fc2654260bae55_918527184400@c.us_memberaddmode_true"
      },
      "notification_id": "true_120363371308389685@g.us_8c04cef4f58148ae91fc2654260bae55_918527184400@c.us_memberaddmode_true",
      "org_id": "2997dd64-89bf-48d3-9a22-b314fca017e5",
      "org_phone": "918527184400@c.us",
      "recipientids": null,
      "timestamp": "2025-01-11T11:51:51.177+00:00",
      "type": "memberaddmode_true",
      "unique_id": "8c04cef4f58148ae91fc2654260bae55"
    }
  ],
  "to": 5
}
{
  "code": "VALIDATION_ERROR",
  "fields": {
    "limit": {
      "message": "Limit should be less than 2000",
      "value": "10000"
    }
  },
  "message": "Limit should be less than ${MAX_LIMIT}",
  "name": "Validation Error",
  "status": 422
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-phone
string

Optional. The phone to scope this request to — in country code + number format with no spaces or special characters (e.g. 919876543210), or the phone_id (phone-xxxxxxxxxxxx). When set, only notifications for that phone are returned. When omitted, notifications are returned — across all phones your token can access (the phones in your token's scope, or every phone in your organization if the token is unscoped). Passing a phone that is outside your token's scope returns a 401.

Example:

"{{orgPhone}}"

Query Parameters

​
offset
number
  • The offset value for paginating the results
  • Default 0
Example:

"0"

​
limit
number
  • The maximum number of notifications to retrieve
  • Default 2000
Example:

"10"

​
start_time
string
  • The start_time to filter the results
Example:

"2025-04-25 or 2025-04-25T00:00:00Z"

​
end_time
string
  • The end_time to filter the results
Example:

"2025-04-31"

Response

​
from
number

The starting index of the returned notifications.

Example:

1

​
to
number

The ending index of the returned notifications.

Example:

10

​
count
number

The total count of notifications.

Example:

10

​
messages
array

An array of notification objects. Refer to the chat notification object here