Reference
TypeScript Types
Comprehensive TypeScript definitions exported by wapi-cloud — every client method, message option, template definition, commerce model, and webhook event is fully typed.
All types below are exported directly from
wapi-cloud root. You can import any type with import type { ... } from "wapi-cloud".Core Client & Response Types
common.d.ts
export interface WhatsappResponse<T> {
data: T | null;
error: WhatsappApiError | null;
status: number;
statusText: string;
raw: unknown;
}
export interface WhatsappConfig {
accessToken: string;
phoneNumberId: string;
businessAccountId?: string;
appId?: string;
appSecret?: string;
businessId?: string;
apiVersion?: string;
baseUrl?: string;
fetch?: typeof fetch;
maxRetries?: number;
timeoutMs?: number;
onRequest?: (info: { method: string; url: string }) => void;
onResponse?: (info: { method: string; url: string; status: number }) => void;
}
export class WhatsappApiError extends Error {
code: number;
type: string;
subcode?: number;
fbtraceId?: string;
httpStatus: number;
isRetryable: boolean;
raw: unknown;
}
export interface PageInfo {
nextCursor?: string;
previousCursor?: string;
hasNext: boolean;
}
export interface PaginatedResult<T> {
items: T[];
pageInfo: PageInfo;
}Message Payload Types
messages.d.ts
export interface SendMessageResult {
messageId: string;
waId: string;
}
export interface TextMessageOptions {
body: string;
previewUrl?: boolean;
}
export interface MediaRef {
link?: string;
mediaId?: string;
caption?: string;
filename?: string;
}
export interface LocationMessageOptions {
latitude: number;
longitude: number;
name?: string;
address?: string;
}
export interface SendLocationRequestOptions {
body: string;
}
export interface ContactMessageEntry {
name: { formattedName: string; firstName?: string; lastName?: string };
phones?: { phone: string; type?: "HOME" | "WORK"; waId?: string }[];
emails?: { email: string; type?: "HOME" | "WORK" }[];
}
export interface InteractiveButton {
id: string;
title: string;
}
export interface InteractiveListRow {
id: string;
title: string;
description?: string;
}
export interface InteractiveListSection {
title?: string;
rows: InteractiveListRow[];
}
export type SendInteractiveOptions =
| { type: "button"; body: string; header?: string; footer?: string; buttons: InteractiveButton[] }
| { type: "list"; body: string; header?: string; footer?: string; buttonText: string; sections: InteractiveListSection[] }
| { type: "cta_url"; body: string; header?: string; footer?: string; displayText: string; url: string };
export interface SendFlowOptions {
flowId: string;
cta: string;
headerText?: string;
bodyText: string;
footerText?: string;
flowActionPayload?: { screen: string; data?: Record<string, unknown> };
}
export interface ReactionOptions {
messageId: string;
emoji: string;
}
export interface SendProductOptions {
catalogId: string;
productRetailerId: string;
body?: string;
footer?: string;
}
export interface ProductListSection {
title: string;
productRetailerIds: string[];
}
export interface SendProductListOptions {
catalogId: string;
header: string;
body: string;
footer?: string;
sections: ProductListSection[];
}
export interface SendCatalogOptions {
body: string;
footer?: string;
thumbnailProductRetailerId?: string;
}
export interface ProductCarouselCard {
catalogId: string;
productRetailerId: string;
}
export interface SendProductCarouselOptions {
body: string;
cards: ProductCarouselCard[];
}
export interface MediaCarouselCtaCard {
type: "cta_url";
headerType: "image" | "video";
headerMedia: MediaRef;
body?: string;
displayText: string;
url: string;
}
export interface MediaCarouselQuickReplyCard {
type: "quick_reply";
headerType: "image" | "video";
headerMedia: MediaRef;
body?: string;
buttons: InteractiveButton[];
}
export type MediaCarouselCard = MediaCarouselCtaCard | MediaCarouselQuickReplyCard;
export interface SendMediaCarouselOptions {
body: string;
cards: MediaCarouselCard[];
}Template & Component Types
templates.d.ts
export type TemplateCategory = "AUTHENTICATION" | "MARKETING" | "UTILITY";
export type TemplateStatus = "APPROVED" | "PENDING" | "REJECTED" | "PAUSED" | "DISABLED";
export interface TemplateButtonDefinition {
type: "QUICK_REPLY" | "URL" | "PHONE_NUMBER" | "SPM" | "FLOW";
text?: string;
url?: string;
phone_number?: string;
example?: string[];
flow_id?: string;
flow_name?: string;
flow_action?: "navigate" | "data_exchange";
navigate_screen?: string;
}
export interface TemplateComponentDefinition {
type: "HEADER" | "BODY" | "FOOTER" | "BUTTONS" | "CALL_PERMISSION_REQUEST";
format?: "TEXT" | "IMAGE" | "VIDEO" | "DOCUMENT" | "LOCATION" | "PRODUCT";
text?: string;
buttons?: TemplateButtonDefinition[];
example?: Record<string, unknown>;
}
export interface CarouselCardComponentDefinition {
type: "HEADER" | "BODY" | "BUTTONS";
format?: "IMAGE" | "VIDEO";
text?: string;
buttons?: TemplateButtonDefinition[];
example?: Record<string, unknown>;
}
export interface CarouselCardDefinition {
components: CarouselCardComponentDefinition[];
}
export interface CarouselComponentDefinition {
type: "CAROUSEL";
cards: CarouselCardDefinition[];
}
export type AnyTemplateComponentDefinition = TemplateComponentDefinition | CarouselComponentDefinition;
export interface WhatsappTemplate {
id: string;
name: string;
category: TemplateCategory;
language: string;
status: TemplateStatus;
components: AnyTemplateComponentDefinition[];
rejected_reason?: string;
}
export interface CreateTemplateInput {
name: string;
category: TemplateCategory;
language: string;
components: AnyTemplateComponentDefinition[];
parameter_format?: "positional" | "named";
}
export interface UpdateTemplateInput {
category?: TemplateCategory;
components?: AnyTemplateComponentDefinition[];
}
export interface ListTemplatesParams {
limit?: number;
after?: string;
before?: string;
status?: TemplateStatus;
name?: string;
}Commerce & Catalog Types
commerce.d.ts
export interface WhatsappCatalog {
id: string;
name: string;
product_count?: number;
vertical?: string;
}
export type ProductAvailability = "in stock" | "out of stock" | "preorder" | "available for order" | "discontinued";
export type ProductCondition = "new" | "refurbished" | "used";
export interface WhatsappProduct {
id: string;
retailer_id: string;
name: string;
description?: string;
price?: string;
currency?: string;
image_url?: string;
url?: string;
availability?: ProductAvailability;
condition?: ProductCondition;
brand?: string;
category?: string;
visibility?: "published" | "staging";
}
export interface CreateProductInput {
retailerId: string;
name: string;
description?: string;
price: number;
currency: string;
imageUrl: string;
url?: string;
availability?: ProductAvailability;
condition?: ProductCondition;
brand?: string;
category?: string;
}
export type UpdateProductInput = Partial<CreateProductInput>;
export interface CommerceSettings {
is_catalog_visible: boolean;
is_cart_enabled: boolean;
}
export interface UpdateCommerceSettingsInput {
isCatalogVisible?: boolean;
isCartEnabled?: boolean;
}Send options & helpers (1.1.0)
send-options.d.ts
export interface SendOptions {
phoneNumberId?: string;
replyToMessageId?: string;
recipientType?: "individual" | "group";
bizOpaqueCallbackData?: string; // max 512 chars
}
export interface SendMessageResult {
messageId: string;
waId: string; // empty when sent to a BSUID
userId?: string;
}
export interface SendMarketingTemplateOptions extends SendTemplateOptions {
productPolicy?: "CLOUD_API_FALLBACK" | "STRICT";
messageActivitySharing?: boolean;
}
/** True for BSUIDs such as "US.13491208655302741918". */
export function isBsuid(value: string): boolean;Calls & Groups types (1.1.0)
calls-groups.d.ts
export interface CallSession {
sdpType: "offer" | "answer";
sdp: string;
}
export interface CallPermissionState {
messaging_product: "whatsapp";
permission: { status: "no_permission" | "temporary" | "permanent"; expiration_time?: number };
actions: {
action_name: "send_call_permission_request" | "start_call";
can_perform_action: boolean;
limits: { time_period: string; max_allowed: number; current_usage: number; limit_expiration_time?: number }[];
}[];
}
export type GroupJoinApprovalMode = "approval_required" | "auto_approve";
export interface CreateGroupInput {
subject: string; // max 128 chars
description?: string; // max 2048 chars
joinApprovalMode?: GroupJoinApprovalMode;
}
export interface WhatsappGroup {
id: string;
subject?: string;
description?: string;
suspended?: boolean;
creation_timestamp?: string;
total_participant_count?: number;
participants?: { wa_id?: string; user_id?: string }[];
join_approval_mode?: GroupJoinApprovalMode;
}Webhooks & Event Types
webhooks.d.ts
export interface InboundMessageBase {
id: string;
/** Phone number (wa_id). Optional: users with a username may not expose one. */
from?: string;
/** Business-scoped user ID (BSUID) and its parent, when Meta includes them. */
userId?: string;
parentUserId?: string;
username?: string;
/** Best identifier for replying: the phone number if present, else the BSUID. */
sender: string;
profileName?: string;
timestamp: string;
phoneNumberId: string;
displayPhoneNumber: string;
context?: InboundMessageContext; // replies, forwards, product inquiries
referral?: Record<string, unknown>; // Click-to-WhatsApp ads
}
export type InteractiveReply =
| { kind: "button_reply"; id: string; title: string }
| { kind: "list_reply"; id: string; title: string; description?: string }
| { kind: "nfm_reply"; name?: string; body?: string; responseJson?: Record<string, unknown> }
| { kind: "unknown" };
export type InboundMessageEvent =
| (InboundMessageBase & { messageType: "text"; text: { body: string } })
| (InboundMessageBase & { messageType: "image"; image: { id: string; mimeType: string; caption?: string } })
| (InboundMessageBase & { messageType: "video"; video: { id: string; mimeType: string; caption?: string } })
| (InboundMessageBase & { messageType: "audio"; audio: { id: string; mimeType: string } })
| (InboundMessageBase & { messageType: "document"; document: { id: string; mimeType: string; filename?: string } })
| (InboundMessageBase & { messageType: "sticker"; sticker: { id: string; mimeType: string } })
| (InboundMessageBase & { messageType: "location"; location: { latitude: number; longitude: number; name?: string; address?: string } })
| (InboundMessageBase & { messageType: "contacts"; contacts: unknown[] })
| (InboundMessageBase & { messageType: "interactive"; interactive: { type: string; [key: string]: unknown }; reply: InteractiveReply })
| (InboundMessageBase & { messageType: "button"; button: { text: string; payload: string } })
| (InboundMessageBase & { messageType: "reaction"; reaction: { messageId: string; emoji: string } })
| (InboundMessageBase & { messageType: "order"; order: { catalogId: string; text?: string; productItems: { productRetailerId: string; quantity: number; itemPrice: number; currency: string }[] } })
| (InboundMessageBase & { messageType: "system"; system: Record<string, unknown> })
| (InboundMessageBase & { messageType: "request_welcome"; raw: unknown })
| (InboundMessageBase & { messageType: "unsupported"; errors?: { code: number; title: string; message?: string }[]; raw: unknown })
| (InboundMessageBase & { messageType: "unknown"; raw: unknown });
export interface MessageStatusEvent {
type: "status";
messageId: string;
status: "sent" | "delivered" | "read" | "failed" | "deleted" | "warning";
/** Optional: can be undefined when the recipient uses a username. */
recipientId?: string;
recipientUserId?: string;
recipientParentUserId?: string;
username?: string;
timestamp: string;
phoneNumberId: string;
bizOpaqueCallbackData?: string; // echoed from your send options
conversation?: { id: string; expirationTimestamp?: string; origin?: { type: string } };
pricing?: { billable?: boolean; pricingModel?: string; category?: string; type?: string };
errors?: { code: number; title: string; message?: string }[];
}
export interface TemplateStatusUpdateEvent {
type: "template_status_update";
messageTemplateId: string;
messageTemplateName: string;
messageTemplateLanguage: string;
event: string;
reason?: string;
}
export interface AccountAlertEvent {
type: "account_alert";
field?: string; // e.g. "phone_number_quality_update"
raw: unknown;
}
/** A webhook field the SDK has no typed event for yet. */
export interface UnknownFieldEvent {
type: "unknown_field";
field: string;
value: unknown;
raw: unknown;
}
export interface CallEvent {
type: "call";
phoneNumberId: string;
callId: string;
event?: string; // "connect" | "terminate" ...
direction?: "USER_INITIATED" | "BUSINESS_INITIATED" | string;
from?: string;
to?: string;
session?: { sdp_type: string; sdp: string }; // SDP offer for inbound calls
status?: string;
timestamp?: string;
bizOpaqueCallbackData?: string;
raw: unknown;
}
export interface GroupUpdateEvent {
type: "group_update";
field: string; // group_lifecycle_update | group_settings_update | ...
value: unknown;
raw: unknown;
}
export type WhatsappEvent =
| ({ type: "message" } & InboundMessageEvent)
| MessageStatusEvent
| TemplateStatusUpdateEvent
| AccountAlertEvent
| UnknownFieldEvent
| CallEvent
| GroupUpdateEvent;Account, Media & Flows Types
modules.d.ts
export interface MediaMetadata {
id: string;
url: string;
mime_type: string;
sha256: string;
file_size: number;
messaging_product: "whatsapp";
}
export interface ContactCheckResult {
input: string;
waId?: string;
status: "valid" | "invalid";
}
export interface WhatsappPhoneNumber {
id: string;
display_phone_number: string;
verified_name: string;
quality_rating: string;
code_verification_status: string;
}
export interface BusinessProfile {
about?: string;
address?: string;
description?: string;
email?: string;
profile_picture_url?: string;
websites?: string[];
vertical?: string;
}
export interface UpdateBusinessProfileInput {
about?: string;
address?: string;
description?: string;
email?: string;
websites?: string[];
vertical?: string;
profilePictureHandle?: string;
}
export interface WhatsappFlow {
id: string;
name: string;
status: "DRAFT" | "PUBLISHED" | "DEPRECATED";
categories: string[];
}
export type FlowCategory =
| "SIGN_UP"
| "SIGN_IN"
| "APPOINTMENT_BOOKING"
| "LEAD_GENERATION"
| "CONTACT_US"
| "CUSTOMER_SUPPORT"
| "SURVEY"
| "OTHER";
export interface CreateFlowInput {
name: string;
categories: FlowCategory[];
flowJson?: object | string;
cloneFlowId?: string;
endpointUri?: string;
}
export interface WhatsappQrCode {
code: string;
prefilled_message: string;
deep_link_url: string;
qr_image_url?: string;
}
export interface AnalyticsQuery {
start: Date | number;
end: Date | number;
granularity?: "HALF_HOUR" | "DAY" | "MONTH";
}
export interface ExchangedEmbeddedSignupToken {
accessToken: string;
tokenType: string;
}
export interface EmbeddedSignupLoginScriptOptions {
appId: string;
configId: string;
graphApiVersion?: string;
triggerElementId?: string;
}