### FAQ Instructions Examples (Text)

Source: https://docs.periskope.app/ai/agent/training

Illustrates different types of instructions that can be provided for an FAQ to control AI behavior, including basic, conditional, and multi-turn/escalation scenarios. These instructions guide the AI's response logic.

```text
Ask for the user's account email before providing specific account details.
```

```text
If the user mentions an error code, ask for a screenshot before troubleshooting.
```

```text
If the user asks about pricing, confirm their region first.
```

```text
If they are facing issues adding a new user and appear to have hit their user limit,
explain that they may need to upgrade their plan. Ask if that's the case, and if so,
direct them to Settings > Manage Plans or notify the sales team to step in.
```

--------------------------------

### Node.js Client Example

Source: https://docs.periskope.app/api-reference/webhooks/org.phone.disconnected

Example of how to use the Periskope client library in Node.js to listen for the `org.phone.updated` event.

```APIDOC
## Node.js Client Example

### Description
This code snippet demonstrates how to initialize the Periskope client and subscribe to the `org.phone.updated` event using the `@periskope/periskope-client` library.

### Language
Node.js

### Code

```javascript
import { PeriskopeApi } from '@periskope/periskope-client';

const client = new PeriskopeApi({
  authToken: 'YOUR_API_KEY',
  phone: 'YOUR_PHONE_NUMBER', // e.g., '919876543210'
});

client.on('org.phone.updated', (data) => {
  console.log('Organization phone details updated:', data);
});
```

### Parameters

- **authToken** (string) - Required - Your Periskope API authentication token.
- **phone** (string) - Required - The phone number associated with your Periskope account.
```

--------------------------------

### Node.js Client Example

Source: https://docs.periskope.app/api-reference/webhooks/ticket.deleted

Example of how to use the Periskope client library in Node.js to listen for the `ticket.deleted` webhook event.

```APIDOC
## Node.js Client Example

### Description
This code snippet demonstrates how to set up a listener for the `ticket.deleted` event using the Periskope client library in a Node.js environment. When a ticket is deleted, the provided callback function will be executed with the event data.

### Method
Client-side event listener

### Endpoint
N/A (This is for client-side integration)

### Parameters
- **authToken** (string) - Your Periskope API authentication token.
- **phone** (string) - Your Periskope phone number.

### Request Body
N/A

### Request Example
```javascript
import { PeriskopeApi } from '@periskope/periskope-client';

const client = new PeriskopeApi({
  authToken: 'YOUR_API_KEY',
  phone: 'YOUR_PHONE_NUMBER', // e.g., '919876543210'
});

client.on('ticket.deleted', (data) => {
  console.log(data);
});
```

### Response
N/A
```

--------------------------------

### Install Periskope Client SDK using npm or yarn

Source: https://docs.periskope.app/api-reference/sdk

Installs the official Periskope client package for Node.js environments using either npm or yarn package managers. This is a prerequisite for using the SDK in your project.

```bash
npm install @periskope/periskope-client
# or
yarn add @periskope/periskope-client
```

--------------------------------

### Get All Phones - cURL

Source: https://docs.periskope.app/api-reference/phones/get-all-phones

This example shows how to fetch all associated phone numbers using a cURL command. It requires an authorization token and the phone number to be included in the headers. This is useful for testing API endpoints directly.

```cURL
curl -X GET \
  https://api.periskope.app/v1/phones/all \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'x-phone: YOUR_PHONE_NUMBER'
```

--------------------------------

### TypeScript API Request Example

Source: https://docs.periskope.app/api-reference/chat/get-messages-in-chat

An example of how to make an API request using TypeScript, likely for interacting with the Periskope API. This snippet demonstrates setting up request parameters and handling responses, useful for developers integrating with the service.

