Messages

// By BSUID (the phone number never arrived)
await client.messages.sendText({
  phoneNumberId: '123',
  recipient: 'US.13491208655302741918',
  body: 'Hola desde Kapso!'
});

// Both identifiers
await client.messages.sendText({
  phoneNumberId: '123',
  to: '56961567267',
  recipient: 'US.13491208655302741918',
  body: 'Hola desde Kapso!'
});

await client.messages.sendText({
  phoneNumberId: '123',
  to: '56961567267',
  body: 'Hola desde Kapso!',
  // Optional: disable URL previews
  previewUrl: false
});

await client.messages.sendImage({
  phoneNumberId: '123',
  to: '56961567267',
  image: {
    link: 'https://example.com/photo.jpg',
    caption: 'Check this out!'
  }
});

// Or with uploaded media ID
await client.messages.sendImage({
  phoneNumberId: '123',
  to: '56961567267',
  image: { id: 'MEDIA_ID', caption: 'Uploaded photo' }
});

await client.messages.sendVideo({
  phoneNumberId: '123',
  to: '56961567267',
  video: {
    link: 'https://example.com/demo.mp4',
    caption: 'Product demo'
  }
});

// Basic audio message
await client.messages.sendAudio({
  phoneNumberId: '123',
  to: '56961567267',
  audio: {
    link: 'https://example.com/ringtone.mp3'
  }
});

// Voice note with transcription support (.ogg with OPUS codec)
await client.messages.sendAudio({
  phoneNumberId: '123',
  to: '56961567267',
  audio: {
    id: 'MEDIA_ID',
    voice: true
  }
});

await client.messages.sendDocument({
  phoneNumberId: '123',
  to: '56961567267',
  document: {
    link: 'https://example.com/report.pdf',
    filename: 'report.pdf',
    caption: 'Q4 Report'
  }
});

await client.messages.sendSticker({
  phoneNumberId: '123',
  to: '56961567267',
  sticker: {
    id: 'STICKER_MEDIA_ID'
  }
});

await client.messages.sendLocation({
  phoneNumberId: '123',
  to: '56961567267',
  location: {
    latitude: -33.4489,
    longitude: -70.6693,
    name: 'Santiago',
    address: 'CL'
  }
});

await client.messages.sendContacts({
  phoneNumberId: '123',
  to: '56961567267',
  contacts: [
    {
      name: { formatted_name: 'Ada Lovelace' },
      org: { company: 'Analytical Engines' },
      phones: [{ phone: '+44123456789', type: 'WORK' }]
    }
  ]
});

await client.messages.sendReaction({
  phoneNumberId: '123',
  to: '56961567267',
  reaction: { messageId: 'wamid.SOME_ID', emoji: '👍' }
});

await client.messages.markRead({
  phoneNumberId: '123',
  messageId: 'wamid.SOME_ID'
});

// With typing indicator (dismissed on send or after ~25s)
await client.messages.markRead({
  phoneNumberId: '123',
  messageId: 'wamid.SOME_ID',
  typingIndicator: { type: 'text' }
});

import { buildKapsoFields } from '@kapso/whatsapp-cloud-api';

// Query by time and direction
const page = await client.messages.query({
  phoneNumberId: '123',
  direction: 'inbound',
  since: '2025-01-01T00:00:00Z',
  limit: 50,
  fields: buildKapsoFields() // include Kapso extras (direction, flow_response, media_data, ...)
});

// List messages for a single conversation
const convMessages = await client.messages.listByConversation({
  phoneNumberId: '123',
  conversationId: 'conv-123',
  limit: 25,
  fields: buildKapsoFields(['media_url', 'flow_response']) // request only the fields you need
});

// Graph-style cursors are exposed under page.paging.cursors.before and page.paging.cursors.after
const nextCursor = page.paging.cursors.after;

> Tip: Include `media_url` to render images/documents directly when Kapso has attached them. See [Kapso Extensions](/docs/whatsapp/typescript-sdk/kapso-extensions) for the full list.