Impression WhatsApp Client

A simple and lightweight WhatsApp messaging client that connects to the Impression Platform API for sending messages.

Installation

npm install impression-client

Quick Setup

1. Get your API key from your Impression dashboard at https://impression.com.ng
2. Set up credentials using the CLI:

npx impression-client setup

Or manually create a .env file:

IMPRESSION_API_KEY=your-api-key-here

Basic Usage

const ImpressionClient = require('impression-client');

// Initialize client
const client = new ImpressionClient({
  apiKey: 'your-api-key-here' // or set IMPRESSION_API_KEY env var
});

// Send a message - Option 1: Separate parameters
async function sendMessage() {
  try {
    const result = await client.sendMessage('2349066100815', 'Hello from Impression!');
    console.log('Message sent:', result);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

// Send a message - Option 2: Object parameter
async function sendMessageWithObject() {
  try {
    const result = await client.sendMessage({
      to: '2349066100815',
      message: 'Hello from Impression!'
    });
    console.log('Message sent:', result);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

sendMessage();

CLI Usage

Setup

npx impression-client setup

Send a message

npx impression-client send --to 2349066100815 --message "Hello World!"

Send a status message

npx impression-client send-status --message "Hello everyone!"

Get message statistics

npx impression-client stats --time-range 7d

Get conversation history

npx impression-client history --number 2349066100815 --limit 10

API Methods

sendMessage(to, message, options) or sendMessage({to, message, ...options})

Send a WhatsApp message to a single recipient.

Traditional Parameters:

• to (string): Phone number with country code (e.g., '2349066100815')
• message (string): Message content
• options (object): Additional options (optional)

Object Parameter:

• options (object): Object containing {to, message, ...additionalOptions}

Returns: Promise with message details

// Method 1: Traditional parameters
const result = await client.sendMessage('2349066100815', 'Hello!');

// Method 2: Object parameter
const result = await client.sendMessage({
  to: '2349066100815',
  message: 'Hello!'
});

console.log(result.messageId); // Message ID from Impression

sendStatusMessage(message, options)

Send a WhatsApp status message (broadcast).

Parameters:

• message (string): Status message content
• options (object): Additional options (optional)

Returns: Promise with status details

const result = await client.sendStatusMessage('Hello from my status!');
console.log(`Status sent to ${result.recipientCount} contacts`);

getMessageStats(options)

Get message statistics for your device.

Parameters:

• options (object): Query options (timeRange: '7d', '30d', etc.)

Returns: Promise with statistics

const stats = await client.getMessageStats({ timeRange: '7d' });
console.log(`Total sent: ${stats.data.totalSent}`);

getConversationHistory(recipientNumber, options)

Get conversation history with a specific contact.

Parameters:

• recipientNumber (string): Phone number to get history for
• options (object): Query options (limit, etc.)

Returns: Promise with conversation history

const history = await client.getConversationHistory('2349066100815', { limit: 20 });
console.log(`Found ${history.count} messages`);

retryMessage(messageId)

Retry a failed message or trigger bulk retry.

Parameters:

• messageId (string): Message ID to retry (optional - omit for bulk retry)

Returns: Promise with retry result

// Retry specific message
await client.retryMessage('msg_123456789');

// Trigger bulk retry of all failed messages
await client.retryMessage();

Events

The client emits events for monitoring:

// Message sent successfully
client.on('message_sent', (data) => {
  console.log(`Message sent to ${data.to}:`, data.messageId);
});

// Message send failed
client.on('send_error', (error) => {
  console.error(`Failed to send to ${error.to}:`, error.error);
});

// Status message sent
client.on('status_sent', (data) => {
  console.log(`Status sent to ${data.recipientCount} contacts`);
});

// Status send failed
client.on('status_error', (error) => {
  console.error('Status send failed:', error.error);
});

// General API errors
client.on('error', (error) => {
  console.error('API Error:', error);
});

Error Handling

The client provides detailed error information:

try {
  await client.sendMessage('invalid-number', 'Test');
} catch (error) {
  console.error('Error code:', error.response?.status);
  console.error('Error message:', error.message);
}

Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | IMPRESSION_API_KEY | Your Impression API key | Yes |

Phone Number Format

Phone numbers should include the country code without the '+' symbol:

• ✅ Correct: 2349066100815 (Nigeria)
• ✅ Correct: 14155552345 (US)
• ❌ Wrong: +2349066100815
• ❌ Wrong: 08123456789 (missing country code)

The client automatically cleans phone numbers by removing non-digit characters.

Rate Limiting

The Impression API may have rate limits. The client includes automatic retry logic for temporary failures.

License

MIT

Support

For support with the Impression Platform API, visit: https://impression.com.ng

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Changelog

1.0.4

• ✅ BREAKING: Removed non-existent API endpoints
• ✅ BREAKING: Replaced fake methods with real Impression API endpoints
• ✅ Added sendStatusMessage() for WhatsApp status broadcasts
• ✅ Added getMessageStats() for device statistics
• ✅ Added getConversationHistory() for chat history
• ✅ Added retryMessage() for message retry functionality
• ✅ Removed bulkSend(), checkStatus(), sendGroupMessage() (non-existent)
• ✅ Updated CLI commands to match real API
• ✅ Fixed API field mapping (number instead of to)

1.0.3

• Fixed API field mapping for send-message endpoint
• Updated payload to use number field instead of to

1.0.2

• Added support for object-style parameter in sendMessage()
• Both sendMessage(to, message) and sendMessage({to, message}) now work

1.0.1

• Bug fixes and improvements

1.0.0

• Initial release
• Basic message sending functionality
• CLI tools
• Event system