Raw proto sends

For content types WhatsApp supports but zapo doesn’t wrap in a typed builder yet, client.message.send also accepts a raw Proto.IMessage. Fill the field that names the content type — locationMessage, contactMessage, contactsArrayMessage, interactiveMessage, and so on — and the library encodes it verbatim. Kinds that already have a typed builder — polls, reactions, edits, revokes, pins, keep-in-chat, view-once wrapping, and quotes / mentions / link previews — belong in Sending messages and Interactive messages. This page is for the raw-only kinds. The full set of recognized Proto.IMessage fields (location, live location, contacts, group invite, product, order, …) is listed in the message types reference. Some examples below use enum values from the proto namespace:

import { proto } from 'zapo-js'

How the stanza type is resolved

Whatever field you fill, zapo classifies the message before it goes on the wire: a <message> stanza carries a type (text or media), and a media stanza must also carry a mediatype. The server silently drops a media stanza with no mediatype — the send acks fine and nothing ever arrives — so a content type that falls through to the media default without one is invisibly lost. Two details matter when you hand-build a payload:

Wrappers are descended into. deviceSentMessage, botForwardedMessage, groupStatusMessageV2 and groupStatusMessage all carry the real message in .message, so the inner content decides the type. A forwarded image stays media with its mediatype; an image status wrapped in groupStatusMessageV2 no longer goes out as type="media" with no mediatype — a pairing no real client sends.
The AI rich-response family classifies as text. richResponseMessage and a bare botForwardedMessage wrapper resolve to type="text". Before 1.9.0 they fell through to the media default and never delivered.

Locations

await client.message.send(jid, {
  locationMessage: {
    degreesLatitude: -23.5613,
    degreesLongitude: -46.6565,
    name: 'Av. Paulista',
    address: 'São Paulo, BR'
  }
})

name and address are optional. For a live-location message, use the liveLocationMessage field instead — it carries movement metadata (accuracyInMeters, speedInMps, sequenceNumber).

await client.message.send(jid, {
  liveLocationMessage: {
    degreesLatitude: -23.5505,
    degreesLongitude: -46.6333,
    accuracyInMeters: 50,
    speedInMps: 0,
    caption: 'On my way',
    sequenceNumber: 1
  }
})

Contacts

A single contact card is a contactMessage with a vCard string:

const vcard = [
  'BEGIN:VCARD',
  'VERSION:3.0',
  'FN:Jeff Singh',
  'TEL;type=CELL;type=VOICE;waid=5511999999999:+55 11 99999-9999',
  'END:VCARD'
].join('\n')

await client.message.send(jid, {
  contactMessage: { displayName: 'Jeff', vcard }
})

The waid=<digits> parameter on the TEL line is what lets the WhatsApp client link the card back to a WhatsApp account — use the recipient’s E.164 phone number without the +. For multiple cards at once, use contactsArrayMessage:

await client.message.send(jid, {
  contactsArrayMessage: {
    displayName: '2 contacts',
    contacts: [
      { displayName: 'Jeff', vcard },
      { displayName: 'Jane', vcard: janeVcard }
    ]
  }
})

Group invite

await client.message.send(jid, {
  groupInviteMessage: {
    groupJid: '123456789-987654@g.us',
    inviteCode: 'AbCdEf123',
    inviteExpiration: Math.floor(Date.now() / 1000) + 86_400,
    groupName: 'My group',
    caption: 'Join us!'
  }
})

Buttons

Up to three quick-reply buttons. The header is a oneof — pick text, image, video, location, or document (pre-uploaded for media):

await client.message.send(jid, {
  buttonsMessage: {
    contentText: 'Order placed — what next?',
    footerText: 'Reply within 24h',
    headerType: proto.Message.ButtonsMessage.HeaderType.TEXT,
    text: 'Order #1234',
    buttons: [
      {
        buttonId: 'track',
        buttonText: { displayText: 'Track' },
        type: proto.Message.ButtonsMessage.Button.Type.RESPONSE
      },
      {
        buttonId: 'cancel',
        buttonText: { displayText: 'Cancel' },
        type: proto.Message.ButtonsMessage.Button.Type.RESPONSE
      }
    ]
  }
})

A single-select list of rows grouped into sections:

