The (Missing) WhatsApp webhook API types
I am working on a project that involves integrating with the WhatsApp Business API, and I noticed that there are no official TypeScript types for the webhook API. The documentation while detailed, lacks (or i could not find) the type definitions that would make it easier to work with the API in a type-safe manner.
So, I decided to create my own minimal set of types to help me with the integration.
Reverse engineering the webhook payload
The process was pretty simple: 1 - In my app webhook endpoint, i saved the received payloads to a database 2 - From this sample i created the types using a JSON to TypeScript converter 3 - I then refined the types to make them more readable and easier to work with.
Some notes:
- The types are not exhaustive, they only cover the message types that I needed for my project i.e, 'messages' and 'message_template_status_update'.
- My go to JSON to Typescript converter was from Transform.Tools which is based on json_typegen. But is lacking creation of enum / union types from fields with repeatable values. Fortunately i found quicktype that supports this feature.
The types
export interface NotificationPayload { object: "whatsapp_business_account"; entry: Entry[]; } export interface Entry { id: string; changes: Change[]; } export type Change = MessagesChange | MessageTemplateStatusUpdateChange; export interface MessagesChange { field: "messages"; value: MessagesValue; } export interface MessageTemplateStatusUpdateChange { field: "message_template_status_update"; value: MessageTemplateStatusUpdateValue; } export interface MessageTemplateStatusUpdateValue { reason: string; message_template_name: string; event: string; message_template_language: string; message_template_id: number; } export interface MessagesValue { metadata: Metadata; messaging_product: MessagingProduct; statuses?: StatusElement[]; messages?: Message[]; contacts?: Contact[]; } export interface Contact { profile: Profile; wa_id: string; } export interface Profile { name: string; } export interface Message { from: string; id: string; text?: Text; type: string; timestamp: string; sticker?: Sticker; } export interface Sticker { sha256: string; mime_type: string; animated: boolean; id: string; } export interface Text { body: string; } export type MessagingProduct = "whatsapp"; export interface Metadata { phone_number_id: string; display_phone_number: string; } export interface StatusElement { biz_opaque_callback_data?: string; id: string; conversation?: Conversation; pricing?: Pricing; status: StatusEnum; timestamp: string; recipient_id: string; errors?: Error[]; } export interface Conversation { origin: Origin; id: string; expiration_timestamp?: string; } export interface Origin { type: Category; } export type Category = "marketing" | "utility"; export interface Error { code: number; title: string; message: string; error_data: ErrorData; } export interface ErrorData { details: string; } export interface Pricing { pricing_model: PricingModel; category: Category; billable: boolean; } export type PricingModel = "CBP"; export type StatusEnum = "delivered" | "failed" | "read" | "sent"; 
Top comments (0)