The Periskope Typescript client exposes our RESTful APIs with complete type-safety, semantically named functions, and straightforward JSON responses. Whether you’re building bots, automating customer support, sending messages, managing tickets, or creating groups, Periskope Client makes it quick and efficient to integrate Periskope into your workflow. 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

​
Prerequisites

  1. Sign up for a free account on Periskope: To use the Periskope Client, 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.
  2. Scan the QR code from WhatsApp to connect your phone: A connected phone is required to use the package
  3. Generate an API Key: An API key is required for authentication and can be generated from your Periskope settings here.

​
Setup Guide

1

Install Node.js

If you don’t already have Node.js installed, download it from the official Node.js website.
We recommend installing the LTS version for better stability.You can verify your installation by running:
node -v
npm -v
2

Install the Periskope Client SDK

Use your preferred package manager to install the official Periskope client:
npm install @periskope/periskope-client
# or
yarn add @periskope/periskope-client
3

Use the SDK in your project

Here’s a basic example of how to use the Periskope client in your code:
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();
4

You're ready to go ✅

That’s it! You’ve set up Node.js, installed the Periskope client SDK, and made your first API call using JavaScript or Typescript.
You can now explore more features like creating groups, raising tickets, and listening to webhooks.

​
Webhooks

Periskope emits various webhook events that you can listen to in real-time using the SDK. These events allow your application to respond automatically to activities like incoming messages, status changes, and other WhatsApp interactions. For a comprehensive overview of all webhook events and their payloads, check out our Webhooks docs. The SDK provides an event emitter interface that makes it easy to subscribe to these events without setting up a separate webhook server.

​
Usage

Here’s a basic example of how to subscribe to the message.created event using the Typescript package: 
import { PeriskopeApi } from '@periskope/periskope-client';

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

client.connect(); // First connect the socket

client.on('message.created', (data) => {
  console.log(data);
  // Handle new messages here - respond, process commands, update your database, etc.
});

​
Available Webhook Events

The SDK supports listening to various event types including:
  • chat.created - Triggered when a new chat is created 🔗
  • chat.notification.created - Triggered when a new chat notification is created 🔗
  • message.created - Triggered when a new message is received or sent 🔗
  • message.updated - Triggered when message is edited 🔗
  • message.deleted - Triggered when message is deleted 🔗
  • message.ack.updated - Triggered when a message is acknowledged 🔗
  • message.ticket.attached - Triggered when a message is attached to a ticket 🔗
  • message.flagged - Triggered when a message is flagged 🔗
  • message.unflagged - Triggered when a message is unflagged 🔗
  • reaction.created - Triggered when a reaction is created 🔗
  • reaction.updated - Triggered when a reaction is updated 🔗
  • ticket.created - Triggered when a new ticket is created 🔗
  • ticket.updated - Triggered when a ticket details are updated 🔗
  • ticket.deleted - Triggered when a ticket is deleted 🔗
  • org.phone.updated - Triggered when a phone number, phone name or phone image changes 🔗
  • org.phone.connected - Triggered when a phone changes to a connected state 🔗
  • org.phone.disconnected - Triggered when a phone changes to a disconnected state 🔗
  • org.phone.qr - Triggered when a phone’s QR code changes 🔗

​
Implementing Event Handlers

You can implement multiple event handlers to build comprehensive automations: 
// Listen for new messages
client.on('message.created', async (messageData) => {
  if (messageData.body && messageData.body.toLowerCase().includes('help')) {
    // Respond to help requests automatically
    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') {
    // Perform actions when tickets are closed
    console.log(`Ticket #${ticketData.id} has been resolved`);
  }
});