```TypeScript
fetch(
  `/api/v1/organizations/${orgId}/messages?limit=${limit}&offset=${offset}`,
  {
    method: "GET",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${token}`
    }
  }
)
  .then(async (response) => {
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(errorData.message || `HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then((data) => {
    console.log(data);
  })
  .catch((error) => {
    console.error("Error fetching messages:", error);
  });
```

--------------------------------

### Install Periskope WhatsApp MCP Package (npm)

Source: https://docs.periskope.app/ai/mcp

Installs the Periskope WhatsApp MCP package globally using npm. This command requires Node.js and npm to be installed on your system.

```bash
npm install -g @periskope/whatsapp-mcp
```

--------------------------------

### Common Request Headers (Example)

Source: https://docs.periskope.app/api-reference/chat/update-chat

This snippet lists common HTTP headers that might be included in requests to the Periskope API. These headers provide information about the connection, content, and rate limiting. Examples include 'Content-Length', 'Date', and 'X-RateLimit-Limit'.

```http
example: '*'
Connection: 'keep-alive'
Content-Length: '2761'
Date: Sun, 26 Jan 2025 13:05:59 GMT
ETag: W/"ac9-EOpSAJXIhlLFANfA4wOXE5DtH3w"
Keep-Alive: timeout=5
X-Powered-By: Express
X-RateLimit-Limit: '10'
X-RateLimit-Remaining: '9'
X-RateLimit-Reset: '1737896761'
x-periskope-org-id: 2997dd64-89bf-48d3-9a22-b314fca017e5
x-periskope-phone-id: phone-bqzvyibhmwkaergr
x-periskope-trace-id: 49946e00-dbe6-11ef-98d2-afe02127d4e6
```

--------------------------------

### Fetch Chat Notes using cURL

Source: https://docs.periskope.app/api-reference/chat/get-private-notes-in-chat

This example shows how to fetch chat notes using a cURL command. It makes a GET request to the Periskope API endpoint for chat notes, requiring an authorization token and phone number. The request body can specify parameters like chat ID, start and end times, offset, and limit.

```cURL
curl -X GET \
  https://api.periskope.app/v1/chats/{chat_id}/notes \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'x-phone: YOUR_PHONE_NUMBER' \
  -d '{
    "chat_id": "919537851844@c.us",
    "start_time": "2025-08-10 10:00:00",
    "end_time": "2025-08-15 10:00:00",
    "offset": "0",
    "limit": "1000"
}'
```

--------------------------------

### GET /notes

Source: https://docs.periskope.app/api-reference/chat/get-private-notes-in-chat

Retrieves a paginated list of notes filtered by a start and end time.

```APIDOC
## GET /notes

### Description
Retrieves a list of notes for a specific organization, filtered by a provided time range. The response includes pagination details and an array of note objects.

### Method
GET

### Endpoint
/notes

### Parameters
#### Query Parameters
- **start_time** (string) - Required - The start_time of the notes returned (YYYY-MM-DDTHH:MM:SSZ)
- **end_time** (string) - Required - The end_time of the notes returned (YYYY-MM-DDTHH:MM:SSZ)

### Response
#### Success Response (200)
- **from** (number) - The starting index of the notes returned
- **to** (number) - The ending index of the notes returned
- **start_time** (string) - The start time filter used
- **end_time** (string) - The end time filter used
- **count** (number) - The total number of notes returned
- **notes** (array) - An array of note objects

#### Response Example
{
  "from": 1,
  "start_time": "2025-08-15T00:00:00Z",
  "end_time": "2025-08-15T23:59:59Z",
  "to": 2,
  "count": 2,
  "notes": [
    {
      "message_id": "true_2dc1aa2c-d711-4497-864d-92bb5709xxxx_api",
      "body": "testing with a new note payload",
      "message_type": "audio"
    }
  ]
}
```

--------------------------------

### Custom Tool Configuration Example

Source: https://docs.periskope.app/ai/agent/custom-tools

A template demonstrating the basic information required to register a custom tool, including the endpoint, HTTP method, and purpose description.

```text
Name: get_broadcast_details
Description: Fetch the status of any broadcast for a client. Useful when the
client is asking about updates on their bulk message, failure reasons of
broadcasts, and delivery issues with broadcasts.
HTTP Method: POST
Endpoint: https://api.yourcompany.com/tools/get_broadcast_details
```

--------------------------------

### Retrieve Message Reactions

Source: https://docs.periskope.app/api-reference/reactions/get-reactions

Fetches a list of reactions from the Periskope API. The TypeScript example uses the official SDK, while the cURL example demonstrates a direct HTTP GET request with authentication headers and query parameters.

```TypeScript
import { PeriskopeApi } from '@periskope/periskope-client';

const client = new PeriskopeApi({
  authToken: 'YOUR_API_KEY',
  phone: 'YOUR_PHONE_NUMBER', // e.g., '919876543210'
});

async function fetchReactions() {
  const response = await client.reaction.getReactions();

  console.log(response);
}

fetchReactions();
```

```cURL
curl -X GET \
  https://api.periskope.app/v1/reaction \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'x-phone: YOUR_PHONE_NUMBER' \
  -d '{
    "chat_id": "919537851844@c.us",
    "message_id": "true_919537851844@c.us_3EB0ABB7C973860FC19EBE05FD934141CCEC2D8B",
    "start_time": "2025-08-10 10:00:00",
    "end_time": "2025-08-15 10:00:00",
    "offset": "0",
    "limit": "1000"
}'
```

--------------------------------

### Get Chats using cURL

Source: https://docs.periskope.app/api-reference/chat/list-all-chats

This example shows how to make a GET request to the Periskope API to retrieve chats using cURL. It requires an authorization token and the user's phone number, passed as headers. The request specifies the content type as JSON.

```cURL
curl -X GET \
  https://api.periskope.app/v1/chats \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'x-phone: YOUR_PHONE_NUMBER'
```

--------------------------------

### POST /knowledge-base/faq/create

Source: https://docs.periskope.app/api-reference/knowledge-base/create-faq

Creates a new FAQ entry in the knowledge base.

```APIDOC
## POST /knowledge-base/faq/create

### Description
Create a new FAQ entry in the knowledge base.

### Method
POST

### Endpoint
/knowledge-base/faq/create

### Parameters
#### Request Body
- **question** (string) - Required - The FAQ question
- **answer** (string) - Required - The FAQ answer

### Request Example
```json
{
  "question": "How do I connect WhatsApp?",
  "answer": "You can connect WhatsApp by scanning the QR code in Settings."
}
```

### Response
#### Success Response (201)
- **context_id** (string) - The unique identifier for this FAQ
- **type** (string) - Type of entry (faq)
- **question** (string) - The FAQ question
- **answer** (string) - The FAQ answer
- **embedding** (array) - The vector embedding of the FAQ (Dimension: 768)
- **attachments** (array) - Array of attachment URLs
- **created_at** (string) - Creation timestamp

#### Response Example
```json
{
  "context_id": "ai-context-aaauajhjdgjnomr",
  "type": "faq",
  "question": "How do I connect WhatsApp?",
  "answer": "You can connect WhatsApp by scanning the QR code in Settings.",
  "attachments": [
    "https://example.com/image.png"
  ],
  "created_at": "2025-01-20T10:00:00Z",
  "updated_at": "2025-01-20T10:00:00Z"
}
```
```

--------------------------------

### Retrieve Knowledge Base Items (OpenAPI)

Source: https://docs.periskope.app/api-reference/knowledge-base/get-all-knowledge-base

This OpenAPI specification defines the GET /knowledge-base endpoint for retrieving paginated lists of knowledge base items (FAQs and Documents). It includes parameters for offset, limit, and type filtering, along with example responses.

```yaml
openapi: 3.0.3
info:
  title: API - Local
  description: >-
    #### Welcome to the official Postman collection of Periskope API


    Periskope APIs enable you automate actions on your WhatsApp phone, and the
    Periskope platform


    - Read more about the APIs & webhooks here -
    [https://docs.periskope.app/api-reference/introduction](https://docs.periskope.app/api-reference/introduction)
        
    - We encourage responsible usage of the APIs. Follow these best practices
    and recommendations for safe actions on WhatsApp -
    [https://docs.periskope.app/get-started/best-practices](https://docs.periskope.app/get-started/best-practices)
        

    #### Getting Started


    ##### Pre-requisites:

    1. **Sign up for a free account on Periskope:** To use the Periskope API,
    you need to have an active Periskope account. If you don’t have one, you can
    sign up for a 7-day free trial [here](https://console.periskope.app).
        
    2. **Scan the QR code from WhatsApp to connect your phone:** A connected
    phone is required to use the APIs
        
    3. **Go to** [Settings &gt;
    API](https://console.periskope.app/settings/api), and generate an API key
    for your organization - The API key is used to authenticate every request.
    Please keep this secure


    ##### Using Postman:

    1. **Fork the collection so you can edit values and test the APIs in your
    own postman environment:** To fork the collection, click on the three dots
    next to v1. Then click on create a fork (_shortcut: Ctrl + Alt + F).
        
    2. **Update the value of the variables in the collection:**  
        \- Update the API key with the key generated in Step 3  
        \- Update the phone number with your connected number. This number will be added to the `x-phone` header across requests
        
        It must be in the format of country code+number, with no special characters or spaces _e.g. +91 98745 32456 becomes 919874532456_ 

    For any help or feedback, please contact us at
    [support@periskope.app](https://mailto:support@periskope.app), or ping us on
    [WhatsApp](https://what.sapp.link/periskope)
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.periskope.app/v1
security:
  - bearerAuth: []
tags:
  - name: contacts
  - name: tickets
  - name: phones
  - name: message
  - name: queue
  - name: chats
  - name: group
  - name: members
  - name: webhooks
paths:
  /knowledge-base:
    get:
      tags:
        - knowledge-base
      summary: Get All Knowledge Base Items
      description: >
        This endpoint retrieves a paginated list of all knowledge base items
        (FAQs and Documents)
      operationId: getAllKnowledgeBase
      parameters:
        - name: offset
          in: query
          schema:
            type: number
            example: '0'
            description: |-
              - The offset value for paginating the results
              - Default 0
        - name: limit
          in: query
          schema:
            type: number
            example: '10'
            description: |-
              - The maximum number of items to retrieve
              - Default 100
        - name: type
          in: query
          schema:
            type: string
            example: faq
            description: |-
              - Optional filter by type: 'faq' or 'document'
              - If not provided, returns all types
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: An array of knowledge base items (FAQs and Documents)
                  total:
                    type: number
                    description: Total count of items
                  offset:
                    type: number
                    description: Current offset
                  limit:
                    type: number
                    description: Current limit
              examples:
                200 OK:
                  value:
                    data:
                      - context_id: ai-context-aaauajhjdgjnomr
                        type: faq
                        question: How do I connect WhatsApp?
                        answer: >-
                          You can connect WhatsApp by scanning the QR code in
                          Settings.
                        attachments: []
                        embedding:
                          - -0.020637017
                          - -0.0148050785
                          - 0.02985098
                          - 0.023778915
                          - ...
                        created_at: '2025-01-20T10:00:00Z'
                        updated_at: '2025-01-20T10:00:00Z'
                      - document_id: doc_xyz789

```

--------------------------------

### POST /v1/knowledge-base/faq/create

Source: https://docs.periskope.app/api-reference/knowledge-base/create-faq

Creates a new FAQ entry in the knowledge base. Requires authentication and a valid phone number header.

```APIDOC
## POST /v1/knowledge-base/faq/create

### Description
Creates a new FAQ entry for the knowledge base associated with the authenticated account.

### Method
POST

### Endpoint
https://api.periskope.app/v1/knowledge-base/faq/create

### Parameters
#### Request Body
- **question** (string) - Required - The FAQ question text.
- **answer** (string) - Required - The FAQ answer text.
- **attachments** (array of strings) - Optional - A list of URLs pointing to media attachments.

### Request Example
{
  "question": "How do I connect WhatsApp?",
  "answer": "You can connect WhatsApp by scanning the QR code in Settings.",
  "attachments": ["https://example.com/image.png"]
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created FAQ.
- **status** (string) - The status of the operation.

#### Response Example
{
  "id": "faq_12345",
  "status": "success"
}
```

--------------------------------

### Implementing Event Handlers

Source: https://docs.periskope.app/api-reference/sdk

How to use the client.on method to listen for specific events and trigger automated actions.

```APIDOC
## Implementing Event Handlers

### Description
Use the `client.on` method to register event listeners. This allows you to build automations based on real-time data from the Periskope platform.

### Example
```javascript
// Listen for new messages
client.on('message.created', async (messageData) => {
  if (messageData.body && messageData.body.toLowerCase().includes('help')) {
    await client.message.send({
      chat_id: messageData.chat.id,
      message: "Here's how I can help you...",
    });
  }
});

// Listen for ticket updates
client.on('ticket.updated', (ticketData) => {
  if (ticketData.ticket.status === 'closed') {
    console.log(`Ticket #${ticketData.id} has been resolved`);
  }
});
```
```

--------------------------------

### Get Chat by ID using Periskope API (TypeScript & cURL)

Source: https://docs.periskope.app/api-reference/chat/get-chat-by-id

This snippet demonstrates how to retrieve chat information by its ID using the Periskope API. It includes examples for both Node.js with the Periskope client library and a direct cURL request. Ensure you replace placeholders like YOUR_API_KEY, YOUR_PHONE_NUMBER, and < CHAT_ID > with your actual credentials and chat identifier.

```TypeScript
import { PeriskopeApi } from '@periskope/periskope-client';

const client = new PeriskopeApi({
  authToken: 'YOUR_API_KEY',
  phone: 'YOUR_PHONE_NUMBER', // e.g., '919876543210'
});

async function getChat() {
  const response = await client.chat.getChatById({
    chat_id: '< CHAT_ID >',
  });

  console.log(response);
}

getChat();
```

```cURL
curl -X GET \
  https://api.periskope.app/v1/chat/{chat_id} \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'x-phone: YOUR_PHONE_NUMBER'
```

--------------------------------

### MCP Configuration for Windows

Source: https://docs.periskope.app/ai/mcp

Configuration JSON for setting up the Periskope WhatsApp MCP on Windows. This file should be placed at ~/.cursor/mcp.json and includes environment variables for API key and phone ID.

```json
{
  "mcpServers": {
    "periskope-mcp": {
      "command": "cmd",
      "args": ["/k", "npx", "-y", "@periskope/whatsapp-mcp"],
      "env": {
        "PERISKOPE_API_KEY": "your_periskope_api_key_here",
        "PERISKOPE_PHONE_ID": "your_periskope_phone_id_here"
      }
    }
  }
}
```

--------------------------------

### Create Knowledge Base Document with cURL

Source: https://docs.periskope.app/api-reference/knowledge-base/create-document

This example shows how to create a knowledge base document using a cURL command. It sends a POST request to the Periskope API endpoint with the necessary authentication headers (Bearer token, phone number) and a JSON payload containing the document URL and filename.

```curl
curl -X POST \
  https://api.periskope.app/v1/knowledge-base/document/create \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'x-phone: YOUR_PHONE_NUMBER' \
  -d '{
    "document": {
      "url": "https://example.com/document.pdf",
      "filename": "document.pdf"
    }
  }'
```

--------------------------------

### Initialize and Send Message with Periskope SDK (TypeScript)

Source: https://docs.periskope.app/api-reference/sdk

Demonstrates how to initialize the Periskope API client with authentication tokens and phone numbers, and then send a message to a recipient. It includes basic error handling for the send operation.

```javascript
import { PeriskopeApi } from "@periskope/periskope-client";

const client = new PeriskopeApi({
  authToken: 'YOUR_API_KEY',
  phone: 'YOUR_PHONE_NUMBER', // e.g., '919876543210'
});

async function sendMessage() {
  try {
    const response = await client.message.send({
        chat_id: 'RECEPIENT_PHONE_NUMBER',
        message:"Hello from Periskope"
    });

    console.log('Message sent:', response);
  } catch (error) {
    console.error('Failed to send message:', error);
  }
}

sendMessage();
```

--------------------------------

### Get All Phones - OpenAPI Specification

Source: https://docs.periskope.app/api-reference/phones/get-all-phones

This OpenAPI 3.0.3 specification defines the GET /phones/all endpoint, which retrieves a list of all phones associated with a Periskope account. It includes details on request parameters, responses, and authentication.

```yaml
openapi: 3.0.3
info:
  title: API - Local
  description: >-
    #### Welcome to the official Postman collection of Periskope API


    Periskope APIs enable you automate actions on your WhatsApp phone, and the
    Periskope platform


    - Read more about the APIs & webhooks here -
    [https://docs.periskope.app/api-reference/introduction](https://docs.periskope.app/api-reference/introduction)
        
    - We encourage responsible usage of the APIs. Follow these best practices
    and recommendations for safe actions on WhatsApp -
    [https://docs.periskope.app/get-started/best-practices](https://docs.periskope.app/get-started/best-practices)
        

    #### Getting Started


    ##### Pre-requisites:

    1. **Sign up for a free account on Periskope:** To use the Periskope API,
    you need to have an active Periskope account. If you don’t have one, you can
    sign up for a 7-day free trial [here](https://console.periskope.app).
        
    2. **Scan the QR code from WhatsApp to connect your phone:** A connected
    phone is required to use the APIs
        
    3. **Go to** [Settings &gt;
    API](https://console.periskope.app/settings/api), and generate an API key
    for your organization - The API key is used to authenticate every request.
    Please keep this secure
        

    ##### Using Postman:

    1. **Fork the collection so you can edit values and test the APIs in your
    own postman environment:** To fork the collection, click on the three dots
    next to v1. Then click on create a fork (_shortcut: Ctrl + Alt + F)._
        
    2. **Update the value of the variables in the collection:**  
        \- Update the API key with the key generated in Step 3  
        \- Update the phone number with your connected number. This number will be added to the `x-phone` header across requests
        
        It must be in the format of country code+number, with no special characters or spaces _e.g. +91 98745 32456 becomes 919874532456_ 

    For any help or feedback, please contact us at
    [support@periskope.app](https://mailto:support@periskope.app), or ping us on
    [WhatsApp](https://what.sapp.link/periskope)
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.periskope.app/v1
security:
  - bearerAuth: []
tags:
  - name: contacts
  - name: tickets
  - name: phones
  - name: message
  - name: queue
  - name: chats
  - name: group
  - name: members
  - name: webhooks
paths:
  /phones/all:
    get:
      tags:
        - phones
      summary: Get All Phones
      description: >-
        This endpoint retrieves a list of all phones associated with this
        account


        #### Response


        The response is a JSON array of phone objects. Refer to [the phone
        object here](/api-reference/objects/the-phone-object)
      operationId: getAllPhones
      responses:
        '200':
          description: 200 OK
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
                example: '*'
            Connection:
              schema:
                type: string
                example: keep-alive
            Content-Length:
              schema:
                type: string
                example: '1113'
            Date:
              schema:
                type: string
                example: Mon, 20 Jan 2025 09:35:25 GMT
            ETag:
              schema:
                type: string
                example: W/"459-nBl/uUG1GNr+RwzyDCnB33KF7AM"
            Keep-Alive:
              schema:
                type: string
                example: timeout=5
            X-Powered-By:
              schema:
                type: string
                example: Express
            X-RateLimit-Limit:
              schema:
                type: string
                example: '10'
            X-RateLimit-Remaining:
              schema:
                type: string
                example: '9'
            X-RateLimit-Reset:
              schema:
                type: string
                example: '1737365727'
            x-periskope-org-id:
              schema:
                type: string
                example: 2997dd64-89bf-48d3-9a22-b314fca017e5
            x-periskope-phone-id:
              schema:
                type: string
                example: phone-bqzvyibhmwkaergr
            x-periskope-trace-id:
              schema:
                type: string
                example: e0871620-d711-11ef-b07a-ad8b5d178f98
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    created_at:
                      type: string
                      example: '2024-12-31T17:51:15.977006+00:00'
                    first_connected_at:
                      type: string

```

--------------------------------

### POST /v1/knowledge-base/document/create

Source: https://docs.periskope.app/api-reference/knowledge-base/create-document

Creates a new document in the knowledge base by providing a source URL and a filename.

```APIDOC
## POST /v1/knowledge-base/document/create

### Description
Creates a new document entry in the knowledge base. The document is fetched from the provided URL.

### Method
POST

### Endpoint
https://api.periskope.app/v1/knowledge-base/document/create

### Parameters
#### Request Body
- **document** (object) - Required - The document object containing source details.
  - **url** (string) - Required - The publicly accessible URL of the document.
  - **filename** (string) - Required - The name to assign to the document.

### Request Example
{
  "document": {
    "url": "https://example.com/document.pdf",
    "filename": "document.pdf"
  }
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created document.
- **status** (string) - The processing status of the document.

#### Response Example
{
  "id": "doc_12345",
  "status": "processing"
}
```

--------------------------------

### Create Webhook Subscription (cURL)

Source: https://docs.periskope.app/api-reference/webhooks/create-webhook

This example shows how to create a webhook subscription using a cURL command. It sends a POST request to the Periskope API endpoint with the webhook URL and integration name in the JSON payload. Authentication is handled via the Authorization header.

```cURL
curl -X POST \
  https://api.periskope.app/v1/webhooks \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "hookUrl": "https://example.com/webhook",
    "integrationName": "message.created"
  }'
```

--------------------------------

### Chat Notification Object Example (JSON)

Source: https://docs.periskope.app/api-reference/chat/list-all-notifications

This snippet shows an example of a chat notification object, detailing its structure and common fields. It includes information about message counts, sender, recipient, timestamps, and notification types.

```json
{
  "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"
    }
  ]
}
```

--------------------------------

### Retrieve FAQ Entry by Context ID using TypeScript

Source: https://docs.periskope.app/api-reference/knowledge-base/get-faq-by-id

This snippet demonstrates how to initialize the Periskope client to fetch a specific FAQ entry. It requires the @periskope/periskope-client package and an authenticated API key.

```TypeScript
import { PeriskopeApi } from '@periskope/periskope-client';
```

--------------------------------

### Chat Notification Object Example (JSON)

Source: https://docs.periskope.app/api-reference/objects/the-chat-notification-object

An example of the Chat Notification object structure in JSON format. This object represents a chat update notification in WhatsApp, including details about the chat, author, notification type, and timestamps.

```json
{
    "org_id": "2997dd64-89bf-48d3-9a22-b314fca017e5",
    "notification_id": "true_120363371308389685@g.us_fa3c48a78cc64e139e5737f7057235ea_918527184400@c.us_remove",
    "chat_id": "120363371308389685@g.us",
    "author": "918527184400@c.us",
    "body": null,
    "id": {
        "id": "fa3c48a78cc64e139e5737f7057235ea",
        "fromMe": true,
        "remote": "120363371308389685@g.us",
        "serialized": "true_120363371308389685@g.us_fa3c48a78cc64e139e5737f7057235ea_918527184400@c.us_remove"
    },
    "recipientids": [
        "919537851844@c.us"
    ],
    "type": "remove",
    "timestamp": "2025-01-11T11:52:27.231+00:00",
    "org_phone": "918527184400@c.us",
    "unique_id": "fa3c48a78cc64e139e5737f7057235ea",
    "metadata": null
}
```

--------------------------------

### Create a new phone instance

Source: https://docs.periskope.app/api-reference/phones/create-phone

Initializes a new phone connection in the Periskope system. This requires an authentication token and the target phone number to establish the session.

```typescript
import { PeriskopeApi } from '@periskope/periskope-client';

const client = new PeriskopeApi({
  authToken: 'YOUR_API_KEY',
  phone: 'YOUR_PHONE_NUMBER',
});

async function createPhone() {
  const response = await client.phone.create();
  console.log(response);
}

createPhone();
```

```bash
curl -X POST \
  https://api.periskope.app/v1/phones/create \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json'
```

--------------------------------

### Create Private Note with Media

Source: https://docs.periskope.app/api-reference/notes/create-private-notes

Demonstrates how to create a private note containing text and an audio attachment. The implementation requires a valid chat ID and base64-encoded media data.

```javascript
async function sendPrivateNote() {
  const response = await client.note.create({
    chat_id: '91882424xxxx@c.us',
    message: 'testing with new note payload',
    reply_to: '52643136-1573-4011-ad22-b95ca6ea8e0c',
    media: {
      type: 'audio',
      mimetype: 'audio/wav',
      filename: 'beep.wav',
      filedata: 'data:audio/wav;base64,UklGRkKAAABXQVZFZm10IBAAAAABAAEAQB8A...'
    }
  });
  console.log(response);
}
sendPrivateNote();
```

```curl
curl -X POST \
  https://api.periskope.app/v1/note/create \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'x-phone: YOUR_PHONE_NUMBER' \
  -d '{
    "chat_id": "91882424xxxx@c.us",
    "message": "testing with new note payload",
    "reply_to": "52643136-1573-4011-ad22-b95ca6ea8e0c",
    "media": {
      "type": "audio",
      "mimetype": "audio/wav",
      "filename": "beep.wav",
      "filedata": "data:audio/wav;base64,UklGRkKAAABXQVZFZm10IBAAAAABAAEAQB8A..."
    }
  }'
```

--------------------------------

### Retrieve Notes via Periskope API

Source: https://docs.periskope.app/api-reference/notes/list-all-private-notes

Demonstrates how to fetch notes from the Periskope API. The TypeScript example uses the official client library, while the cURL example shows the raw HTTP request structure including necessary headers and authentication.

```TypeScript
import { PeriskopeApi } from '@periskope/periskope-client';

const client = new PeriskopeApi({
  authToken: 'YOUR_API_KEY',
  phone: 'YOUR_PHONE_NUMBER',
});

async function fetchNotes() {
  const response = await client.reaction.getNotes();

  console.log(response);
}

fetchNotes();
```

```cURL
curl -X GET \
  https://api.periskope.app/v1/note \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'x-phone: YOUR_PHONE_NUMBER' \
  -d '{
    "chat_id": "919537851844@c.us",
    "start_time": "2025-08-10 10:00:00",
    "end_time": "2025-08-15 10:00:00",
    "offset": "0",
    "limit": "1000"
}'
```

--------------------------------

### POST /knowledge-base/document/create

Source: https://docs.periskope.app/api-reference/knowledge-base/create-document

Creates a new document entry in the knowledge base by processing a provided file URL or base64 data. The system automatically splits the document into chunks for retrieval.

```APIDOC
## POST /knowledge-base/document/create

### Description
Process and create document entries in the knowledge base. The document will be split into chunks for efficient retrieval.

### Method
POST

### Endpoint
/knowledge-base/document/create

### Parameters
#### Request Body
- **document** (object) - Required - The document object containing file details.
  - **url** (string) - Optional - The URL of the document to process.
  - **base64** (string) - Optional - The raw bytes of the file, represented in base64.
  - **filename** (string) - Optional - The filename of the document.

### Request Example
{
  "document": {
    "url": "https://example.com/document.pdf",
    "filename": "document.pdf"
  }
}

### Response
#### Success Response (201)
- **file_name** (string) - The filename of the document
- **document_id** (string) - The ID of the document
- **file_path** (string) - The path of the document
- **chunks_count** (number) - The number of chunks created for the document

#### Response Example
{
  "file_name": "Frank.pdf",
  "document_id": "88a010a1-c6ac-4f8f-be15-850bee5372b7",
  "file_path": "org-assets/2997dd64-89bf-48d3-9a22-b314fca017e5/ai_assets/documents/88a010a1-c6ac-4f8f-be15-850bee5372b7/Frank.pdf",
  "chunks_count": 1
}
```