Periskope API TypeScript Client

This is the official TypeScript API client for the Periskope REST API.

Installation

npm install @periskope/periskope-client

Usage

An example of initializing the API client and sending a message:

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

const client = new PeriskopeApi({
  authToken: ' <Your token> ',
  phone: ' <Your phone number> ',
});

const test = async () => {
  const { data, error } = await client.messages.sendMessage({
    chat_id: " < Receiver's chat ID > ",
    message: 'Hello from Periskope',
  });
  if (error) console.log(error);
};

test();

Namespaces mirror the API tags and methods mirror the operations of the API reference — the same names the Python SDK uses. Everything is generated from the Periskope OpenAPI specification, so your IDE autocompletes every namespace, method, argument and response shape:

await client.chats.listChats({ limit: 10 });
await client.notes.createNote({ chat_id: '...', body: 'hi' });
await client.tickets.createTicket({ chat_id: '...' });

The full request/response types are exported from the package root:

import type { paths, components, operations } from '@periskope/periskope-client';

type SendMessageBody =
  NonNullable<paths['/message/send']['post']['requestBody']>['content']['application/json'];

Migrating from 1.x to 2.0.0

2.0.0 generates the entire client from the Periskope OpenAPI spec, replacing the hand-maintained 1.x surface with typed methods, arguments and responses.

Breaking changes:

• Method names now follow the API operations (client.message.send() → client.messages.sendMessage()). Every endpoint behaves identically on the wire — only the names changed. The complete old-name → new-name table is in MIGRATION.md.
• Types follow the spec exactly. Code that passed fields the API does not define may get compile errors on upgrade.
• Types follow the spec exactly — but the result shape is unchanged from 1.x: every call resolves to { data, error, status, statusCode }, where data is the response body as-is, error is a PeriskopeClientError (or null), status is the numeric HTTP code and statusCode is its text. Errors are returned on error, not thrown — check if (error).

Additive changes:

• The client sends no response-format header — the API returns flat, unwrapped bodies, and each method returns the documented payload for that endpoint verbatim (list endpoints include their { from, to, count, … } wrapper).
• paths, components, operations and the socket event types are exported from the package root.

Documentation

For more detailed reference documentation, have a look at the API documentation with Node examples.

Feedback

Any feedback, such as bugs, questions, comments, etc. can be reported as Issues in this repository, and will be handled by us in Periskope.