Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

15.4 KB
Raw Blame
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
import {
  ValidateNested,
  IsString,
  IsNotEmpty,
  IsOptional,
  MaxLength,
  IsArray,
  ArrayMaxSize,
  IsBoolean,
  IsObject,
  Validate,
  Matches,
} from 'class-validator';
import { Type } from 'class-transformer';
import { IsMentionWidConstraint } from './is-mention-wid.validator';
import { ToStrictArray, ToStrictBoolean, ToStrictString } from '../../../common/utils/strict-boolean';
import { IsMediaUrl } from '../../../common/media/media-url';
import { stripBase64DataUri } from '../media-cap.util';

export const MENTIONS_DESCRIPTION =
  'WIDs to @mention (e.g. ["[email protected]"]). The text/caption must also contain the @<number> token.';

/**
 * Caps for a `mentions` array, exported because the field appears on every REST route whose engine
 * can carry it (send, reply, edit, template, bulk) and on the matching agent-tool schemas. Inline
 * literals repeated per site is how the two numbers would drift apart between endpoints that share
 * one documented contract, and the tool path needs them most: it calls the service directly, so the
 * ValidationPipe never runs and the zod schema is the only cap there is.
 */
export const MENTIONS_MAX = 1024;
export const MENTION_WID_MAX_LENGTH = 64;

/**
 * Caps for a custom link preview, exported for the same reason as the mentions pair above: the
 * agent-tool schema restates nothing, and that path never reaches the ValidationPipe.
 */
export const CUSTOM_PREVIEW_URL_MAX_LENGTH = 2048;
export const CUSTOM_PREVIEW_TITLE_MAX_LENGTH = 256;
export const CUSTOM_PREVIEW_DESCRIPTION_MAX_LENGTH = 1024;

// Single source of truth for the text-body cap, shared with the agent-tool input schemas
// (src/core/agent-tools/tools/message.tools.ts) so MCP and REST enforce the same limit.
export const MESSAGE_TEXT_MAX_LENGTH = 4096;

/**
 * Caps for the ids a caller chooses: a chat id and a bulk batch id. Both end up in a btree index
 * (the message chat indexes, UNIQUE(sessionId, batchId)), and PostgreSQL refuses an index entry past
 * about 2.7 KB with an error the client sees as a 500, where SQLite takes any length. A WhatsApp JID is
 * well under 100 characters, so 255 leaves room for every real id and matches the idempotency key cap.
 */
export const CHAT_ID_MAX_LENGTH = 255;
export const BATCH_ID_MAX_LENGTH = 255;

/**
 * The structural check on a chat id for the chat routes that also verify its form: localpart@host with
 * no whitespace, engine-neutral so another engine's JID scheme (Baileys' `@s.whatsapp.net`) passes and
 * the adapter normalises further. Exported so the MCP tools that reach the same operations hold the
 * rule too: they call the service directly, and a restated pattern is how the two drift apart.
 */
export const CHAT_JID_PATTERN = /^[^\s@]+@[^\s@]+$/;
export const CHAT_JID_MESSAGE = 'chatId must be a valid chat JID in the form localpart@host';

// The cap on a prompt choice's id. It must equal BUTTON_TEXT_MAX_LENGTH in the Baileys message
// mapper, which refuses to offer any inbound choice whose id is longer, so an id past this bound
// can never name a choice that exists. Validating it against the text cap instead accepted such a
// request and let the engine answer a confusing "unknown button" a few layers later.
export const BUTTON_ID_MAX_LENGTH = 256;

/**
 * Shared wording for the quoted-send field (issue #1271). One constant rather than five copies so
 * the two engine caveats — different id dialects, and Baileys' store requirement — cannot drift
 * apart between the endpoints that all accept the same field.
 */
export const QUOTED_MESSAGE_ID_DESCRIPTION =
  'Quote an earlier message, turning this send into a reply. The id is engine-specific: ' +
  'whatsapp-web.js matches the serialized message id, Baileys matches the raw message key id and ' +
  'can only quote a message it has already stored. An id that cannot be resolved fails the send ' +
  'rather than delivering it unquoted.';
export const QUOTED_MESSAGE_ID_EXAMPLE = '[email protected]_3EB0ABCD';

