Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import {
ConversationSendEnvelope,
PluginCapabilityError,
PluginCapabilityPermission,
PluginManifest,
} from './plugin.interfaces';
export interface ConversationSendDeps {
manifest: PluginManifest;
assertPermission: (manifest: PluginManifest, permission: PluginCapabilityPermission) => void;
// Full session gate for THIS plugin (manifest scope AND operator activation), bound to the plugin by
// the loader — so conversation.send is confined to activated sessions like every other capability.
assertSessionActive: (sessionId: string) => void;
// Resolve the WA chat id from conversation_mappings when the envelope omits chatId.
resolveChatId: (env: ConversationSendEnvelope) => Promise<string>;
// Run the send inside the hook context the caller is already in, when it is in one: a send from a hook
// handler then cannot re-fire that handler's own message:sending event. A send from an ingress handler
// is in no hook context and runs the full chain. Only 'message:sending' is reachable this way,
// because MessageService fires it synchronously inside sendText/reply. 'message:sent' is emitted later
// by SessionEngineLifecycle's engine callback (onMessageCreate), outside this call's async scope, so
// seeding it here would be a no-op.
runGuarded: <T>(events: string[], run: () => Promise<T>) => Promise<T>;
sendText: (sessionId: string, opts: { chatId: string; text: string; linkPreview?: boolean }) => Promise<unknown>;
reply: (sessionId: string, opts: { chatId: string; quotedMessageId: string; text: string }) => Promise<unknown>;
// Media send by URL. The loader binds this to the per-type MessageService media methods
// (sendImage/sendVideo/sendAudio/sendDocument) — the facade stays DTO-agnostic.
sendMedia: (
sessionId: string,
opts: { chatId: string; url: string; type: ConversationMediaType; caption?: string },
) => Promise<unknown>;
// Location send. The loader binds this to MessageService.sendLocation; `text` maps to the description.
sendLocation: (
sessionId: string,
opts: { chatId: string; latitude: number; longitude: number; description?: string },
) => Promise<unknown>;
}
/**
* Envelope types carried as media by URL. `voice` is a PTT audio note (the loader maps it to an audio
* send with `ptt`). `location` is a non-text type but has no mediaUrl, so it is excluded.
*/
export type ConversationMediaType = 'image' | 'file' | 'audio' | 'video' | 'voice';
const MEDIA_TYPES: readonly ConversationMediaType[] = ['image', 'file', 'audio', 'video', 'voice'];
const isMediaType = (type: ConversationSendEnvelope['type']): type is ConversationMediaType =>
(MEDIA_TYPES as readonly string[]).includes(type);
const isValidLatitude = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v) && v >= -90 && v <= 90;
const isValidLongitude = (v: unknown): v is number =>
typeof v === 'number' && Number.isFinite(v) && v >= -180 && v <= 180;
const MESSAGE_HOOK_EVENTS = ['message:sending'];
export function buildConversationSendFacade(deps: ConversationSendDeps) {
return {
async send(env: ConversationSendEnvelope): Promise<unknown> {
deps.assertPermission(deps.manifest, PluginCapabilityPermission.CONVERSATION_SEND);
const sessionId = env.sessionId;
if (!sessionId) throw new PluginCapabilityError('conversation.send: sessionId is required');
deps.assertSessionActive(sessionId);
const chatId = env.chatId ?? (await deps.resolveChatId(env));
return deps.runGuarded(MESSAGE_HOOK_EVENTS, async () => {
// A location envelope is delivered as a native location pin. Without valid coordinates there
// is NOTHING to send — reject loudly instead of degrading to an empty text message.
if (env.type === 'location') {
// The plugin location port (ConversationSendDeps, PluginMessagePort) carries no quotedMessageId,
// so a location reply would lose its quote. Reject rather than silently drop it (same rule as media).
if (env.replyTo) {
throw new PluginCapabilityError('conversation.send: replyTo is not supported for location messages');
}
if (!isValidLatitude(env.latitude) || !isValidLongitude(env.longitude)) {
throw new PluginCapabilityError(
'conversation.send: type location requires latitude (-90..90) and longitude (-180..180)',
);
}
return deps.sendLocation(sessionId, {
chatId,
latitude: env.latitude,
longitude: env.longitude,
description: env.text,
});
}
// A media type carrying a mediaUrl is sent as native media. A media type WITHOUT a mediaUrl has
// nothing to send as media, so it falls through to the text/reply path — a plugin that puts the
// URL in `text` as a fallback still delivers a (text) message rather than erroring.
if (isMediaType(env.type) && env.mediaUrl) {
// The plugin media port (ConversationSendDeps, PluginMessagePort) carries no quotedMessageId, so
// a media reply would lose its quote. Reject rather than silently drop it.
if (env.replyTo) {
throw new PluginCapabilityError('conversation.send: replyTo is not supported for media messages');
}
return deps.sendMedia(sessionId, { chatId, url: env.mediaUrl, type: env.type, caption: env.text });
}
if (env.replyTo) {
return deps.reply(sessionId, { chatId, quotedMessageId: env.replyTo, text: env.text ?? '' });
}
// Forwarded only when the plugin actually expressed a choice: MessageService widens the engine
// call whenever the key is present, so a blanket `linkPreview: undefined` would rewrite the call
// shape of every plugin send that never asked for a preview.
return deps.sendText(sessionId, {
chatId,
text: env.text ?? '',
...(env.linkPreview === undefined ? {} : { linkPreview: env.linkPreview }),
});
});
},
};
}