A list to a group goes out with a different stanza shape than the same list in a direct chat: the group takes it only when type=media, mediatype=list and the <biz><list> companion node travel together, while a direct send keeps the flat text shape. zapo picks the right one for you. Before 1.10.0 a group list was nacked with 479 while the identical message went through 1:1.

await client.message.send(jid, {
  listMessage: {
    title: 'Menu',
    description: 'Choose an item',
    buttonText: 'View menu',
    footerText: 'Open 9–18',
    listType: proto.Message.ListMessage.ListType.SINGLE_SELECT,
    sections: [
      {
        title: 'Pizzas',
        rows: [
          { rowId: 'pizza-margherita', title: 'Margherita', description: 'Tomato, mozzarella, basil' },
          { rowId: 'pizza-pepperoni',  title: 'Pepperoni',  description: 'Tomato, cheese, pepperoni' }
        ]
      },
      {
        title: 'Drinks',
        rows: [{ rowId: 'drink-cola', title: 'Cola' }]
      }
    ]
  }
})

Interactive native flow (cta_url)

The modern interactive surface — buttons whose params are JSON-encoded ad-hoc payloads:

await client.message.send(jid, {
  interactiveMessage: {
    body: { text: 'Tap below to open the form' },
    footer: { text: 'Powered by your bot' },
    nativeFlowMessage: {
      buttons: [
        {
          name: 'cta_url',
          buttonParamsJson: JSON.stringify({
            display_text: 'Open form',
            url: 'https://example.com/form'
          })
        }
      ],
      messageVersion: 1
    }
  }
})

This is the same wire shape as the PIX / review-and-pay cards in Payments below — only the button name and buttonParamsJson differ.

Product

Send a catalog product. The inner productImage must already be uploaded:

await client.message.send(jid, {
  productMessage: {
    businessOwnerJid: '5511999999999@s.whatsapp.net',
    body: 'Take a look at this',
    footer: 'In stock',
    product: {
      productId: '12345',
      title: 'Hat',
      description: 'One size, adjustable',
      currencyCode: 'BRL',
      priceAmount1000: 49_900, // 49.90 BRL — price × 1000
      retailerId: 'sku-001',
      url: 'https://example.com/p/12345',
      productImage: { /* pre-uploaded image fields */ }
    }
  }
})

Order

Order confirmation / inquiry:

await client.message.send(jid, {
  orderMessage: {
    orderId: 'ord-abc',
    orderTitle: 'Sample order',
    itemCount: 3,
    status: proto.Message.OrderMessage.OrderStatus.INQUIRY,   // or ACCEPTED / DECLINED
    surface: proto.Message.OrderMessage.OrderSurface.CATALOG,
    sellerJid: '5511888888888@s.whatsapp.net',
    totalAmount1000: 149_700, // 149.70 BRL — total × 1000
    totalCurrencyCode: 'BRL',
    message: 'Order details'
  }
})

Invite a contact to co-admin one of your newsletters:

await client.message.send(contactJid, {
  newsletterAdminInviteMessage: {
    newsletterJid: '120363xxxxxxxxxxxxxx@newsletter',
    newsletterName: 'My Newsletter',
    caption: 'Become a co-admin',
    inviteExpiration: Math.floor(Date.now() / 1000) + 7 * 86_400
  }
})

Toggle disappearing messages (ephemeral setting)

Chat-wide toggle for disappearing messages — distinct from the per-message expirationSeconds send option (one message) and the ephemeralMessage wrapper (one message inheriting the chat timer). This one flips the timer for the whole chat.

await client.message.send(jid, {
  protocolMessage: {
    type: proto.Message.ProtocolMessage.Type.EPHEMERAL_SETTING,
    ephemeralExpiration: 7 * 24 * 3600 // seconds; 0 disables
  }
})

Request a phone number

await client.message.send(jid, { requestPhoneNumberMessage: {} })

Payments (PIX & review-and-pay)

Send WhatsApp Business payment cards — static PIX (payment_info) and order checkout (review_and_pay) — as raw interactiveMessage / nativeFlowMessage payloads through client.message.send. There is no typed builder for them yet, so build the shape yourself the same way as the locations/contacts cards above. The library relays the interactive native-flow buttons; the WhatsApp clients render the card UI.

Payment cards are a Business / native-flow feature. Rendering differs between WhatsApp mobile and WhatsApp Web — prefer the flow that matches the UI you want (payment_info for a PIX-only card, review_and_pay for the “Nº da cobrança” / order card) and verify on both clients.

