Messages

Every outbound message goes through client.messages.send(params). The params shape is a discriminated — common fields (to, optional replyTo, optional bizOpaqueCallbackData) plus exactly one content key.

Recipient format

to is a WhatsApp ID — the recipient’s phone number in international format. Either +15551234567 or 15551234567 is accepted.

Text

await client.messages.send({
  to: "+15551234567",
  text: "Hello!",
});

Pass a string for quick sends, or a for richer options:

await client.messages.send({
  to: "+15551234567",
  text: { body: "Check this out: https://photon.codes", previewUrl: true },
});

TextInput

Option	Type	Description
`body`	`string`
`previewUrl`	`boolean`

Media

Images, videos, audio, and documents all share the same shape. Send by referencing an uploaded id or a public link:

// Upload first, then reference by ID
const { mediaId } = await client.media.upload({
  file: await readFile("/path/to/photo.jpg"),
  mimeType: "image/jpeg",
});

await client.messages.send({
  to: "+15551234567",
  image: { id: mediaId, caption: "Here's the photo" },
});

// Or point at a hosted URL
await client.messages.send({
  to: "+15551234567",
  document: {
    link: "https://example.com/report.pdf",
    filename: "Q1-report.pdf",
  },
});

MediaInput

Option	Type	Description
`caption`	`string`
`filename`	`string`
`id`	`string`
`link`	`string`
`mimeType`	`string`

See Media for the upload flow and size limits.

Content types

Key	Accepts	Use for
`image`	`MediaInput`	JPEG, PNG
`video`	`MediaInput`	MP4, 3GP
`audio`	`MediaInput`	AAC, MP4 audio, AMR, MP3, OGG
`document`	`MediaInput`	Any file with a filename
`sticker`	`StickerInput` (id or link only)	WebP stickers

Location

await client.messages.send({
  to: "+15551234567",
  location: {
    latitude: 37.422,
    longitude: -122.084,
    name: "Googleplex",
    address: "1600 Amphitheatre Pkwy, Mountain View, CA",
  },
});

Contact cards

Send one or more vCard-style contact cards:

await client.messages.send({
  to: "+15551234567",
  contacts: [
    {
      name: { formattedName: "Alice Example", firstName: "Alice" },
      phones: [{ phone: "+15559876543", type: "MOBILE" }],
      emails: [{ email: "[email protected]" }],
      addresses: [],
      urls: [],
    },
  ],
});

Reactions

React to an incoming message by ID. Use an empty string for emoji to remove a reaction.

await client.messages.send({
  to: "+15551234567",
  reaction: {
    messageId: "wamid.HBgMMTU1NT...",
    emoji: "❤️",
  },
});

Replies

Thread a reply by setting replyTo:

await client.messages.send({
  to: event.message.from,
  replyTo: event.message.id,
  text: "Replying to your last message.",
});

Interactive and templates

Rich messages — buttons, lists, product carousels, flows, and pre-approved templates — have their own pages:

Interactive messages — buttons, lists, flows, product messages
Templates — template builder, parameters, carousels

Mark as read

Clear unread state on the recipient’s side:

await client.messages.markRead(event.message.id);

Send result

Every send() returns a — record messageId if you plan to reply to, react to, or track status for that message.

const { messageId, messageStatus } = await client.messages.send({
  to: "+15551234567",
  text: "Hello",
});

Abort signal

Every method accepts an optional RequestOptions with an AbortSignal:

const ctrl = new AbortController();
setTimeout(() => ctrl.abort(), 5000);

await client.messages.send(
  { to: "+15551234567", text: "Hello" },
  { signal: ctrl.signal },
);

Advanced Kits

Opensource Kits

Utilities

Recipient format

Text

Media

Content types

Location

Contact cards

Reactions

Replies

Interactive and templates

Mark as read

Send result

Abort signal

​Recipient format

​Text

​Media

​Content types

​Location

​Contact cards

​Reactions

​Replies

​Interactive and templates

​Mark as read

​Send result

​Abort signal

Recipient format

Text

Media

Content types

Location

Contact cards

Reactions

Replies

Interactive and templates

Mark as read

Send result

Abort signal