Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.usetitan.app/llms.txt

Use this file to discover all available pages before exploring further.

The TypeScript SDK is the primary client library for Titan’s WhatsApp API. It ships with full type inference powered by the @titan-api/types package, built-in webhook signature verification, and automatic detection of API deprecation headers. You can use it in Node.js, Bun, edge runtimes, and any TypeScript or JavaScript project.

​
Installation

npm install @titan-api/sdk

​
Create a client

Import TitanClient and initialize it with your base URL and API key. 
import { TitanClient } from '@titan-api/sdk';

const client = new TitanClient({
  baseUrl: 'https://api.example.com',
  apiKey: 'titan_...',
});
Your API key starts with titan_. Keep it on the server — never expose it in browser code. Use client tokens for browser-side access.

​
Send a message

Call methods on the domain that corresponds to the resource you want to work with. Sending a message uses client.messages.send. 
const resp = await client.messages.send('default', {
  chatId: '[email protected]',
  type: 'text',
  text: 'Hello from TypeScript!',
});
The first argument is the session name. The second is the message payload, typed against the OpenAPI spec.

​
Service domains

The client exposes every Titan API domain as a property. All methods are async and return typed response objects.
DomainProperty
Sessionsclient.sessions
Messagesclient.messages
Contactsclient.contacts
Groupsclient.groups
Channelsclient.channels
Presenceclient.presence
Profileclient.profile
Labelsclient.labels
Chatsclient.chats
Webhooksclient.webhooks
Pairingclient.pairing
LIDsclient.lids
Mediaclient.media
Client tokensclient.clientTokens

​
Webhook verification

Use verifyWebhookSignature to validate the HMAC-SHA256 signature on incoming webhook deliveries. The function returns the parsed event object, fully typed based on the event name. 
import { verifyWebhookSignature, isEvent } from '@titan-api/sdk';

const event = await verifyWebhookSignature(rawBody, signatureHeader, secret);

if (isEvent(event, 'message.received')) {
  // event.payload is fully typed as a MessageReceivedPayload
}
Pass the raw request body as a string or Uint8Array, the value of the X-Webhook-Signature header, and your webhook secret. The function throws if the signature does not match.
Always verify webhook signatures before processing events. Requests with invalid signatures should be rejected with a 400 or 401 response.

​
Client tokens

To use a short-lived client token instead of a server API key, pass clientToken instead of apiKey: 
const client = new TitanClient({ baseUrl: '...', clientToken: 'titan_ct_...' });
The same TitanClient class handles both. See Client tokens for how to mint tokens and configure session rules.

​
Full client token flow

import { TitanClient } from '@titan-api/sdk';

// Server-side: configure rules and mint a token
const server = new TitanClient({
  baseUrl: 'https://api.example.com',
  apiKey: 'titan_...',
});

// Set rules once per session
await server.clientTokens.setRules('default', {
  recipientMode: 'conversation',
  allowedActions: 'send_message,send_reaction,send_typing',
  rateLimit: 5,
  maxDaily: 100,
  enabled: true,
});

// Mint a token per browser session
const { token, expiresAt } = await server.clientTokens.mint({
  session: 'default',
  ephemeralId: 'user-123-tab-1',
  ttl: 900,
});

// Browser-side: use the client token
const browser = new TitanClient({
  baseUrl: 'https://api.example.com',
  clientToken: token,
});

await browser.messages.send('default', {
  chatId: '[email protected]',
  type: 'text',
  text: 'Hello!',
});

​
Types

The TypeScript SDK gets its types from the @titan-api/types npm package, published separately from packages/shared/ in the Titan API monorepo. Types are kept in sync with the OpenAPI spec. You can import types directly if you need them without instantiating a client: 
import type { SendMessageRequest, SessionStatus } from '@titan-api/types';

​
Deprecation warnings

The SDK reads Deprecation, Sunset, and Titan-SDK-Deprecation response headers automatically. When any of these headers appear, the SDK emits a warning to the console once per client lifetime to avoid log spam.
  • Deprecation: true — the API version you are calling is deprecated; action required.
  • Sunset: <date> — the API version will be removed on the given date.
  • Titan-SDK-Deprecation — your SDK version is outdated; upgrade to avoid future breakage.
Run your test suite against the production API periodically and watch for deprecation warnings in CI output. This catches required upgrades before they become breaking changes.