Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import { describe, expect, expectTypeOf, it } from 'vitest';
import { OpenWAClient, type BatchCancelResponse } from '../src';
import { MockTransport } from './helpers';
function client(t: MockTransport): OpenWAClient {
return new OpenWAClient({ baseUrl: 'http://x', apiKey: 'k', fetch: t.asFetch() });
}
it('preserves message-time filters and the unknown timestamp count', async () => {
const t = new MockTransport().on('GET', /\/messages$/, { body: { messages: [], total: 0, unknownTimestampTotal: 2 } });
const page = await client(t).messages.list('s', {
since: 1789855200000.5, until: 1789941600000, direction: 'incoming',
orderBy: 'timestamp', type: 'image', messageId: 'M1',
});
const query = new URL(t.lastCall!.url).searchParams;
expect(query.get('since')).toBe('1789855200000.5');
expect(query.get('until')).toBe('1789941600000');
expect(query.get('direction')).toBe('incoming');
expect(query.get('orderBy')).toBe('timestamp');
expect(query.get('type')).toBe('image');
expect(query.get('messageId')).toBe('M1');
expect(page.unknownTimestampTotal).toBe(2);
});
describe('MessagesResource idempotency keys', () => {
const sends: Array<[string, (c: OpenWAClient, key?: string) => Promise<unknown>]> = [
['send-text', (c, key) => c.messages.sendText('s', { chatId: '[email protected]', text: 'hi', mentions: ['[email protected]'] }, key)],
['send-image', (c, key) => c.messages.sendImage('s', { chatId: '[email protected]', url: 'http://image', caption: 'image' }, key)],
['send-video', (c, key) => c.messages.sendVideo('s', { chatId: '[email protected]', url: 'http://video', caption: 'video' }, key)],
['send-audio', (c, key) => c.messages.sendAudio('s', { chatId: '[email protected]', url: 'http://audio', ptt: true }, key)],
['send-document', (c, key) => c.messages.sendDocument('s', { chatId: '[email protected]', base64: 'YQ==', mimetype: 'application/pdf', filename: 'a.pdf' }, key)],
['send-sticker', (c, key) => c.messages.sendSticker('s', { chatId: '[email protected]', url: 'http://sticker', mimetype: 'image/webp' }, key)],
['send-location', (c, key) => c.messages.sendLocation('s', { chatId: '[email protected]', latitude: 1, longitude: 2 }, key)],
['send-contact', (c, key) => c.messages.sendContact('s', { chatId: '[email protected]', contactName: 'A', contactNumber: '628' }, key)],
['send-template', (c, key) => c.messages.sendTemplate('s', { chatId: '[email protected]', templateName: 'welcome', vars: { name: 'A' } }, key)],
['send-poll', (c, key) => c.messages.sendPoll('s', { chatId: '[email protected]', name: 'Question', options: ['A', 'B'] }, key)],
['reply', (c, key) => c.messages.reply('s', { chatId: '[email protected]', quotedMessageId: 'q', text: 'reply' }, key)],
['forward', (c, key) => c.messages.forward('s', { fromChatId: '[email protected]', toChatId: '[email protected]', messageId: 'm' }, key)],
];
it.each(sends)('%s keeps keys local to each call and preserves JSON', async (route, send) => {
const t = new MockTransport().on('POST', new RegExp(`/messages/${route}$`), { body: { messageId: 'm', timestamp: 1 } });
const c = new OpenWAClient({ baseUrl: 'http://localhost', apiKey: 'k', fetch: t.asFetch() });
await send(c);
const originalBody = t.lastCall!.body;
expect(t.lastCall!.headers['idempotency-key']).toBeUndefined();
for (const key of ['first-key', 'second-key']) {
await send(c, key);
expect(t.lastCall!.method).toBe('POST');
expect(t.lastCall!.url).toBe(`http://localhost/api/sessions/s/messages/${route}`);
expect(t.lastCall!.headers['idempotency-key']).toBe(key);
expect(t.lastCall!.body).toEqual(originalBody);
}
await send(c);
expect(t.lastCall!.headers['idempotency-key']).toBeUndefined();
expect(t.lastCall!.body).toEqual(originalBody);
});
it('treats a null key from an untyped caller as no key, as the Python and PHP SDKs do', async () => {
const t = new MockTransport().on('POST', /\/messages\/send-text$/, { body: { messageId: 'm', timestamp: 1 } });
const c = new OpenWAClient({ baseUrl: 'http://localhost', apiKey: 'k', fetch: t.asFetch() });
await c.messages.sendText('s', { chatId: '[email protected]', text: 'hi' }, null as unknown as string);
expect(t.lastCall!.headers['idempotency-key']).toBeUndefined();
});
it('overrides a mixed-case default without changing later calls', async () => {
const t = new MockTransport().on('POST', /send-text$/, { body: { messageId: 'm', timestamp: 1 } });
const headers = { 'iDeMpOtEnCy-KeY': 'default-key', 'X-Trace': 'trace' };
const c = new OpenWAClient({ baseUrl: 'http://localhost', apiKey: 'k', defaultHeaders: headers, fetch: t.asFetch() });
const body = { chatId: '[email protected]', text: 'hi' };
await c.messages.sendText('s', body, 'explicit-key');
expect(t.lastCall!.headers['idempotency-key']).toBe('explicit-key');
expect(t.lastCall!.headers['x-trace']).toBe('trace');
expect(headers['iDeMpOtEnCy-KeY']).toBe('default-key');
await c.messages.sendText('s', body);
expect(t.lastCall!.headers['idempotency-key']).toBe('default-key');
});
it.each(['', 'has space', ' key', 'key ', 'key\n', 'key\t', 'caf\u00e9', 'a\u007fb', 'x'.repeat(256)])(
'rejects invalid key %j before transport',
async key => {
const t = new MockTransport().on('POST', /send-text$/, { body: { messageId: 'm', timestamp: 1 } });
const c = new OpenWAClient({ baseUrl: 'http://localhost', apiKey: 'k', fetch: t.asFetch() });
await expect(c.messages.sendText('s', { chatId: '[email protected]', text: 'hi' }, key)).rejects.toThrow(TypeError);
expect(t.calls).toHaveLength(0);
},
);
it.each(['!', '~', 'x', 'x'.repeat(255)])('accepts visible ASCII key %j', async key => {
const t = new MockTransport().on('POST', /send-text$/, { body: { messageId: 'm', timestamp: 1 } });
const c = new OpenWAClient({ baseUrl: 'http://localhost', apiKey: 'k', fetch: t.asFetch() });
await c.messages.sendText('s', { chatId: '[email protected]', text: 'hi' }, key);
expect(t.lastCall!.headers['idempotency-key']).toBe(key);
});
});
describe('MessagesResource — exact paths', () => {
it('sendText posts to /messages/send-text (NOT /messages/text)', async () => {
const t = new MockTransport().on('POST', /send-text$/, { body: { messageId: 'm1', timestamp: 1 } });
await client(t).messages.sendText('s1', { chatId: '[email protected]', text: 'hi' });
expect(t.lastCall!.url).toBe('http://x/api/sessions/s1/messages/send-text');
expect(t.lastCall!.body).toEqual({ chatId: '[email protected]', text: 'hi' });
});
it('sendText forwards mentions verbatim', async () => {
const t = new MockTransport().on('POST', /send-text$/, { body: { messageId: 'm1', timestamp: 1 } });
await client(t).messages.sendText('s1', { chatId: '[email protected]', text: 'hi @628123', mentions: ['[email protected]'] });
expect(t.lastCall!.body).toEqual({ chatId: '[email protected]', text: 'hi @628123', mentions: ['[email protected]'] });
});
it('sendPoll posts to /messages/send-poll', async () => {
const t = new MockTransport().on('POST', /send-poll$/, { body: { messageId: 'm2', timestamp: 2 } });
const res = await client(t).messages.sendPoll('s1', {
chatId: '[email protected]',
name: 'Where?',
options: ['Park', 'Beach'],
allowMultipleAnswers: true,
});
expect(t.lastCall!.url).toBe('http://x/api/sessions/s1/messages/send-poll');
expect(t.lastCall!.body).toEqual({
chatId: '[email protected]',
name: 'Where?',
options: ['Park', 'Beach'],
allowMultipleAnswers: true,
});
expect(res.messageId).toBe('m2');
});
it('sendImage posts to /messages/send-image', async () => {
const t = new MockTransport().on('POST', /send-image$/, { body: { messageId: 'm', timestamp: 2 } });
await client(t).messages.sendImage('s', { chatId: '[email protected]', url: 'http://img' });
expect(t.lastCall!.url).toContain('/messages/send-image');
});
it('sendVideo / sendAudio / sendDocument / sendSticker use correct segments', async () => {
const cases: Array<[string, (c: OpenWAClient) => Promise<unknown>]> = [
['send-video', c => c.messages.sendVideo('s', { chatId: '[email protected]', url: 'u' })],
['send-audio', c => c.messages.sendAudio('s', { chatId: '[email protected]', url: 'u' })],
['send-document', c => c.messages.sendDocument('s', { chatId: '[email protected]', filename: 'f.pdf' })],
['send-sticker', c => c.messages.sendSticker('s', { chatId: '[email protected]', url: 'u' })],
];
for (const [segment, fn] of cases) {
const t = new MockTransport().on('POST', new RegExp(`${segment}$`), { body: { messageId: 'm', timestamp: 3 } });
await fn(client(t));
expect(t.lastCall!.url).toContain(`/messages/${segment}`);
}
});
it('sendLocation / sendContact / sendTemplate', async () => {
const t = new MockTransport()
.on('POST', /send-location/, { body: { messageId: 'm', timestamp: 1 } })
.on('POST', /send-contact/, { body: { messageId: 'm', timestamp: 1 } })
.on('POST', /send-template/, { body: { messageId: 'm', timestamp: 1 } });
const c = client(t);
await c.messages.sendLocation('s', { chatId: '[email protected]', latitude: -6.2, longitude: 106.8 });
expect(t.lastCall!.url).toContain('/messages/send-location');
await c.messages.sendContact('s', { chatId: '[email protected]', contactName: 'A', contactNumber: '628' });
expect(t.lastCall!.url).toContain('/messages/send-contact');
await c.messages.sendTemplate('s', { chatId: '[email protected]', templateId: 't1', vars: { name: 'Sam' } });
expect(t.lastCall!.url).toContain('/messages/send-template');
// Server DTO field is `vars` (NOT `variables`) — body must forward verbatim.
expect(t.lastCall!.body).toEqual({ chatId: '[email protected]', templateId: 't1', vars: { name: 'Sam' } });
});
it('sendTemplate accepts templateName as the alternative to templateId', async () => {
const t = new MockTransport().on('POST', /send-template/, { body: { messageId: 'm', timestamp: 1 } });
await client(t).messages.sendTemplate('s', { chatId: '[email protected]', templateName: 'welcome', vars: { x: '1' } });
expect(t.lastCall!.body).toEqual({ chatId: '[email protected]', templateName: 'welcome', vars: { x: '1' } });
});
it('list returns the {messages,total} wrapper the server actually sends', async () => {
const t = new MockTransport().on('GET', /\/messages$/, {
body: {
messages: [
{
id: '1',
sessionId: 's',
chatId: '[email protected]',
from: '[email protected]',
to: 's',
type: 'text',
direction: 'incoming',
status: 'delivered',
createdAt: '',
},
],
total: 1,
},
});
const res = await client(t).messages.list('s', { chatId: '[email protected]' });
expect(res.total).toBe(1);
expect(res.messages).toHaveLength(1);
});
// Asserted on the BODY, not the URL: the field is what this is about, and a URL assertion cannot
// see a dropped key. One case per request type, because each is a separate declaration — a type
// that forgot the field would still send it from JS but would not compile for a typed caller.
it.each([
[
'send-text',
(c: OpenWAClient) => c.messages.sendText('s1', { chatId: '[email protected]', text: 'hi', quotedMessageId: 'q1' }),
],
[
'send-image',
(c: OpenWAClient) => c.messages.sendImage('s1', { chatId: '[email protected]', url: 'http://u', quotedMessageId: 'q1' }),
],
[
'send-location',
(c: OpenWAClient) =>
c.messages.sendLocation('s1', { chatId: '[email protected]', latitude: 1, longitude: 2, quotedMessageId: 'q1' }),
],
[
'send-contact',
(c: OpenWAClient) =>
c.messages.sendContact('s1', {
chatId: '[email protected]',
contactName: 'A',
contactNumber: '628',
quotedMessageId: 'q1',
}),
],
[
'send-poll',
(c: OpenWAClient) =>
c.messages.sendPoll('s1', { chatId: '[email protected]', name: 'Q', options: ['a', 'b'], quotedMessageId: 'q1' }),
],
])('%s forwards quotedMessageId in the body', async (route, call) => {
const t = new MockTransport().on('POST', new RegExp(`${route}$`), { body: { messageId: 'm', timestamp: 1 } });
await call(client(t));
expect(t.lastCall!.body).toMatchObject({ quotedMessageId: 'q1' });
});
// Known-negative control: an ordinary send must not carry the key at all, so an implementation
// that always emitted it (as `undefined`, which JSON.stringify drops but a proxy may not) fails.
it('omits quotedMessageId entirely on an ordinary send', async () => {
const t = new MockTransport().on('POST', /send-image$/, { body: { messageId: 'm', timestamp: 1 } });
await client(t).messages.sendImage('s1', { chatId: '[email protected]', url: 'http://u' });
expect(t.lastCall!.body).not.toHaveProperty('quotedMessageId');
});
it('reply / forward / react / delete', async () => {
const t = new MockTransport()
.on('POST', /\/messages\/reply$/, { body: { messageId: 'm', timestamp: 1 } })
.on('POST', /\/messages\/forward$/, { body: { messageId: 'm', timestamp: 1 } })
.on('POST', /\/messages\/react$/, { body: { success: true } })
.on('POST', /\/messages\/delete$/, { body: { success: true } });
const c = client(t);
await c.messages.reply('s', { chatId: '[email protected]', quotedMessageId: 'q', text: 'r' });
expect(t.lastCall!.url).toContain('/messages/reply');
await c.messages.forward('s', { fromChatId: '[email protected]', toChatId: '[email protected]', messageId: 'm' });
expect(t.lastCall!.url).toContain('/messages/forward');
await c.messages.react('s', { chatId: '[email protected]', messageId: 'm', emoji: '👍' });
expect(t.lastCall!.url).toContain('/messages/react');
await c.messages.delete('s', { chatId: '[email protected]', messageId: 'm' });
expect(t.lastCall!.url).toContain('/messages/delete');
});
it('clickButton posts to /messages/click-button', async () => {
const t = new MockTransport().on('POST', /\/messages\/click-button$/, {
body: { messageId: 'm2', timestamp: 9 },
});
const res = await client(t).messages.clickButton('s', {
chatId: '[email protected]',
messageId: 'prompt1',
buttonId: 'yes',
text: 'Sim',
});
expect(t.lastCall!.url).toBe('http://x/api/sessions/s/messages/click-button');
expect(t.lastCall!.body).toEqual({
chatId: '[email protected]',
messageId: 'prompt1',
buttonId: 'yes',
text: 'Sim',
});
expect(res.messageId).toBe('m2');
});
it('editMessage posts to /messages/edit and returns the MessageResponse shape', async () => {
const t = new MockTransport().on('POST', /\/messages\/edit$/, { body: { messageId: 'm1', timestamp: 4 } });
const res = await client(t).messages.editMessage('s', { chatId: '[email protected]', messageId: 'm1', body: 'edited' });
expect(t.lastCall!.url).toBe('http://x/api/sessions/s/messages/edit');
expect(t.lastCall!.body).toEqual({ chatId: '[email protected]', messageId: 'm1', body: 'edited' });
expect(res.messageId).toBe('m1');
expect(res.timestamp).toBe(4);
});
it('history puts chatId in the path', async () => {
const t = new MockTransport().on('GET', /\/messages\/[^/]+\/history$/, { body: [] });
await client(t).messages.history('s', '[email protected]', { limit: 5 });
expect(t.lastCall!.url).toContain('/messages/[email protected]/history');
expect(t.lastCall!.url).toContain('limit=5');
});
it('reactions puts chatId and messageId in the path', async () => {
const t = new MockTransport().on('GET', /\/reactions$/, { body: [] });
await client(t).messages.reactions('s', '[email protected]', 'm1');
expect(t.lastCall!.url).toContain('/[email protected]/m1/reactions');
});
it('sendBulk + batchStatus + cancelBatch', async () => {
const t = new MockTransport()
.on('POST', /send-bulk$/, {
body: { batchId: 'b', status: 'queued', totalMessages: 1, estimatedCompletionTime: 't', statusUrl: '/u' },
})
.on('GET', /\/batch\/b$/, {
body: {
batchId: 'b',
status: 'done',
progress: { total: 1, sent: 1, failed: 0, pending: 0, cancelled: 0 },
results: [],
startedAt: 's',
completedAt: 'c',
},
})
.on('POST', /\/batch\/b\/cancel$/, {
body: {
batchId: 'b',
status: 'cancelled',
progress: { total: 1, sent: 0, failed: 0, pending: 0, cancelled: 1 },
},
});
const c = client(t);
await c.messages.sendBulk('s', { messages: [{ chatId: '[email protected]', type: 'text', content: { text: 'x' } }] });
expect(t.lastCall!.url).toContain('/messages/send-bulk');
const status = await c.messages.batchStatus('s', 'b');
expect(status.progress?.sent).toBe(1);
expect(t.lastCall!.url).toContain('/messages/batch/b');
const cancelled = await c.messages.cancelBatch('s', 'b');
// The cancel route answers without the per-recipient `results` the status route carries.
expectTypeOf(cancelled).toEqualTypeOf<BatchCancelResponse>();
expect(cancelled.status).toBe('cancelled');
expect(t.lastCall!.url).toContain('/messages/batch/b/cancel');
expect(t.lastCall!.method).toBe('POST');
});
});