Amounts are integer minor units plus an offset divisor: { value: 1000, offset: 100 } renders as R$ 10,00. PIX key_type is one of EVP (chave aleatória), EMAIL, PHONE (E.164 preferred), CPF, CNPJ.

PIX card (`payment_info`)

Renders the PIX payment card (key / merchant). Use this for a static PIX key without an order card.

await client.message.send(jid, {
  interactiveMessage: {
    nativeFlowMessage: {
      messageVersion: 1,
      buttons: [
        {
          name: 'payment_info',
          buttonParamsJson: JSON.stringify({
            currency: 'BRL',
            total_amount: { value: 0, offset: 100 },
            reference_id: `PIX${Date.now()}`,
            type: 'physical-goods',
            order: {
              status: 'pending',
              subtotal: { value: 0, offset: 100 },
              order_type: 'ORDER',
              items: [
                { name: '', amount: { value: 0, offset: 100 }, quantity: 0, sale_amount: { value: 0, offset: 100 } }
              ]
            },
            payment_settings: [
              {
                type: 'pix_static_code',
                pix_static_code: {
                  merchant_name: 'Loja Exemplo',
                  key: 'pix@loja.com',
                  key_type: 'EMAIL'
                }
              }
            ],
            share_payment_status: false,
            is_soft_deleted: false,
            referral: 'chat_attachment'
            // display_text: 'Pagar com PIX' // optional
          })
        }
      ]
    }
  }
})

Review-and-pay card (`review_and_pay`)

Renders the order / cobrança card (reference number, items, total). Use this for a checkout-style summary.

await client.message.send(jid, {
  interactiveMessage: {
    body: { text: 'Olá! Sua fatura está disponível.' },
    footer: { text: 'Se já pagou, desconsidere.' },
    nativeFlowMessage: {
      messageVersion: 1,
      buttons: [
        {
          name: 'review_and_pay',
          buttonParamsJson: JSON.stringify({
            currency: 'BRL',
            reference_id: 'PGT-PIX-001',
            type: 'physical-goods',
            total_amount: { value: 10000, offset: 100 }, // R$ 100,00
            payment_settings: [
              {
                type: 'pix_static_code',
                pix_static_code: {
                  merchant_name: 'Loja Exemplo',
                  key: 'pix@loja.com',
                  key_type: 'EMAIL'
                }
              }
            ],
            order: {
              status: 'payment_requested',
              subtotal: { value: 10000, offset: 100 },
              order_type: 'ORDER',
              items: [
                { name: 'Fatura', amount: { value: 10000, offset: 100 }, quantity: 1 }
              ]
              // discount: { value: 500, offset: 100 }
            }
            // additional_note: 'Pagamento até o vencimento'
          })
        }
      ]
    }
  }
})

buttonParamsJson must be a JSON string — build the object in code and stringify it. body / footer on interactiveMessage are optional. Don’t mix payment_info and review_and_pay expecting the same UI — they render different cards, and adding extra cta_copy / CTA buttons in the same nativeFlowMessage can render differently on mobile vs Web.

Getting started

Core concepts

Guides

Plugins

Reference

Advanced

Reverse engineering

Raw proto sends

How the stanza type is resolved

Locations

Contacts

Group invite

Buttons

List menu

Interactive native flow (cta_url)

Product

Order

Toggle disappearing messages (ephemeral setting)

Request a phone number

Payments (PIX & review-and-pay)

PIX card (`payment_info`)

Review-and-pay card (`review_and_pay`)

See also

​How the stanza type is resolved

​Locations

​Contacts

​Group invite

​Buttons

​List menu

​Interactive native flow (cta_url)

​Product

​Order

​Newsletter admin invite

​Toggle disappearing messages (ephemeral setting)

​Request a phone number

​Payments (PIX & review-and-pay)

​PIX card (payment_info)

​Review-and-pay card (review_and_pay)

​See also

How the stanza type is resolved

Locations

Contacts

Group invite

Buttons

List menu

Interactive native flow (cta_url)

Product

Order

Newsletter admin invite

Toggle disappearing messages (ephemeral setting)

Request a phone number

Payments (PIX & review-and-pay)

PIX card (`payment_info`)

Review-and-pay card (`review_and_pay`)

See also