export class CustomLinkPreviewDto {
  @ApiProperty({
    description: 'The URL as it appears in the message text — WhatsApp anchors the preview to it.',
    example: 'https://example.com/launch',
    maxLength: CUSTOM_PREVIEW_URL_MAX_LENGTH,
  })
  @ToStrictString()
  @IsString()
  @IsNotEmpty()
  @MaxLength(CUSTOM_PREVIEW_URL_MAX_LENGTH)
  url!: string;

  @ApiProperty({
    description: 'Required: WhatsApp will not render a preview without a title.',
    example: 'We just launched',
    maxLength: 256,
  })
  @ToStrictString()
  @IsString()
  @IsNotEmpty()
  @MaxLength(CUSTOM_PREVIEW_TITLE_MAX_LENGTH)
  title!: string;

  @ApiPropertyOptional({ description: 'Preview description', example: 'Read the announcement.', maxLength: 1024 })
  @IsOptional()
  @ToStrictString()
  @IsString()
  @MaxLength(CUSTOM_PREVIEW_DESCRIPTION_MAX_LENGTH)
  description?: string;
}

export class SendTextMessageDto {
  @ApiProperty({
    description: 'WhatsApp chat ID ([email protected] for individual, [email protected] for groups)',
    example: '[email protected]',
    maxLength: CHAT_ID_MAX_LENGTH,
  })
  @ToStrictString()
  @IsString()
  @IsNotEmpty()
  @MaxLength(CHAT_ID_MAX_LENGTH)
  @Matches(CHAT_JID_PATTERN, { message: CHAT_JID_MESSAGE })
  chatId!: string;

  @ApiProperty({
    description: 'Text message content',
    example: 'Hello from OpenWA!',
    maxLength: MESSAGE_TEXT_MAX_LENGTH,
  })
  @ToStrictString()
  @IsString()
  @IsNotEmpty()
  @MaxLength(MESSAGE_TEXT_MAX_LENGTH)
  text!: string;

  @ApiPropertyOptional({
    description: MENTIONS_DESCRIPTION,
    example: ['[email protected]'],
    type: [String],
    maxItems: MENTIONS_MAX,
    items: { type: 'string', maxLength: MENTION_WID_MAX_LENGTH },
  })
  @IsOptional()
  @ToStrictArray()
  @IsArray()
  @ArrayMaxSize(MENTIONS_MAX)
  @IsString({ each: true })
  @MaxLength(MENTION_WID_MAX_LENGTH, { each: true })
  @Validate(IsMentionWidConstraint, { each: true })
  mentions?: string[];

  @ApiPropertyOptional({
    description:
      'Controls the URL preview, and the engines differ. On whatsapp-web.js WhatsApp Web builds one ' +
      'by default and `false` suppresses it. On Baileys previews are OPT-IN: `true` asks the gateway ' +
      'to fetch the page and attach one, while unset or `false` sends none — generating a preview is ' +
      'a blocking outbound fetch per URL in the text, so it is never done unless asked for.',
    example: false,
  })
  // Implicit conversion turns EVERY non-empty string into true, so an unguarded `false` sent as a
  // string would request a preview instead of suppressing one — the opposite of what was asked.
  @ToStrictBoolean()
  @IsOptional()
  @IsBoolean()
  linkPreview?: boolean;

  @ApiPropertyOptional({
    type: CustomLinkPreviewDto,
    description:
      'Attach a preview you supply yourself, instead of one fetched from the URL. Nothing is ' +
      'fetched for these, so a preview can be attached even for a URL this server cannot reach. ' +
      '**Baileys only** — whatsapp-web.js takes a boolean and answers `501`. Cannot be combined ' +
      'with `linkPreview: false`, which asks for the opposite.',
  })
  @IsOptional()
  @IsObject()
  @ValidateNested()
  @Type(() => CustomLinkPreviewDto)
  customLinkPreview?: CustomLinkPreviewDto;

  @ApiPropertyOptional({
    description: QUOTED_MESSAGE_ID_DESCRIPTION,
    example: QUOTED_MESSAGE_ID_EXAMPLE,
  })
  @IsOptional()
  @ToStrictString()
  @IsString()
  @IsNotEmpty()
  quotedMessageId?: string;
}

