Skip to main content

Installation

Install the EnviaAI SDK using npm or yarn:
npm install @enviaai/sdk

Quick Start

import { EnviaAI } from '@enviaai/sdk';

const client = new EnviaAI({
  apiKey: process.env.ENVIAAI_API_KEY
});

// Send a message
const response = await client.messages.send({
  instanceId: 'inst_abc123',
  to: '5511999999999',
  message: 'Hello from EnviaAI!'
});

console.log('Message ID:', response.messageId);

Configuration

Client Options

import { EnviaAI } from '@enviaai/sdk';

const client = new EnviaAI({
  apiKey: 'your-api-key',          // Required
  baseUrl: 'https://api.enviaai.app', // Optional, defaults to production
  timeout: 30000,                   // Optional, request timeout in ms
  maxRetries: 3                     // Optional, number of retries on failure
});

Environment Variables

The SDK automatically reads from environment variables:
ENVIAAI_API_KEY=your-api-key
ENVIAAI_BASE_URL=https://api.enviaai.app
// API key is read from ENVIAAI_API_KEY
const client = new EnviaAI();

Messages API

Send Text Message

const response = await client.messages.send({
  instanceId: 'inst_abc123',
  to: '5511999999999',
  message: 'Hello! How can I help you?'
});

Send Media Message

// Image
const imageResponse = await client.messages.send({
  instanceId: 'inst_abc123',
  to: '5511999999999',
  mediaUrl: 'https://example.com/image.jpg',
  mediaType: 'image',
  caption: 'Check this out!'
});

// Document
const docResponse = await client.messages.send({
  instanceId: 'inst_abc123',
  to: '5511999999999',
  mediaUrl: 'https://example.com/document.pdf',
  mediaType: 'document',
  filename: 'invoice.pdf'
});

// Audio
const audioResponse = await client.messages.send({
  instanceId: 'inst_abc123',
  to: '5511999999999',
  mediaUrl: 'https://example.com/audio.mp3',
  mediaType: 'audio'
});

Get Message Status

const status = await client.messages.getStatus('msg_xyz789');
console.log(status.status); // 'sent', 'delivered', 'read', 'failed'

List Chats

const chats = await client.messages.getChats({
  instanceId: 'inst_abc123',
  limit: 20,
  unreadOnly: true
});

chats.data.forEach(chat => {
  console.log(`${chat.contactName}: ${chat.unreadCount} unread`);
});

Get Chat Messages

const messages = await client.messages.getChatMessages({
  instanceId: 'inst_abc123',
  chatId: 'chat_def456',
  limit: 50
});

Instances API

List Instances

const instances = await client.instances.list();

instances.data.forEach(instance => {
  console.log(`${instance.name}: ${instance.status}`);
});

Get Instance Status

const status = await client.instances.getStatus('inst_abc123');

if (status.data.status === 'connected') {
  console.log(`Connected as ${status.data.phone}`);
} else if (status.data.status === 'qr_pending') {
  console.log('Scan QR:', status.data.qrCode);
}

Connect Instance

await client.instances.connect('inst_abc123');

// Poll for QR code
const status = await client.instances.getStatus('inst_abc123');
if (status.data.qrCode) {
  // Display QR code to user
}

Disconnect Instance

await client.instances.disconnect('inst_abc123');

Webhooks API

Create Webhook

const webhook = await client.webhooks.create({
  url: 'https://myapp.com/webhooks/enviaai',
  events: ['message.received', 'message.delivered'],
  secret: 'my-webhook-secret'
});

List Webhooks

const webhooks = await client.webhooks.list();

Update Webhook

await client.webhooks.update('wh_abc123', {
  events: ['message.received', 'message.delivered', 'message.read']
});

Delete Webhook

await client.webhooks.delete('wh_abc123');

Verify Webhook Signature

import { EnviaAI } from '@enviaai/sdk';

const isValid = EnviaAI.webhooks.verifySignature(
  payload,
  signature,
  'your-webhook-secret'
);

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:
import {
  EnviaAI,
  Message,
  Instance,
  SendMessageOptions,
  MessageStatus
} from '@enviaai/sdk';

const client = new EnviaAI({ apiKey: 'your-key' });

// Full type inference
const options: SendMessageOptions = {
  instanceId: 'inst_abc123',
  to: '5511999999999',
  message: 'Hello!'
};

const response: Message = await client.messages.send(options);

Error Handling

import { EnviaAI, EnviaAIError, RateLimitError } from '@enviaai/sdk';

try {
  await client.messages.send({
    instanceId: 'inst_abc123',
    to: '5511999999999',
    message: 'Hello!'
  });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof EnviaAIError) {
    console.log(`API Error: ${error.code} - ${error.message}`);
  } else {
    throw error;
  }
}

Error Types

Error ClassDescription
EnviaAIErrorBase error class for all API errors
AuthenticationErrorInvalid or missing API key
RateLimitErrorRate limit exceeded
ValidationErrorInvalid request parameters
NotFoundErrorResource not found
ServerErrorInternal server error

Pagination

// Manual pagination
let offset = 0;
const limit = 50;
let allChats = [];

while (true) {
  const response = await client.messages.getChats({
    instanceId: 'inst_abc123',
    limit,
    offset
  });

  allChats = allChats.concat(response.data);

  if (!response.pagination.hasMore) break;
  offset += limit;
}

// Using async iterator (coming soon)
for await (const chat of client.messages.getChatsIterator({
  instanceId: 'inst_abc123'
})) {
  console.log(chat.contactName);
}

Logging

Enable debug logging:
const client = new EnviaAI({
  apiKey: 'your-key',
  debug: true
});

// Or set environment variable
// ENVIAAI_DEBUG=true

Examples

Express.js Webhook Handler

import express from 'express';
import { EnviaAI } from '@enviaai/sdk';

const app = express();
const client = new EnviaAI();

app.post('/webhooks/enviaai', express.json(), async (req, res) => {
  const signature = req.headers['x-enviaai-signature'] as string;

  if (!EnviaAI.webhooks.verifySignature(req.body, signature, 'secret')) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;

  if (event.event === 'message.received') {
    // Auto-reply
    await client.messages.send({
      instanceId: event.data.instanceId,
      to: event.data.from,
      message: 'Thanks for your message! We\'ll get back to you soon.'
    });
  }

  res.status(200).send('OK');
});

app.listen(3000);

Bulk Message Sending

import { EnviaAI } from '@enviaai/sdk';
import pLimit from 'p-limit';

const client = new EnviaAI();
const limit = pLimit(10); // Max 10 concurrent requests

const contacts = [
  { phone: '5511999999999', name: 'John' },
  { phone: '5521988888888', name: 'Jane' },
  // ... more contacts
];

const results = await Promise.all(
  contacts.map(contact =>
    limit(() =>
      client.messages.send({
        instanceId: 'inst_abc123',
        to: contact.phone,
        message: `Hello ${contact.name}! Check out our new products.`
      })
    )
  )
);

console.log(`Sent ${results.length} messages`);

Resources