Envios proto brutos

Para tipos de conteúdo que o WhatsApp suporta mas o zapo ainda não empacota num builder tipado, o client.message.send também aceita um Proto.IMessage bruto. Preencha o campo que nomeia o tipo — locationMessage, contactMessage, contactsArrayMessage, interactiveMessage, e assim por diante — e a lib encoda literalmente. Tipos que já têm um builder tipado — enquetes, reações, edições, revogações, fixação, manter no chat, wrapping view-once e citações / menções / previews de link — pertencem a Enviando mensagens e Mensagens interativas. Esta página é para os tipos que só existem em modo bruto. O conjunto completo de campos Proto.IMessage reconhecidos (localização, localização ao vivo, contatos, convite de grupo, produto, pedido, …) está na referência de tipos de mensagem. Alguns exemplos abaixo usam valores de enum do namespace proto:

import { proto } from 'zapo-js'

Como o tipo da stanza é resolvido

Qualquer que seja o campo preenchido, o zapo classifica a mensagem antes de ela ir para o fio: uma stanza <message> carrega um type (text ou media), e uma stanza de mídia precisa carregar também um mediatype. O servidor descarta silenciosamente uma stanza de mídia sem mediatype — o envio recebe ack normalmente e nada chega — então um tipo de conteúdo que cai no default de mídia sem um mediatype se perde de forma invisível. Dois detalhes importam quando você monta um payload na mão:

Wrappers são percorridos por dentro. deviceSentMessage, botForwardedMessage, groupStatusMessageV2 e groupStatusMessage carregam a mensagem real em .message, então o conteúdo interno decide o tipo. Uma imagem encaminhada continua media com seu mediatype; um status de imagem embrulhado em groupStatusMessageV2 não sai mais como type="media" sem mediatype — uma combinação que nenhum client real envia.
A família de rich response de IA classifica como texto. richResponseMessage e um wrapper botForwardedMessage puro resolvem para type="text". Antes da 1.9.0 eles caíam no default de mídia e nunca eram entregues.

Localizações

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

name e address são opcionais. Para uma mensagem de live location, use o campo liveLocationMessage — ele carrega os metadados de movimento (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
  }
})

Contatos

Um cartão de contato único é um contactMessage com uma string vCard:

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 }
})

O parâmetro waid=<digits> na linha TEL é o que permite ao cliente WhatsApp vincular o cartão a uma conta WhatsApp — use o telefone E.164 do destinatário sem o +. Para vários cartões de uma vez, use contactsArrayMessage:

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

Convite de grupo

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!'
  }
})

Botões

Até três botões de quick-reply. O header é um oneof — escolha texto, imagem, vídeo, localização ou documento (pré-upload para mídia):

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
      }
    ]
  }
})

Uma lista para um grupo sai com um formato de stanza diferente da mesma lista numa conversa direta: o grupo só a aceita quando type=media, mediatype=list e o nó companheiro <biz><list> viajam juntos, enquanto um envio direto mantém o formato de texto plano. O zapo escolhe o certo pra você. Antes da 1.10.0 uma lista em grupo era nackeada com 479 enquanto a mensagem idêntica passava no 1:1.

Uma lista single-select de rows agrupadas em sections:

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)

A superfície interativa moderna — botões cujos parâmetros são payloads ad-hoc codificados em JSON:

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
    }
  }
})

É o mesmo formato de wire dos cards PIX / review-and-pay em Pagamentos abaixo — só o name do botão e o buttonParamsJson mudam.

Produto

Envie um produto do catálogo. O productImage interno precisa estar pré-uploadado:

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 */ }
    }
  }
})

Pedido

Confirmação / consulta de pedido:

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'
  }
})

Convide um contato para ser co-admin de uma das suas 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
  }
})

Alternar mensagens temporárias (configuração ephemeral)

Alternância do timer para o chat inteiro — diferente da opção de envio expirationSeconds (uma mensagem) e do wrapper ephemeralMessage (uma mensagem herdando o timer do chat).

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

Solicitar número de telefone

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

Pagamentos (PIX e review-and-pay)

Envie cards de pagamento do WhatsApp Business — PIX estático (payment_info) e checkout de pedido (review_and_pay) — como payloads brutos interactiveMessage / nativeFlowMessage via client.message.send. Ainda não existe builder tipado, então monte o shape você mesmo do mesmo jeito que os cards de localização/contato acima. A lib apenas relaya os botões native-flow interativos; os clientes WhatsApp renderizam a UI do card.

Cards de pagamento são um recurso Business / native-flow. A renderização difere entre WhatsApp mobile e WhatsApp Web — prefira o flow que combina com a UI que você quer (payment_info para o card só-PIX, review_and_pay para o card “Nº da cobrança” / pedido) e valide nos dois clients.

Valores são unidades monetárias inteiras mais um divisor offset: { value: 1000, offset: 100 } renderiza como R$ 10,00. key_type do PIX é um de EVP (chave aleatória), EMAIL, PHONE (E.164 preferido), CPF, CNPJ.

Card PIX (`payment_info`)

Renderiza o card PIX (chave / merchant). Use para uma chave PIX estática sem card de pedido.

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
          })
        }
      ]
    }
  }
})

Card review-and-pay (`review_and_pay`)

Renderiza o card de pedido / cobrança (número, itens, total). Use para um resumo estilo checkout.

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 precisa ser uma string JSON — monte o objeto em código e faça o stringify. body / footer em interactiveMessage são opcionais. Não misture payment_info e review_and_pay esperando a mesma UI — eles renderizam cards diferentes, e adicionar cta_copy / botões CTA extras no mesmo nativeFlowMessage pode renderizar diferente no mobile vs Web.

Veja também

Enviando mensagens — a API base client.message.send, opções e variantes de conteúdo tipadas.
Mensagens interativas — builders tipados para enquetes, reações, edições, revogações, fixar e manter no chat.
Referência de tipos de mensagem — todos os campos Proto.IMessage reconhecidos e seu tipo resolvido.

Primeiros passos

Conceitos

Guias

Plugins

Referência

Avançado

Engenharia reversa

Envios proto brutos

Como o tipo da stanza é resolvido

Localizações

Contatos

Convite de grupo

Botões

Menu de lista

Interactive native flow (cta_url)

Produto

Pedido

Alternar mensagens temporárias (configuração ephemeral)

Solicitar número de telefone

Pagamentos (PIX e review-and-pay)

Card PIX (`payment_info`)

Card review-and-pay (`review_and_pay`)

Veja também

​Como o tipo da stanza é resolvido

​Localizações

​Contatos

​Convite de grupo

​Botões

​Menu de lista

​Interactive native flow (cta_url)

​Produto

​Pedido

​Convite de admin de newsletter

​Alternar mensagens temporárias (configuração ephemeral)

​Solicitar número de telefone

​Pagamentos (PIX e review-and-pay)

​Card PIX (payment_info)

​Card review-and-pay (review_and_pay)

​Veja também

Como o tipo da stanza é resolvido

Localizações

Contatos

Convite de grupo

Botões

Menu de lista

Interactive native flow (cta_url)

Produto

Pedido

Convite de admin de newsletter

Alternar mensagens temporárias (configuração ephemeral)

Solicitar número de telefone

Pagamentos (PIX e review-and-pay)

Card PIX (`payment_info`)

Card review-and-pay (`review_and_pay`)

Veja também