> ## 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.

# The Chat Notification Object

> 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.

```json The Chat Notification Object theme={null}
{
  "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": [
        {
          "agent_id": "agent@example.com",
          "path": "00000000-0000-0000-0000-000000000000/phone-aaaaaaaaaaaaaaaa/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.agent-0.wav",
          "url": "https://api.periskope.app/app/media/periskope-call-attachments/00000000-0000-0000-0000-000000000000/phone-aaaaaaaaaaaaaaaa/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.agent-0.wav?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
        }
      ],
      "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": [
        {
          "t": 12.4,
          "speaker": "John Doe",
          "text": "Hi, I wanted to check on my order."
        }
      ]
    },
    "summary": {
      "text": "The customer asked about a delayed order. The agent confirmed it ships tomorrow and shared the tracking link.",
      "tags": [
        null
      ]
    }
  }
}
```

**Attributes**

**notification\_id** `string`

Unique id of the notification, in the form \<from\_me>*\<chat\_id>*\<wa\_id>*\<author>*\<type>

**org\_id** `string`

Id of the organization the notification belongs to

**org\_phone** `string`

Org phone (WhatsApp account) the notification was observed on, as country code + number suffixed with @c.us

**chat\_id** `string`

Chat the notification belongs to

**author** `string`

Participant who performed the action (\<countrycode>\<number>@c.us)

**body** `string`

Text of the notification, when WhatsApp provides one

**type** `string`

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).

**recipientids** `string[]`

Participants affected by the event (e.g. the contacts that were added or removed).

**id** `object`

Raw WhatsApp id object of the notification (id, remote, fromMe, serialized)

**properties**

**timestamp** `string`

When the event happened, as an ISO 8601 UTC timestamp

**unique\_id** `string`

WhatsApp id of the notification without the id prefix

**metadata** `object`

Extra event metadata, when present. On call rows: direction, result and timing as reported by WhatsApp.

**call\_metadata** `object`

On call rows handled in Periskope: the recording as stored plus a downloadable url, participants, transcript and summary. null on other rows.

**properties**

**recording** `object`

The call recording, when the call was recorded in Periskope.

**properties**

**provider** `string`

Where the recording is stored ('gcs'). Internal; use url to download.

**bucket** `string`

Private storage bucket of the recording. Internal and not publicly readable; use url to download.

**path** `string`

Object path of the recording inside bucket. Internal; use url to download.

**url** `string`

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.

**url\_expires\_at** `string`

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.

**duration\_seconds** `integer`

Length of the recording in seconds.

**channels** `object`

What each stereo channel carries: left is the customer, right is every Periskope member on the call mixed together.

**properties**

**left** `string`

**right** `string`

**agent\_tracks** `object[]`

One separate recording per member on the call, when captured.

**each item**

**agent\_id** `string`

Email of the member this track belongs to.

**path** `string`

Object path of this member's track inside the recording's bucket. Internal; use url to download.

**url** `string`

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.

**recorded\_at** `string`

When the recording was saved, as an ISO 8601 UTC timestamp.

**truncated** `boolean`

true when the recording hit the size cap and stops before the call ended. Absent otherwise.

**answered\_by** `string`

Email of the member who answered or placed the call in Periskope.

**participants** `object[]`

Periskope members on the call, in join order.

**each item**

**agent\_id** `string`

Email of the member.

**role** `string`

'Host' for the member who answered or placed the call, 'Joined' for members who joined later.

**transcript** `object`

**properties**

**status** `string`

'pending', 'done' or 'failed'.

**utterances** `object[]`

The transcript, line by line, once status is done.

**each item**

**t** `number`

Offset into the recording where this line starts, in seconds.

**speaker** `string`

The customer's name (or number), or a member's email.

**text** `string`

What was said.

**summary** `object`

AI summary of the call, once generated.

**properties**

**text** `string`

**tags** `string[]`

Topic tags, present only on summaries generated before tags were discontinued (September 2026). Returned as stored.


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