Oxenty SDK

Official TypeScript/JavaScript SDK for Oxenty WhatsApp API.

Overview

The Oxenty SDK provides a complete interface for integrating WhatsApp messaging capabilities into your applications. It supports session management, message sending (16+ types), contact validation, group operations, and real-time event handling via WebSocket.

Key Features

• Dual Authentication — API Key for server-side or JWT for client-side applications
• Complete WhatsApp API — Sessions, Messages, Contacts, and Groups
• Real-time Events — WebSocket support via Socket.IO for instant updates
• Cross-platform — Compatible with Node.js 18+ and modern browsers
• Optimized Bundles — ESM and CJS builds with tree-shaking support
• Type Safety — Written in TypeScript with full type definitions

Installation

npm install oxenty-sdk
# or
yarn add oxenty-sdk
# or
pnpm add oxenty-sdk

Quick Start

Client Initialization

import { OxentyClient } from 'oxenty-sdk'

// Server-side with API Key (recommended)
const client = new OxentyClient({
  baseUrl: 'https://api.oxenty.api.br',
  apiKey: 'whl_your_api_key_here'
})

// Client-side with JWT tokens
const client = new OxentyClient({
  baseUrl: 'https://api.oxenty.api.br',
  tokens: {
    accessToken: 'eyJ...',
    refreshToken: 'eyJ...'
  }
})

API Reference

Session Management

// List all sessions
const sessions = await client.sessions.list()

// Create a new session
const session = await client.sessions.create({
  name: 'My Session',
  webhookUrl: 'https://myapp.com/webhook'
})

// Retrieve QR code for authentication
const qr = await client.sessions.getQRCode(session.id)

// Connect session
await client.sessions.connect(session.id)

// Disconnect session
await client.sessions.disconnect(session.id)

// Delete session
await client.sessions.delete(session.id)

Message Types

The SDK supports 16+ message types. Below are the most common examples:

// Text
await client.messages.sendText({
  sessionId: 'session-uuid',
  to: '5511999999999',
  text: 'Hello from Oxenty SDK'
})

// Image
await client.messages.sendImage({
  sessionId: 'session-uuid',
  to: '5511999999999',
  url: 'https://example.com/image.jpg',
  caption: 'Image description'
})

// Document
await client.messages.sendDocument({
  sessionId: 'session-uuid',
  to: '5511999999999',
  url: 'https://example.com/document.pdf',
  filename: 'report.pdf'
})

// Location
await client.messages.sendLocation({
  sessionId: 'session-uuid',
  to: '5511999999999',
  latitude: -23.5505,
  longitude: -46.6333,
  name: 'Location Name',
  address: 'Full address'
})

// Interactive buttons
await client.messages.sendButtons({
  sessionId: 'session-uuid',
  to: '5511999999999',
  text: 'Select an option:',
  buttons: [
    { id: 'btn_1', text: 'Option 1' },
    { id: 'btn_2', text: 'Option 2' }
  ],
  footer: 'Footer text'
})

// Reaction
await client.messages.sendReaction({
  sessionId: 'session-uuid',
  to: '5511999999999',
  messageId: 'BAE5...',
  emoji: '👍'
})

// PIX payment (Brazil)
await client.messages.sendPix({
  sessionId: 'session-uuid',
  to: '5511999999999',
  keyType: 'cpf',
  key: '12345678900',
  amount: 99.90,
  description: 'Order #123'
})

Contact Operations

// Validate WhatsApp numbers
const result = await client.contacts.check({
  sessionId: 'session-uuid',
  numbers: ['5511999999999', '5511888888888']
})
// Returns: { results: [{ number, exists, jid }] }

// Get profile picture URL
const picture = await client.contacts.getProfilePicture({
  sessionId: 'session-uuid',
  jid: '[email protected]'
})

// Get contact status/about
const status = await client.contacts.getStatus({
  sessionId: 'session-uuid',
  jid: '[email protected]'
})

