> ## 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. # 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. ## OpenAPI ````yaml api-reference/openapi-generated.json POST /v1/notes/create 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/notes/create: post: tags: - Notes summary: Create a private note in a chat description: >- 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. operationId: createNote parameters: - schema: type: string example: '919876543210' description: >- 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. required: false description: >- 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. name: x-phone in: header requestBody: content: application/json: schema: type: object properties: chat_id: type: string minLength: 1 example: 120363000000000000@g.us description: >- 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 message: type: string description: >- 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. example: Customer asked for a callback tomorrow @user@example.com media: type: object properties: url: type: string format: uri description: >- Publicly accessible URL of the attachment. Provide either url or filedata — when both are given, url wins and filedata is ignored. example: https://example.com/files/image.png filedata: type: string description: >- File content as a base64 string or a data: URI (data:;base64,). The file is uploaded to Periskope storage. Requires mimetype. Alternative to url. example: iVBORw0KGgoAAAANSUhEUgAA... mimetype: type: string description: >- MIME type of the attachment. Required when uploading via filedata — it sets the content type of the stored file. example: image/png filename: type: string description: >- Filename for the attachment, shown in the chat (mainly relevant for document attachments). Defaults to the last url path segment, or a generated id. example: document.pdf type: type: string enum: - image - video - document - audio description: >- Kind of attachment — determines how it renders in the chat example: image required: - type description: >- Attachment for the note. Provide either a public url or base64/data-URI filedata (uploaded to Periskope storage). Required unless message is provided. reply_to: type: string description: >- message_id of an existing message or note in the chat that this note replies to. Stored on the note as quoted_message_id. example: true_00000000-0000-0000-0000-000000000000_api required: - chat_id responses: '200': description: The created note content: application/json: schema: type: object properties: success: type: boolean enum: - true description: Always true when the note was created message: type: string description: Human-readable confirmation message example: A Private note created successfully data: allOf: - $ref: '#/components/schemas/Note' - description: The created note examples: default: summary: Response body value: 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' '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.notes.createNote({ chat_id: '120363000000000000@g.us', }); console.log(response); } main(); - lang: bash label: cURL source: |- 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" }' components: schemas: Note: type: object properties: message_id: type: string example: true_00000000-0000-0000-0000-000000000000_api description: >- Unique id of the note, in the form true__. Use this value as the note_id path parameter when fetching a single note. org_id: type: string format: uuid description: Id of the organization the note belongs to example: 00000000-0000-0000-0000-000000000000 org_phone: type: string description: >- Org phone (WhatsApp account) the note was created under, as country code + number suffixed with @c.us example: 911111111111@c.us chat_id: type: string description: >- Chat the note is attached to — @c.us for 1-1 chats, @g.us for group chats example: 120363000000000000@g.us body: type: string description: Text content of the note. null for media-only notes. example: Customer asked for a callback tomorrow @user@example.com message_type: type: string description: >- Content type of the note: 'chat' for text-only notes, otherwise the attachment type ('image', 'video', 'document' or 'audio') example: chat media: type: object properties: path: type: string description: >- URL of the attachment — the url provided at creation, or the storage URL of the uploaded filedata example: https://example.com/files/image.png mimetype: type: string description: MIME type of the attachment example: image/png filename: type: string description: >- Filename of the attachment — the filename provided at creation, or one derived from the url example: image.png description: Attachment details. null for text-only notes. is_private_note: type: boolean enum: - true description: >- Always true — marks the record as a private note rather than a WhatsApp message from_me: type: boolean description: >- Always true for notes — notes are authored by the org, never by the contact example: true performed_by: type: string description: >- Who created the note: the member's email, or "api" when created via the API example: api quoted_message_id: type: string description: >- message_id of the message or note this note replies to (set via reply_to at creation). null when the note is not a reply. example: true_00000000-0000-0000-0000-000000000000_api mentioned_ids: type: array items: type: string description: >- Member emails @-mentioned in the note body. Each mention creates a task assigned to that member. example: - user@example.com timestamp: type: string description: When the note was created, as an ISO 8601 UTC timestamp example: '2026-01-15T09:30:00.000Z' updated_at: type: string description: When the note was last updated, as an ISO 8601 UTC timestamp example: '2026-01-15T09:30:00.000Z' description: >- A private note attached to a chat. Notes are internal to the workspace — they are never sent to WhatsApp and contacts cannot see them. Notes share the message record shape, so responses may include additional message fields (ack, sender_phone, sent_message_id, unique_id). securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Periskope API token, sent as `Authorization: Bearer `. 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.