/**
 * Request-body examples for `POST send-text`, applied with `@ApiBody` on the controller.
 *
 * Swagger UI does NOT pre-fill "Try it out" from the required properties — its sampler walks EVERY
 * property in the schema, skipping only `deprecated`/`readOnly`/`writeOnly`. So an optional field is
 * always present in the generated body; a property's `example` only decides the VALUE it is given,
 * never whether it appears. Left to the sampler this endpoint offers `linkPreview: false` together
 * with a `customLinkPreview` object — the one combination `MessageService.sendText` rejects outright
 * — so every Try-it click returned `400 linkPreview: false cannot be combined with customLinkPreview`
 * without the caller having typed anything (#1068). An explicit example overrides the sampler
 * entirely, which is the only way to stop an optional property from reaching the default body.
 *
 * Keep every entry here a payload the API actually accepts: `send-message.dto.spec.ts` validates each
 * one against the DTO and asserts it does not trip that guard, so a future field cannot silently
 * reintroduce an unusable default.
 */
export const SEND_TEXT_BODY_EXAMPLES = {
  minimal: {
    summary: 'Plain text message',
    value: { chatId: '[email protected]', text: 'Hello from OpenWA!' },
  },
  withMentions: {
    summary: 'Group message with an @mention (the text must carry the @<number> token)',
    value: { chatId: '[email protected]', text: 'Hello @62811', mentions: ['[email protected]'] },
  },
};

export class SendMediaMessageDto {
  @ApiProperty({
    description: 'WhatsApp chat ID',
    example: '[email protected]',
    maxLength: CHAT_ID_MAX_LENGTH,
  })
  @ToStrictString()
  @IsString()
  @IsNotEmpty()
  @MaxLength(CHAT_ID_MAX_LENGTH)
  @Matches(CHAT_JID_PATTERN, { message: CHAT_JID_MESSAGE })
  chatId!: string;

  @ApiPropertyOptional({
    description: 'Media URL (http/https)',
    example: 'https://example.com/image.jpg',
  })
  @IsOptional()
  // base64 wins when it holds data, so a url next to it is not fetched and not checked; a base64 that
  // is only a data-URI prefix strips to nothing, and then the url is what gets sent.
  @IsMediaUrl<SendMediaMessageDto>({ ignoreWhen: o => !!stripBase64DataUri(o.base64) })
  url?: string;

  @ApiPropertyOptional({
    description: 'Base64 encoded media data',
  })
  @IsOptional()
  @ToStrictString()
  @IsString()
  base64?: string;

  @ApiPropertyOptional({
    description: 'Media MIME type (required when using base64)',
    example: 'image/jpeg',
  })
  @IsOptional()
  @ToStrictString()
  @IsString()
  mimetype?: string;

  @ApiPropertyOptional({
    description:
      "Filename for the media. Only rendered on document sends — defaults to 'file' when omitted (a URL-based document send on whatsapp-web.js first derives the URL basename)",
    example: 'image.jpg',
    maxLength: 255,
  })
  @IsOptional()
  @ToStrictString()
  @IsString()
  @MaxLength(255)
  filename?: string;

  @ApiPropertyOptional({
    description: 'Caption for the media',
    example: 'Check out this image!',
    maxLength: 1024,
  })
  @IsOptional()
  @ToStrictString()
  @IsString()
  @MaxLength(1024)
  caption?: string;

  @ApiPropertyOptional({
    description: MENTIONS_DESCRIPTION,
    example: ['[email protected]'],
    type: [String],
    maxItems: MENTIONS_MAX,
    items: { type: 'string', maxLength: MENTION_WID_MAX_LENGTH },
  })
  @IsOptional()
  @ToStrictArray()
  @IsArray()
  @ArrayMaxSize(MENTIONS_MAX)
  @IsString({ each: true })
  @MaxLength(MENTION_WID_MAX_LENGTH, { each: true })
  @Validate(IsMentionWidConstraint, { each: true })
  mentions?: string[];

  @ApiPropertyOptional({
    description: QUOTED_MESSAGE_ID_DESCRIPTION,
    example: QUOTED_MESSAGE_ID_EXAMPLE,
  })
  @IsOptional()
  @ToStrictString()
  @IsString()
  @IsNotEmpty()
  quotedMessageId?: string;
}