// Send presence indicators
await client.contacts.startTyping('session-uuid', '[email protected]')
await client.contacts.stopTyping('session-uuid', '[email protected]')
await client.contacts.startRecording('session-uuid', '[email protected]')

Group Management

// List all groups
const groups = await client.groups.list('session-uuid')

// Create a group
const group = await client.groups.create({
  sessionId: 'session-uuid',
  subject: 'Group Name',
  participants: ['5511999999999', '5511888888888']
})

// Manage participants
await client.groups.addParticipants({
  sessionId: 'session-uuid',
  groupJid: group.groupJid,
  participants: ['5511777777777']
})

await client.groups.removeParticipants({
  sessionId: 'session-uuid',
  groupJid: group.groupJid,
  participants: ['5511777777777']
})

// Update group settings
await client.groups.setAnnouncementOnly('session-uuid', group.groupJid)
await client.groups.setAllCanSend('session-uuid', group.groupJid)

// Get invite link
const invite = await client.groups.getInviteCode('session-uuid', group.groupJid)

Real-time Events (WebSocket)

// Establish WebSocket connection
await client.connectRealtime()

// Subscribe to session events
client.realtime.joinSession('session-uuid')

// Event listeners
client.realtime.on('message:received', (message) => {
  console.log('New message from:', message.from)
})

client.realtime.on('session:qrcode', (data) => {
  // Handle QR code update
})

client.realtime.on('session:connected', (data) => {
  // Session authenticated successfully
})

client.realtime.on('session:disconnected', (data) => {
  // Session disconnected
})

client.realtime.on('message:status', (status) => {
  // Message delivery status update (sent, delivered, read)
})

// Wait for a specific event with timeout
const qrData = await client.realtime.waitForEvent('session:qrcode', 30000)

// Close connection
client.disconnectRealtime()

Error Handling

The SDK provides typed error classes for precise error handling:

import { 
  OxentyError, 
  OxentyAuthError,
  OxentyRateLimitError,
  OxentyPlanLimitError,
  OxentyNotFoundError 
} from 'oxenty-sdk'

try {
  await client.messages.sendText({ ... })
} catch (error) {
  if (error instanceof OxentyAuthError) {
    // HTTP 401 - Invalid or expired credentials
  } else if (error instanceof OxentyRateLimitError) {
    // HTTP 429 - Rate limit exceeded
    console.log(`Retry after ${error.retryAfter} seconds`)
  } else if (error instanceof OxentyPlanLimitError) {
    // HTTP 403 - Plan quota exceeded
    console.log(`${error.resource}: ${error.current}/${error.limit}`)
  } else if (error instanceof OxentyNotFoundError) {
    // HTTP 404 - Resource not found
  } else if (error instanceof OxentyError) {
    // Other API errors
    console.log(`Code: ${error.code}, Message: ${error.message}`)
  }
}

Configuration

Client Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | baseUrl | string | — | API base URL (required) | | apiKey | string | — | API Key for authentication | | tokens | object | — | JWT tokens (accessToken, refreshToken) | | timeout | number | 30000 | Request timeout in milliseconds | | maxRetries | number | 3 | Maximum retry attempts for failed requests | | debug | boolean | false | Enable debug logging | | refreshEndpoint | string | /auth/refresh | JWT refresh endpoint path |

Token Management (JWT)

// Automatic token refresh callback
client.onTokensRefreshed((tokens) => {
  localStorage.setItem('accessToken', tokens.accessToken)
  localStorage.setItem('refreshToken', tokens.refreshToken)
})

// Manual token operations
client.setTokens({ accessToken: '...', refreshToken: '...' })
const tokens = client.getTokens()
client.clearTokens()

Requirements

| Environment | Minimum Version | |-------------|-----------------| | Node.js | 18.0.0+ | | TypeScript | 5.0+ (optional) |

Browser Compatibility

The SDK requires browsers with support for:

• Fetch API
• AbortController
• ES2022 features

License

This project is licensed under the MIT License. See the LICENSE file for details.

Resources

• API Documentation
• GitHub Repository
• NPM Package
• Issue Tracker