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.notes.createNote({
chat_id: '120363000000000000@g.us',
});
console.log(response);
}
main();curl -X POST 'https://api.periskope.app/v1/notes/create' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'x-phone: 919876543210' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "120363000000000000@g.us"
}'{
"success": true,
"message": "A Private note created successfully",
"data": {
"message_id": "true_00000000-0000-0000-0000-000000000000_api",
"org_id": "00000000-0000-0000-0000-000000000000",
"org_phone": "911111111111@c.us",
"chat_id": "120363000000000000@g.us",
"body": "Customer asked for a callback tomorrow @user@example.com",
"message_type": "chat",
"media": {
"path": "https://example.com/files/image.png",
"mimetype": "image/png",
"filename": "image.png"
},
"is_private_note": true,
"from_me": true,
"performed_by": "api",
"quoted_message_id": "true_00000000-0000-0000-0000-000000000000_api",
"mentioned_ids": [
"user@example.com"
],
"timestamp": "2026-01-15T09:30:00.000Z",
"updated_at": "2026-01-15T09:30:00.000Z"
}
}{
"code": "UNAUTHORIZED_ERROR",
"message": "Invalid bearer auth token",
"status": 401
}{
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 422,
"fields": {
"body.chat_id": {
"message": "chat_id is required"
}
}
}{
"code": "RATE_LIMIT_ERROR",
"message": "You can only make 100 requests per second",
"status": 429
}{
"code": "UNKNOWN_ERROR",
"message": "Internal server error",
"status": 500
}Send Private Notes
Adds a private note (message, media, or both) to a chat. Notes are internal — never sent to WhatsApp. @-mentioning a member email creates a task for them.
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.notes.createNote({
chat_id: '120363000000000000@g.us',
});
console.log(response);
}
main();curl -X POST 'https://api.periskope.app/v1/notes/create' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'x-phone: 919876543210' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "120363000000000000@g.us"
}'{
"success": true,
"message": "A Private note created successfully",
"data": {
"message_id": "true_00000000-0000-0000-0000-000000000000_api",
"org_id": "00000000-0000-0000-0000-000000000000",
"org_phone": "911111111111@c.us",
"chat_id": "120363000000000000@g.us",
"body": "Customer asked for a callback tomorrow @user@example.com",
"message_type": "chat",
"media": {
"path": "https://example.com/files/image.png",
"mimetype": "image/png",
"filename": "image.png"
},
"is_private_note": true,
"from_me": true,
"performed_by": "api",
"quoted_message_id": "true_00000000-0000-0000-0000-000000000000_api",
"mentioned_ids": [
"user@example.com"
],
"timestamp": "2026-01-15T09:30:00.000Z",
"updated_at": "2026-01-15T09:30:00.000Z"
}
}{
"code": "UNAUTHORIZED_ERROR",
"message": "Invalid bearer auth token",
"status": 401
}{
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 422,
"fields": {
"body.chat_id": {
"message": "chat_id is required"
}
}
}{
"code": "RATE_LIMIT_ERROR",
"message": "You can only make 100 requests per second",
"status": 429
}{
"code": "UNKNOWN_ERROR",
"message": "Internal server error",
"status": 500
}Authorizations
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.
Headers
Optional. Phone to act with: country code + number without symbols or spaces (e.g. 911111111111), or a phone_id (phone-xxxxxxxxxxxx). Omit to let the API select an eligible phone automatically — within the token's phone scopes and connected; chat actions use a phone that has the chat (a group admin where required), message actions use the phone the message belongs to.
"919876543210"
Body
Chat to add the note to. For group chats, the chat_id ending with @g.us; for 1-1 chats, country code + number of the contact suffixed with @c.us, e.g. 911111111111@c.us
1"120363000000000000@g.us"
Text content of the note, or the caption when media is provided. Supports the basic WhatsApp markdown formatting (bold, italic, strikethrough, monospace). @-mentioning a member email (e.g. @user@example.com) creates a task assigned to that member. Required unless media is provided.
"Customer asked for a callback tomorrow @user@example.com"
Attachment for the note. Provide either a public url or base64/data-URI filedata (uploaded to Periskope storage). Required unless message is provided.
Show child attributes
Show child attributes
message_id of an existing message or note in the chat that this note replies to. Stored on the note as quoted_message_id.
"true_00000000-0000-0000-0000-000000000000_api"
Was this page helpful?