Skip to main content

​
Configuration

The Advanced iMessage Kit SDK is configured when you initialize it using the SDK() function. All configuration options are passed through the ClientConfig interface.

​
Basic Configuration

Minimal configuration to connect to a local server: 
import { SDK } from '@photon-ai/advanced-imessage-kit';

const sdk = SDK({
  serverUrl: 'http://localhost:1234',
});

​
ClientConfig Interface

All configuration options available for the SDK client:
​
serverUrl
string
default:"http://localhost:1234"
The URL of the Advanced iMessage Kit server.This is the base URL where your server is running. For local development, this is typically http://localhost:1234. For remote servers, use the full URL including protocol and port.
serverUrl: 'http://localhost:1234'
serverUrl: 'https://imessage.example.com'
serverUrl: 'http://192.168.1.100:1234'
​
apiKey
string
Optional API key for authentication.If your server is configured to require API key authentication, provide it here. The API key is sent in the X-API-Key header for HTTP requests and in the Socket.IO auth payload for WebSocket connections.
apiKey: process.env.API_KEY
apiKey: 'your-api-key-here'
Without an API key, the SDK operates in “legacy mode” for servers that don’t require authentication. The ready event will fire immediately upon connection.
​
logLevel
'debug' | 'info' | 'warn' | 'error'
default:"info"
The logging level for the SDK.Controls the verbosity of log output:
  • debug - All logs including detailed debugging information
  • info - Informational messages, warnings, and errors
  • warn - Only warnings and errors
  • error - Only errors
logLevel: 'debug'  // Development
logLevel: 'info'   // Production (default)
logLevel: 'warn'   // Quiet mode
logLevel: 'error'  // Errors only
​
logToFile
boolean
default:"true"
Whether to write logs to a file.When enabled, the SDK writes logs to a file in addition to console output. Disable this in serverless or containerized environments where file system access is limited.
logToFile: true   // Enable file logging (default)
logToFile: false  // Console only
File logging is useful for debugging production issues, but may consume disk space over time.

​
Configuration Examples

​
Development Configuration

For local development with detailed logging: 
import { SDK } from '@photon-ai/advanced-imessage-kit';

const sdk = SDK({
  serverUrl: 'http://localhost:1234',
  logLevel: 'debug',
  logToFile: true,
});

​
Production Configuration

For production with environment variables and error-level logging: 
import { SDK } from '@photon-ai/advanced-imessage-kit';

const sdk = SDK({
  serverUrl: process.env.SERVER_URL ?? 'http://localhost:1234',
  apiKey: process.env.API_KEY,
  logLevel: 'error',
  logToFile: false,
});

​
Remote Server Configuration

Connecting to a remote server with authentication: 
import { SDK } from '@photon-ai/advanced-imessage-kit';

const sdk = SDK({
  serverUrl: 'https://imessage.company.com',
  apiKey: process.env.IMESSAGE_API_KEY,
  logLevel: 'info',
  logToFile: true,
});

​
TypeScript Configuration

Full type safety with TypeScript: 
import { SDK, type ClientConfig } from '@photon-ai/advanced-imessage-kit';

const config: ClientConfig = {
  serverUrl: process.env.SERVER_URL ?? 'http://localhost:1234',
  apiKey: process.env.API_KEY,
  logLevel: 'info',
  logToFile: true,
};

const sdk = SDK(config);

​
Environment Variables

Use environment variables for flexible configuration across environments:
1

Create .env file

Create a .env file in your project root:
.env
SERVER_URL=http://localhost:1234
API_KEY=your-api-key-here
LOG_LEVEL=info
2

Install dotenv (if needed)

If you’re not using a framework that loads .env files automatically:
npm install dotenv
3

Load environment variables

Load the variables in your application:
import 'dotenv/config';
import { SDK } from '@photon-ai/advanced-imessage-kit';

const sdk = SDK({
  serverUrl: process.env.SERVER_URL,
  apiKey: process.env.API_KEY,
  logLevel: process.env.LOG_LEVEL as 'debug' | 'info' | 'warn' | 'error',
});

​
Singleton Pattern

The SDK uses a singleton pattern - calling SDK() multiple times returns the same instance: 
import { SDK } from '@photon-ai/advanced-imessage-kit';

// First call creates the instance
const sdk1 = SDK({ serverUrl: 'http://localhost:1234' });

// Subsequent calls return the same instance
const sdk2 = SDK(); // Returns sdk1
const sdk3 = SDK(); // Returns sdk1

console.log(sdk1 === sdk2); // true
console.log(sdk2 === sdk3); // true
You can also use AdvancedIMessageKit.getInstance() directly for the same behavior. The SDK() export is a convenience wrapper around this method.

​
Advanced: Direct Instantiation

For advanced use cases where you need multiple instances (not recommended for most applications): 
import { AdvancedIMessageKit } from '@photon-ai/advanced-imessage-kit';

// Create a new instance directly (bypasses singleton)
const sdk = new AdvancedIMessageKit({
  serverUrl: 'http://localhost:1234',
  apiKey: process.env.API_KEY,
  logLevel: 'info',
});
Direct instantiation creates a new instance that is not shared globally. This is rarely needed and can lead to multiple WebSocket connections. Use the singleton SDK() function in most cases.

​
Connection Configuration

The SDK automatically configures the Socket.IO connection with optimal settings:
  • Transport: WebSocket-only (polling disabled to prevent message duplication)
  • Timeout: 10 seconds to avoid frequent reconnections
  • Reconnection: Enabled with exponential backoff (100ms - 2000ms)
  • Force New: Ensures fresh connections to avoid state pollution
These settings are optimized for reliability and are not currently configurable.

​
Next Steps

Quick Start

Build your first integration with the configured SDK

API Reference

Explore all available methods and modules

Events

Learn about event handling and real-time updates

Examples

See configuration in action with real examples

Build docs developers (and LLMs) love

Get started for freeTalk to us