A powerful and easy-to-use Node.js client for interacting with the A1Base API. Give your AI agents a phone number, an email, and real autonomy on the internet.
- Send individual messages via WhatsApp
- Send group messages with attachments
- Retrieve message and thread details
- Get recent messages from threads
- Handle incoming WhatsApp messages
- Built-in security features:
- HTTPS-only communication
- Rate limiting (10 req/s default)
- Input sanitization
- Webhook security
- Safe error handling
npm install a1base-nodeAll API communication is enforced over HTTPS to ensure data security in transit. The package automatically upgrades all HTTP requests to HTTPS.
Built-in rate limiting protects against abuse and ensures fair API usage:
- Default limit: 10 requests per second
- Configurable through client initialization
- Automatic request queuing and retry mechanism
Automatic sanitization of all user inputs:
- Message content validation and sanitization
- Attachment URI validation
- Phone number format verification
- Service type validation (whatsapp/telegram)
Enhanced webhook security measures:
- Timestamp validation to prevent replay attacks
- Secret key verification
- Request signature validation
- IP allowlist support
Secure error handling implementation:
- Sanitized error messages
- No sensitive data exposure
- Detailed logging (without sensitive information)
- Custom error types for better debugging
Importing the Library You can import the A1BaseAPI class using CommonJS or ES Module syntax.
// CommonJS
const { A1BaseAPI } = require('a1base-node');
// ES Module
import { A1BaseAPI } from 'a1base-node';Initialize the A1BaseAPI client with your API credentials. Both apiKey and apiSecret are required for authentication.
const credentials = {
apiKey: 'YOUR_API_KEY',
apiSecret: 'YOUR_API_SECRET',
};
// HTTPS is enforced for security
const baseURL = 'https://api.a1base.com/v1';
const client = new A1BaseAPI({ credentials, baseURL });sendIndividualMessage Sends an individual message to a specific recipient.
const messageData = {
content: "Hello, World!", // Message body text
from: "+1234567890", // Sender phone number
to: "+0987654321", // Recipient phone number
service: "whatsapp", // 'whatsapp' or 'telegram'
attachment_uri: "https://...", // Optional file/media attachment
};
try {
const response = await client.sendIndividualMessage("accountId", messageData);
console.log("Message sent:", response);
// Response: { "to": "61433174782", "from": "61421868490", "body": "Hello, World!", "status": "queued" }
} catch (error) {
console.error("Error:", error.message);
}sendGroupMessage Sends a message to a group thread.
const groupMessageData = {
content: "Hello, Group!", // Message body text
from: "+1234567890", // Sender's phone number
thread_id: "123", // Thread ID
service: "whatsapp", // Chat service (whatsapp/telegram)
attachment_uri: "https://...", // Optional file/media attachment
};
try {
const response = await client.sendGroupMessage("accountId", groupMessageData);
console.log("Group message sent:", response);
// Response: { "thread_id": "123", "body": "Hello, Group!", "status": "queued" }
} catch (error) {
console.error("Error:", error.message);
}getMessageDetails Retrieves detailed information about a specific individual message.
try {
const details = await client.getMessageDetails("accountId", "messageId");
console.log("Message Details:", details);
} catch (error) {
console.error("Error:", error.message);
}getChatGroupDetails Retrieves comprehensive details about a specific chat group thread.
try {
const groupDetails = await client.getChatGroupDetails(
"accountId",
"threadId"
);
console.log("Thread Details:", groupDetails);
} catch (error) {
console.error("Error:", error.message);
}getRecentMessages Retrieves recent messages from a specific chat thread.
try {
const messages = await client.getRecentMessages("accountId", "threadId");
console.log("Recent Messages:", messages);
} catch (error) {
console.error("Error:", error.message);
}getAllThreads Retrieves all chat threads for an account.
try {
const threads = await client.getAllThreads("accountId");
console.log("All Threads:", threads);
} catch (error) {
console.error("Error:", error.message);
}getAllThreadsByNumber Retrieves all chat threads for a specific phone number.
try {
const threads = await client.getAllThreadsByNumber(
"accountId",
"phoneNumber"
);
console.log("Threads for Number:", threads);
} catch (error) {
console.error("Error:", error.message);
}handleWhatsAppIncoming Handles incoming WhatsApp webhook data.
// Webhook data structure
const webhookData = {
external_thread_id: "3456098@s.whatsapp",
external_message_id: "2asd5678cfvgh123",
chat_type: "group", // 'group', 'individual', or 'broadcast'
content: "Hello!",
sender_name: "Bobby",
sender_number: "61421868490",
participants: ["61421868490", "61433174782"],
a1_account_number: "61421868490",
timestamp: 1734486451000,
secret_key: "xxx",
};
try {
const result = await client.handleWhatsAppIncoming(webhookData);
console.log("Webhook processed:", result);
} catch (error) {
console.error("Error:", error.message);
}A1Base provides powerful email capabilities through the SDK, allowing you to create email addresses, send emails, and process incoming email webhooks.
createEmailAddress Creates a new email address for an account.
const emailData = {
address: "yourname", // Local part of the email (before @)
domain_name: "a1send.com", // Domain name (a1send.com or a101.bot)
};
try {
const response = await client.createEmailAddress("accountId", emailData);
console.log("Email address created:", response);
// Response: { "address": "yourname@a1send.com", "status": "active" }
} catch (error) {
console.error("Error:", error.message);
}sendEmailMessage Sends an email message to a recipient.
const emailData = {
sender_address: "yourname@a1send.com", // Sender's email address
recipient_address: "recipient@example.com", // Recipient's email address
subject: "Hello from A1Base", // Email subject
body: "This is an example email body.", // Email content (plain text or HTML)
headers: {
cc: "someone@example.com", // Optional CC recipients
bcc: "hidden@example.com", // Optional BCC recipients
},
};
try {
const response = await client.sendEmailMessage("accountId", emailData);
console.log("Email sent:", response);
// Response: { "recipient": "recipient@example.com", "status": "queued" }
} catch (error) {
console.error("Error:", error.message);
}handleEmailIncoming Processes incoming email webhook data.
// Webhook data structure for incoming emails
const webhookData = {
email_id: "a82b3e6b-dc79-46ad-9284-a166629592e3", // Unique identifier for the email
subject: "Email Subject", // Subject line of the email
sender_address: "sender@example.com", // Email address of the sender
recipient_address: "yourname@a1send.com", // Your A1Base email address
timestamp: "2025-03-19T10:24:08.46083+00:00", // ISO 8601 timestamp
service: "email", // Always "email" for email webhooks
raw_email_data: "Full email content including headers and body", // Complete raw email
};
try {
const result = await client.handleEmailIncoming(webhookData);
console.log("Email webhook processed:", result);
} catch (error) {
console.error("Error:", error.message);
}The A1BaseAPI client throws descriptive errors based on API responses. It's essential to handle these errors gracefully in your application. Example with try-catch:
try {
const response = await client.sendIndividualMessage('account123', messageData);
console.log(response);
} catch (error) {
console.error('Error:', error.message);
}
try {
const response = await client.sendIndividualMessage('account123', messageData);
console.log(response);
} catch (error) {
console.error('Error:', error.message);
}