@jackiemacklein/nettz-utils
Version:
Serviços de imagem, e-mail, códigos de barras, utilitários numéricos e componentes React para apps Node.js com TypeScript
207 lines (206 loc) • 7.71 kB
TypeScript
/**
* @author Jackiê Macklein
* @company Onside tecnologia/Nettz
* @copyright Todos direitos reservados.
* @description Tipos para WhatsApp Cloud API (Graph API).
* Referência: https://developers.facebook.com/documentation/business-messaging/whatsapp/about-the-platform
*/
/** Host padrão da Graph API. */
export declare const WHATSAPP_GRAPH_DEFAULT_BASE_URL = "https://graph.facebook.com";
/**
* Versão da Graph API usada na URL (ex.: v21.0).
* Ajuste conforme a versão habilitada no seu app.
*/
export declare const WHATSAPP_GRAPH_DEFAULT_VERSION = "v21.0";
export interface WhatsAppCloudClientConfig {
/** Token de acesso OAuth (ex.: token de sistema ou de página, com permissões para o número). */
accessToken: string;
/** ID do número comercial do WhatsApp (phone number id), não o MSISDN. */
phoneNumberId: string;
/** Base da Graph API, sem barra final. @default https://graph.facebook.com */
graphBaseUrl?: string;
/** Segmento de versão na URL, ex. `v21.0`. @default v21.0 */
graphApiVersion?: string;
/** Timeout em ms por requisição. @default 30000 */
timeoutMs?: number;
fetchImpl?: typeof fetch;
}
/** Opções comuns: resposta a uma mensagem (context.message_id). */
export interface WhatsAppReplyContextOptions {
replyToMessageId?: string;
}
/** Text — https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/text-messages */
export interface WhatsAppSendTextMessageOptions extends WhatsAppReplyContextOptions {
to: string;
body: string;
previewUrl?: boolean;
}
/** Template — https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/template-messages */
export interface WhatsAppSendTemplateMessageOptions extends WhatsAppReplyContextOptions {
to: string;
templateName: string;
languageCode: string;
components?: unknown[];
}
/** Address (interactive) — https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/address-messages */
export interface WhatsAppSendAddressMessageOptions extends WhatsAppReplyContextOptions {
to: string;
/** Código do país ISO (ex.: IN). Obrigatório na API. */
country: string;
bodyText: string;
/** Mescla em `action.parameters` (ex.: values, saved_addresses, validation_errors). */
actionParameters?: Record<string, unknown>;
headerText?: string;
footerText?: string;
}
/** Audio — https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/audio-messages */
export interface WhatsAppSendAudioMessageOptions extends WhatsAppReplyContextOptions {
to: string;
id?: string;
link?: string;
voice?: boolean;
}
/** Contacts — https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/contacts-messages */
export interface WhatsAppContactName {
formatted_name: string;
first_name?: string;
last_name?: string;
middle_name?: string;
suffix?: string;
prefix?: string;
}
export interface WhatsAppContactPhone {
phone?: string;
type?: string;
wa_id?: string;
}
export interface WhatsAppContactEntry {
name: WhatsAppContactName;
addresses?: unknown[];
birthday?: string;
emails?: unknown[];
org?: Record<string, unknown>;
phones?: WhatsAppContactPhone[];
urls?: unknown[];
}
export interface WhatsAppSendContactsMessageOptions extends WhatsAppReplyContextOptions {
to: string;
contacts: WhatsAppContactEntry[];
}
/** Document — https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/document-messages */
export interface WhatsAppSendDocumentMessageOptions extends WhatsAppReplyContextOptions {
to: string;
id?: string;
link?: string;
caption?: string;
filename?: string;
}
/** Image — https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/image-messages */
export interface WhatsAppSendImageMessageOptions extends WhatsAppReplyContextOptions {
to: string;
id?: string;
link?: string;
caption?: string;
}
/** Video — https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/video-messages */
export interface WhatsAppSendVideoMessageOptions extends WhatsAppReplyContextOptions {
to: string;
id?: string;
link?: string;
caption?: string;
}
/** Location — https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/location-messages */
export interface WhatsAppSendLocationMessageOptions extends WhatsAppReplyContextOptions {
to: string;
latitude: string | number;
longitude: string | number;
name?: string;
address?: string;
}
/** Interactive header (reply buttons / CTA URL). */
export type WhatsAppInteractiveMessageHeader = {
type: "text";
text: string;
} | {
type: "image";
image: {
id?: string;
link?: string;
};
} | {
type: "video";
video: {
id?: string;
link?: string;
};
} | {
type: "document";
document: {
id?: string;
link?: string;
filename?: string;
};
};
/** CTA URL — https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/interactive-cta-url-messages */
export interface WhatsAppSendInteractiveCtaUrlMessageOptions extends WhatsAppReplyContextOptions {
to: string;
bodyText: string;
buttonDisplayText: string;
buttonUrl: string;
header?: WhatsAppInteractiveMessageHeader;
footerText?: string;
}
/** List row — https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/interactive-list-messages */
export interface WhatsAppInteractiveListRow {
id: string;
title: string;
description?: string;
}
export interface WhatsAppInteractiveListSection {
title: string;
rows: WhatsAppInteractiveListRow[];
}
/** List — https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/interactive-list-messages */
export interface WhatsAppSendInteractiveListMessageOptions extends WhatsAppReplyContextOptions {
to: string;
bodyText: string;
/** Texto do botão que abre a lista (máx. 20 caracteres na doc). */
actionButtonText: string;
sections: WhatsAppInteractiveListSection[];
headerText?: string;
footerText?: string;
}
/** Reply buttons — https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/interactive-reply-buttons-messages */
export interface WhatsAppInteractiveReplyButton {
id: string;
title: string;
}
export interface WhatsAppSendInteractiveReplyButtonsMessageOptions extends WhatsAppReplyContextOptions {
to: string;
bodyText: string;
/** Até 3 botões. */
buttons: WhatsAppInteractiveReplyButton[];
header?: WhatsAppInteractiveMessageHeader;
footerText?: string;
}
/** Media carousel — https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/interactive-media-carousel-messages */
export interface WhatsAppSendInteractiveMediaCarouselMessageOptions extends WhatsAppReplyContextOptions {
to: string;
mainBodyText: string;
cards: unknown[];
}
/** @deprecated use WhatsAppSendTextMessageOptions */
export type WhatsAppSendTextOptions = WhatsAppSendTextMessageOptions;
/** @deprecated use WhatsAppSendTemplateMessageOptions */
export type WhatsAppSendTemplateOptions = WhatsAppSendTemplateMessageOptions;
/** Resposta típica de envio de mensagem (Cloud API). */
export interface WhatsAppSendMessageResponse {
messaging_product: string;
contacts?: {
input: string;
wa_id: string;
}[];
messages?: {
id: string;
}[];
}