/**
 * Request-body examples for the media send routes, applied with `@ApiBody` on the controller.
 *
 * Same reason as the text route: Swagger UI's sampler emits EVERY property, so the generated body
 * carried `url` AND `base64` together. `base64` has no `example`, so it arrived as the literal string
 * `"string"` — and `MessageService.buildMediaInput` deliberately lets base64 win over url (a stale
 * example url must never be fetched in place of real bytes), so pressing Execute uploaded four
 * characters of garbage instead of the example image. An explicit example is the only way to keep an
 * optional property out of the body.
 *
 * Only the URL form is offered, and every entry must be submittable as-is: a base64 example would
 * need real bytes pasted in, which is the "click Execute, get an error" trap this exists to remove.
 * `base64` and its `mimetype` requirement stay documented in the schema.
 */
const mediaBodyExample = (url: string, extra: Record<string, unknown> = {}) => ({
  fromUrl: {
    summary: 'Fetch the media from a URL',
    value: { chatId: '[email protected]', url, ...extra },
  },
});

export const SEND_IMAGE_BODY_EXAMPLES = mediaBodyExample('https://example.com/image.jpg', {
  caption: 'Check out this image!',
});
export const SEND_VIDEO_BODY_EXAMPLES = mediaBodyExample('https://example.com/video.mp4');
export const SEND_AUDIO_BODY_EXAMPLES = mediaBodyExample('https://example.com/audio.ogg', { ptt: true });
export const SEND_DOCUMENT_BODY_EXAMPLES = mediaBodyExample('https://example.com/report.pdf', {
  filename: 'report.pdf',
});
export const SEND_STICKER_BODY_EXAMPLES = mediaBodyExample('https://example.com/sticker.webp');

/**
 * Request-body examples for the location, contact and poll routes.
 *
 * These three had no `@ApiBody` and were left to the schema sampler, which was harmless while every
 * optional property was self-contained. `quotedMessageId` is not: the sampler emits EVERY property,
 * so a Try-it body would carry a made-up message id, and the send path refuses an id it cannot
 * resolve rather than delivering the message unquoted — turning every unedited Execute on these
 * three routes into an error. Same failure #1068 fixed for the text and media routes, arriving by a
 * different door, so the same remedy applies: pin an example that is submittable as-is.
 */
export const SEND_LOCATION_BODY_EXAMPLES = {
  minimal: {
    summary: 'Share a location',
    value: { chatId: '[email protected]', latitude: -6.2088, longitude: 106.8456, description: 'Jakarta' },
  },
};
export const SEND_CONTACT_BODY_EXAMPLES = {
  minimal: {
    summary: 'Share a contact card',
    value: { chatId: '[email protected]', contactName: 'Alice', contactNumber: '628999888777' },
  },
};
export const SEND_POLL_BODY_EXAMPLES = {
  minimal: {
    summary: 'Ask a single-choice poll',
    value: { chatId: '[email protected]', name: 'Where should we meet?', options: ['Park', 'Beach'] },
  },
};

export class SendAudioMessageDto extends SendMediaMessageDto {
  @ApiPropertyOptional({
    description:
      'Send as a WhatsApp voice note (PTT — mic bubble + waveform). Provide audio/ogg; codecs=opus ' +
      'bytes for reliable playback; when the mimetype is omitted it defaults to that for voice notes. ' +
      'Expects a JSON boolean. Default false = plain audio file. Only valid on send-audio.',
  })
  @ToStrictBoolean()
  @IsOptional()
  @IsBoolean()
  ptt?: boolean;
}

export class MessageResponseDto {
  @ApiProperty({
    description:
      'The message id, assigned when the gateway accepts the message for sending. A 201 here means the ' +
      'message was handed to the WhatsApp session; it does not confirm delivery. Baileys checks phone ' +
      'destinations without a LID mapping and rejects a number reported as unregistered with 400. An ' +
      'unanswered lookup returns 503 before sending. Known LIDs skip the number check. Track delivery ' +
      'through the message status (sent, delivered, read, or failed). A message resting at sent can ' +
      'also belong to a registered recipient whose device is offline.',
    example: '[email protected]_3EB0123456789',
  })
  messageId!: string;

  @ApiProperty({
    description: 'Unix timestamp (seconds) at which the gateway accepted the message for sending.',
    example: 1706868000,
  })
  timestamp!: number;
}