Enviar mensagens com WABA

Este guia mostra como enviar mensagens por uma instância oficial (WABA). O endpoint é o mesmo das instâncias não oficiais, POST /v1/wa/messages, com a mesma assinatura de requisição. A Zapster converte o seu payload para o formato da Cloud API da Meta automaticamente.

Antes de começar

Você precisa de uma instância WABA conectada.
Mensagens livres (texto, mídia, botões) só são entregues dentro da janela de conversa de 24 horas, que abre quando o cliente manda mensagem para o seu número. Fora da janela, use um template aprovado pela Meta.
Instâncias WABA não enviam para grupos. Se precisar de grupos, use uma instância não oficial. Veja o comparativo em WABA vs não oficial.

Em todos os exemplos abaixo, troque YOUR_API_TOKEN pelo seu token de API e YOUR_INSTANCE_ID pelo ID da instância WABA.

As mensagens livres (texto, mídia e botões) enviadas por uma instância oficial são gratuitas até 30 de setembro de 2026. A partir de 1 de outubro de 2026, a Meta passa a cobrar por elas. Entenda o que muda na seção Cobrança das mensagens em 2026, mais abaixo.

Texto simples

curl -X POST https://api.zapsterapi.com/v1/wa/messages \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "X-Instance-ID: YOUR_INSTANCE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "5511999999999",
    "text": "Olá! Seu pedido foi confirmado."
  }'

const axios = require('axios')

const response = await axios.post(
  'https://api.zapsterapi.com/v1/wa/messages',
  {
    recipient: '5511999999999',
    text: 'Olá! Seu pedido foi confirmado.',
  },
  {
    headers: {
      Authorization: 'Bearer YOUR_API_TOKEN',
      'X-Instance-ID': 'YOUR_INSTANCE_ID',
    },
  },
)

console.log(response.data.message_id)

const response = await fetch('https://api.zapsterapi.com/v1/wa/messages', {
  body: JSON.stringify({
    recipient: '5511999999999',
    text: 'Olá! Seu pedido foi confirmado.',
  }),
  headers: {
    Authorization: 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
    'X-Instance-ID': 'YOUR_INSTANCE_ID',
  },
  method: 'POST',
})

const data = await response.json()
console.log(data.message_id)

import requests

response = requests.post(
    "https://api.zapsterapi.com/v1/wa/messages",
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "X-Instance-ID": "YOUR_INSTANCE_ID",
    },
    json={
        "recipient": "5511999999999",
        "text": "Olá! Seu pedido foi confirmado.",
    },
)

print(response.json()["message_id"])

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
		"recipient": "5511999999999",
		"text": "Olá! Seu pedido foi confirmado."
	}`)

	req, _ := http.NewRequest("POST", "https://api.zapsterapi.com/v1/wa/messages", body)
	req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")
	req.Header.Set("X-Instance-ID", "YOUR_INSTANCE_ID")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

Mídia (imagem, vídeo ou documento)

Envie a mídia por URL pública ou base64 no campo media. O tipo (imagem, vídeo, documento) é detectado automaticamente a partir do arquivo. Para documentos, você pode informar fileName para controlar o nome exibido no WhatsApp.

curl -X POST https://api.zapsterapi.com/v1/wa/messages \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "X-Instance-ID: YOUR_INSTANCE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "5511999999999",
    "media": {
      "url": "https://exemplo.com/imagem.jpg",
      "caption": "Confira o catálogo de julho"
    }
  }'

const axios = require('axios')

await axios.post(
  'https://api.zapsterapi.com/v1/wa/messages',
  {
    media: {
      caption: 'Confira o catálogo de julho',
      url: 'https://exemplo.com/imagem.jpg',
    },
    recipient: '5511999999999',
  },
  {
    headers: {
      Authorization: 'Bearer YOUR_API_TOKEN',
      'X-Instance-ID': 'YOUR_INSTANCE_ID',
    },
  },
)

await fetch('https://api.zapsterapi.com/v1/wa/messages', {
  body: JSON.stringify({
    media: {
      caption: 'Confira o catálogo de julho',
      url: 'https://exemplo.com/imagem.jpg',
    },
    recipient: '5511999999999',
  }),
  headers: {
    Authorization: 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
    'X-Instance-ID': 'YOUR_INSTANCE_ID',
  },
  method: 'POST',
})

import requests

requests.post(
    "https://api.zapsterapi.com/v1/wa/messages",
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "X-Instance-ID": "YOUR_INSTANCE_ID",
    },
    json={
        "recipient": "5511999999999",
        "media": {
            "url": "https://exemplo.com/imagem.jpg",
            "caption": "Confira o catálogo de julho",
        },
    },
)

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
		"recipient": "5511999999999",
		"media": {
			"url": "https://exemplo.com/imagem.jpg",
			"caption": "Confira o catálogo de julho"
		}
	}`)

	req, _ := http.NewRequest("POST", "https://api.zapsterapi.com/v1/wa/messages", body)
	req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")
	req.Header.Set("X-Instance-ID", "YOUR_INSTANCE_ID")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	res.Body.Close()
}

Para enviar vídeo ou documento, basta trocar a URL. Exemplo de documento com nome de arquivo:

{
  "recipient": "5511999999999",
  "media": {
    "url": "https://exemplo.com/contrato.pdf",
    "fileName": "contrato.pdf",
    "caption": "Segue o contrato para assinatura"
  }
}

Botões interativos

Em WABA, botões viram mensagens interativas da Cloud API e seguem as regras da Meta: até 3 botões reply, ou exatamente 1 botão url, sem misturar os dois tipos. Botões call e copyable não existem em mensagem de sessão (veja Erros comuns). A matriz completa está em Mensagem com botões. Quando você envia media junto com botões, a mídia vira o cabeçalho da mensagem interativa (imagem, vídeo ou documento; áudio não é suportado). Se enviar media.caption e text juntos, o caption tem prioridade e vira o corpo da mensagem.

Botões de resposta rápida (reply) com imagem

curl -X POST https://api.zapsterapi.com/v1/wa/messages \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "X-Instance-ID: YOUR_INSTANCE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "5511999999999",
    "text": "Deseja confirmar o agendamento de amanhã?",
    "media": {
      "url": "https://exemplo.com/clinica.jpg"
    },
    "buttons": [
      { "id": "confirm", "label": "Confirmar", "type": "reply" },
      { "id": "reschedule", "label": "Remarcar", "type": "reply" },
      { "id": "cancel", "label": "Cancelar", "type": "reply" }
    ]
  }'

const axios = require('axios')

await axios.post(
  'https://api.zapsterapi.com/v1/wa/messages',
  {
    buttons: [
      { id: 'confirm', label: 'Confirmar', type: 'reply' },
      { id: 'reschedule', label: 'Remarcar', type: 'reply' },
      { id: 'cancel', label: 'Cancelar', type: 'reply' },
    ],
    media: { url: 'https://exemplo.com/clinica.jpg' },
    recipient: '5511999999999',
    text: 'Deseja confirmar o agendamento de amanhã?',
  },
  {
    headers: {
      Authorization: 'Bearer YOUR_API_TOKEN',
      'X-Instance-ID': 'YOUR_INSTANCE_ID',
    },
  },
)

await fetch('https://api.zapsterapi.com/v1/wa/messages', {
  body: JSON.stringify({
    buttons: [
      { id: 'confirm', label: 'Confirmar', type: 'reply' },
      { id: 'reschedule', label: 'Remarcar', type: 'reply' },
      { id: 'cancel', label: 'Cancelar', type: 'reply' },
    ],
    media: { url: 'https://exemplo.com/clinica.jpg' },
    recipient: '5511999999999',
    text: 'Deseja confirmar o agendamento de amanhã?',
  }),
  headers: {
    Authorization: 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
    'X-Instance-ID': 'YOUR_INSTANCE_ID',
  },
  method: 'POST',
})

import requests

requests.post(
    "https://api.zapsterapi.com/v1/wa/messages",
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "X-Instance-ID": "YOUR_INSTANCE_ID",
    },
    json={
        "recipient": "5511999999999",
        "text": "Deseja confirmar o agendamento de amanhã?",
        "media": {"url": "https://exemplo.com/clinica.jpg"},
        "buttons": [
            {"id": "confirm", "label": "Confirmar", "type": "reply"},
            {"id": "reschedule", "label": "Remarcar", "type": "reply"},
            {"id": "cancel", "label": "Cancelar", "type": "reply"},
        ],
    },
)

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
		"recipient": "5511999999999",
		"text": "Deseja confirmar o agendamento de amanhã?",
		"media": { "url": "https://exemplo.com/clinica.jpg" },
		"buttons": [
			{ "id": "confirm", "label": "Confirmar", "type": "reply" },
			{ "id": "reschedule", "label": "Remarcar", "type": "reply" },
			{ "id": "cancel", "label": "Cancelar", "type": "reply" }
		]
	}`)

	req, _ := http.NewRequest("POST", "https://api.zapsterapi.com/v1/wa/messages", body)
	req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")
	req.Header.Set("X-Instance-ID", "YOUR_INSTANCE_ID")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	res.Body.Close()
}

Botão de link (url) com imagem

Lembre: em WABA só pode existir 1 botão url na mensagem, e ele não pode ser combinado com botões reply.

curl -X POST https://api.zapsterapi.com/v1/wa/messages \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "X-Instance-ID: YOUR_INSTANCE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "5511999999999",
    "text": "Seu boleto de julho está disponível.",
    "media": {
      "url": "https://exemplo.com/fatura.jpg"
    },
    "buttons": [
      {
        "label": "Ver boleto",
        "type": "url",
        "url": "https://exemplo.com/boleto/123"
      }
    ]
  }'

const axios = require('axios')

await axios.post(
  'https://api.zapsterapi.com/v1/wa/messages',
  {
    buttons: [
      {
        label: 'Ver boleto',
        type: 'url',
        url: 'https://exemplo.com/boleto/123',
      },
    ],
    media: { url: 'https://exemplo.com/fatura.jpg' },
    recipient: '5511999999999',
    text: 'Seu boleto de julho está disponível.',
  },
  {
    headers: {
      Authorization: 'Bearer YOUR_API_TOKEN',
      'X-Instance-ID': 'YOUR_INSTANCE_ID',
    },
  },
)

await fetch('https://api.zapsterapi.com/v1/wa/messages', {
  body: JSON.stringify({
    buttons: [
      {
        label: 'Ver boleto',
        type: 'url',
        url: 'https://exemplo.com/boleto/123',
      },
    ],
    media: { url: 'https://exemplo.com/fatura.jpg' },
    recipient: '5511999999999',
    text: 'Seu boleto de julho está disponível.',
  }),
  headers: {
    Authorization: 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
    'X-Instance-ID': 'YOUR_INSTANCE_ID',
  },
  method: 'POST',
})

import requests

requests.post(
    "https://api.zapsterapi.com/v1/wa/messages",
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "X-Instance-ID": "YOUR_INSTANCE_ID",
    },
    json={
        "recipient": "5511999999999",
        "text": "Seu boleto de julho está disponível.",
        "media": {"url": "https://exemplo.com/fatura.jpg"},
        "buttons": [
            {
                "label": "Ver boleto",
                "type": "url",
                "url": "https://exemplo.com/boleto/123",
            }
        ],
    },
)

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
		"recipient": "5511999999999",
		"text": "Seu boleto de julho está disponível.",
		"media": { "url": "https://exemplo.com/fatura.jpg" },
		"buttons": [
			{ "label": "Ver boleto", "type": "url", "url": "https://exemplo.com/boleto/123" }
		]
	}`)

	req, _ := http.NewRequest("POST", "https://api.zapsterapi.com/v1/wa/messages", body)
	req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")
	req.Header.Set("X-Instance-ID", "YOUR_INSTANCE_ID")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	res.Body.Close()
}

Template (fora da janela de 24h)

Templates precisam ser criados e aprovados na Meta antes do envio. O campo template é mutuamente exclusivo com text e media.

O objeto template é um espelho do formato da Meta. A Zapster embrulha apenas name e language (que vira { "code": ... }) e repassa o array components exatamente como você o envia para a Cloud API, sem reinterpretar. Por isso, use o mesmo formato da documentação de templates da Cloud API da Meta.

O components descreve as partes do template que recebem valores no envio:

header: cabeçalho com mídia (imagem, vídeo ou documento) ou com uma variável de texto.
body: o corpo, onde entram as variáveis do texto aprovado.
button: os botões que têm valor dinâmico, como o payload de uma resposta rápida ou o sufixo de uma URL.

As variáveis do template podem ser posicionais ({{1}}, {{2}}, preenchidas pela ordem do array parameters) ou nomeadas ({{customer_name}}, preenchidas por parameter_name). Cada template usa um estilo ou o outro, nunca os dois juntos. Os valores enviados precisam corresponder ao que o template aprovado espera.

Exemplo simples (variável posicional)

curl -X POST https://api.zapsterapi.com/v1/wa/messages \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "X-Instance-ID: YOUR_INSTANCE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "5511999999999",
    "template": {
      "name": "confirmacao_pedido",
      "language": "pt_BR",
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "João" }
          ]
        }
      ]
    }
  }'

const axios = require('axios')

await axios.post(
  'https://api.zapsterapi.com/v1/wa/messages',
  {
    recipient: '5511999999999',
    template: {
      components: [
        {
          parameters: [{ text: 'João', type: 'text' }],
          type: 'body',
        },
      ],
      language: 'pt_BR',
      name: 'confirmacao_pedido',
    },
  },
  {
    headers: {
      Authorization: 'Bearer YOUR_API_TOKEN',
      'X-Instance-ID': 'YOUR_INSTANCE_ID',
    },
  },
)

await fetch('https://api.zapsterapi.com/v1/wa/messages', {
  body: JSON.stringify({
    recipient: '5511999999999',
    template: {
      components: [
        {
          parameters: [{ text: 'João', type: 'text' }],
          type: 'body',
        },
      ],
      language: 'pt_BR',
      name: 'confirmacao_pedido',
    },
  }),
  headers: {
    Authorization: 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
    'X-Instance-ID': 'YOUR_INSTANCE_ID',
  },
  method: 'POST',
})

import requests

requests.post(
    "https://api.zapsterapi.com/v1/wa/messages",
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "X-Instance-ID": "YOUR_INSTANCE_ID",
    },
    json={
        "recipient": "5511999999999",
        "template": {
            "name": "confirmacao_pedido",
            "language": "pt_BR",
            "components": [
                {
                    "type": "body",
                    "parameters": [{"type": "text", "text": "João"}],
                }
            ],
        },
    },
)

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
		"recipient": "5511999999999",
		"template": {
			"name": "confirmacao_pedido",
			"language": "pt_BR",
			"components": [
				{
					"type": "body",
					"parameters": [{ "type": "text", "text": "João" }]
				}
			]
		}
	}`)

	req, _ := http.NewRequest("POST", "https://api.zapsterapi.com/v1/wa/messages", body)
	req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")
	req.Header.Set("X-Instance-ID", "YOUR_INSTANCE_ID")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	res.Body.Close()
}

Com header, variáveis posicionais e botões

Este template tem cabeçalho de imagem, duas variáveis posicionais no corpo ({{1}} e {{2}}) e dois botões: um de resposta rápida (com payload) e um de URL dinâmica (o texto vira o sufixo anexado à URL base do template). O index do botão segue a ordem em que ele aparece no template aprovado.

curl -X POST https://api.zapsterapi.com/v1/wa/messages \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "X-Instance-ID: YOUR_INSTANCE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "5511999999999",
    "template": {
      "name": "pedido_enviado",
      "language": "pt_BR",
      "components": [
        {
          "type": "header",
          "parameters": [
            { "type": "image", "image": { "link": "https://exemplo.com/banner.jpg" } }
          ]
        },
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "João" },
            { "type": "text", "text": "#1234" }
          ]
        },
        {
          "type": "button",
          "sub_type": "quick_reply",
          "index": 0,
          "parameters": [
            { "type": "payload", "payload": "RASTREAR_PEDIDO" }
          ]
        },
        {
          "type": "button",
          "sub_type": "url",
          "index": 1,
          "parameters": [
            { "type": "text", "text": "pedido/1234" }
          ]
        }
      ]
    }
  }'

const axios = require('axios')

await axios.post(
  'https://api.zapsterapi.com/v1/wa/messages',
  {
    recipient: '5511999999999',
    template: {
      components: [
        {
          parameters: [
            { image: { link: 'https://exemplo.com/banner.jpg' }, type: 'image' },
          ],
          type: 'header',
        },
        {
          parameters: [
            { text: 'João', type: 'text' },
            { text: '#1234', type: 'text' },
          ],
          type: 'body',
        },
        {
          index: 0,
          parameters: [{ payload: 'RASTREAR_PEDIDO', type: 'payload' }],
          sub_type: 'quick_reply',
          type: 'button',
        },
        {
          index: 1,
          parameters: [{ text: 'pedido/1234', type: 'text' }],
          sub_type: 'url',
          type: 'button',
        },
      ],
      language: 'pt_BR',
      name: 'pedido_enviado',
    },
  },
  {
    headers: {
      Authorization: 'Bearer YOUR_API_TOKEN',
      'X-Instance-ID': 'YOUR_INSTANCE_ID',
    },
  },
)

await fetch('https://api.zapsterapi.com/v1/wa/messages', {
  body: JSON.stringify({
    recipient: '5511999999999',
    template: {
      components: [
        {
          parameters: [
            { image: { link: 'https://exemplo.com/banner.jpg' }, type: 'image' },
          ],
          type: 'header',
        },
        {
          parameters: [
            { text: 'João', type: 'text' },
            { text: '#1234', type: 'text' },
          ],
          type: 'body',
        },
        {
          index: 0,
          parameters: [{ payload: 'RASTREAR_PEDIDO', type: 'payload' }],
          sub_type: 'quick_reply',
          type: 'button',
        },
        {
          index: 1,
          parameters: [{ text: 'pedido/1234', type: 'text' }],
          sub_type: 'url',
          type: 'button',
        },
      ],
      language: 'pt_BR',
      name: 'pedido_enviado',
    },
  }),
  headers: {
    Authorization: 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
    'X-Instance-ID': 'YOUR_INSTANCE_ID',
  },
  method: 'POST',
})

import requests

requests.post(
    "https://api.zapsterapi.com/v1/wa/messages",
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "X-Instance-ID": "YOUR_INSTANCE_ID",
    },
    json={
        "recipient": "5511999999999",
        "template": {
            "name": "pedido_enviado",
            "language": "pt_BR",
            "components": [
                {
                    "type": "header",
                    "parameters": [
                        {"type": "image", "image": {"link": "https://exemplo.com/banner.jpg"}}
                    ],
                },
                {
                    "type": "body",
                    "parameters": [
                        {"type": "text", "text": "João"},
                        {"type": "text", "text": "#1234"},
                    ],
                },
                {
                    "type": "button",
                    "sub_type": "quick_reply",
                    "index": 0,
                    "parameters": [{"type": "payload", "payload": "RASTREAR_PEDIDO"}],
                },
                {
                    "type": "button",
                    "sub_type": "url",
                    "index": 1,
                    "parameters": [{"type": "text", "text": "pedido/1234"}],
                },
            ],
        },
    },
)

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
		"recipient": "5511999999999",
		"template": {
			"name": "pedido_enviado",
			"language": "pt_BR",
			"components": [
				{
					"type": "header",
					"parameters": [
						{ "type": "image", "image": { "link": "https://exemplo.com/banner.jpg" } }
					]
				},
				{
					"type": "body",
					"parameters": [
						{ "type": "text", "text": "João" },
						{ "type": "text", "text": "#1234" }
					]
				},
				{
					"type": "button",
					"sub_type": "quick_reply",
					"index": 0,
					"parameters": [{ "type": "payload", "payload": "RASTREAR_PEDIDO" }]
				},
				{
					"type": "button",
					"sub_type": "url",
					"index": 1,
					"parameters": [{ "type": "text", "text": "pedido/1234" }]
				}
			]
		}
	}`)

	req, _ := http.NewRequest("POST", "https://api.zapsterapi.com/v1/wa/messages", body)
	req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")
	req.Header.Set("X-Instance-ID", "YOUR_INSTANCE_ID")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	res.Body.Close()
}

Variáveis nomeadas

Quando o template foi aprovado com variáveis nomeadas, cada parâmetro leva um parameter_name além de type e text. O restante da requisição (o recipient, os headers, o name e o language) é igual aos exemplos acima. Muda apenas o conteúdo de components:

components (variáveis nomeadas)

[
  {
    "type": "header",
    "parameters": [
      { "type": "text", "parameter_name": "company_name", "text": "Zapster" }
    ]
  },
  {
    "type": "body",
    "parameters": [
      { "type": "text", "parameter_name": "customer_name", "text": "João" },
      { "type": "text", "parameter_name": "order_id", "text": "#1234" }
    ]
  }
]

Não misture variáveis posicionais e nomeadas no mesmo template. Use parameter_name apenas quando o template foi aprovado com variáveis nomeadas; caso contrário, use a forma posicional (só type e text, na ordem em que aparecem).

Cobrança das mensagens em 2026

O canal oficial do WhatsApp (WABA) é pago, e quem cobra pelas mensagens é a Meta, não a Zapster. São duas coisas separadas: a assinatura da sua instância na Zapster, de um lado, e o que a Meta cobra pelo envio das mensagens, do outro. A cobrança da Meta é feita através da conta de WhatsApp Business ligada ao seu número. Em 2026 a Meta muda a forma de cobrar as mensagens livres, que são justamente as que você aprende a enviar neste guia. Esta seção resume, em português claro, o que a documentação oficial da Meta descreve de um jeito nem sempre fácil de entender.

O que é uma “mensagem de serviço”

É toda mensagem livre (texto, mídia ou botões) que você envia em resposta a um cliente, dentro da janela de 24 horas. Pela definição da Meta, é qualquer mensagem que não seja um template. São exatamente as mensagens deste guia. Até hoje elas são gratuitas, assim desde novembro de 2024.

O que muda e quando

Data	O que passa a ser cobrado
1 de agosto de 2026	Mensagens do Meta Business Agent (respostas geradas pela inteligência artificial da Meta) passam a ser cobradas por token: US$ 2,00 a cada 1 milhão de tokens, o que dá por volta de 4 a 5 centavos de dólar por mensagem. Isso só vale se você usar o agente de IA da Meta.
1 de outubro de 2026	As mensagens de serviço (as mensagens livres deste guia) passam a ser cobradas por mensagem enviada. Elas eram gratuitas desde novembro de 2024. No mesmo dia, mensagens de utilidade enviadas dentro da janela de 24 horas, gratuitas desde 1 de julho de 2025, também passam a ser cobradas.

Quanto vai custar

A Meta ainda não publicou os valores. Segundo a documentação, os preços que entram em vigor em 1 de outubro de 2026 serão anunciados até 1 de setembro de 2026. O preço de uma mensagem de serviço vai acompanhar o preço já usado para mensagens de utilidade e autenticação, que varia conforme o país do cliente. A Meta informou que não haverá desconto por volume para mensagens de serviço.

O que continua igual

A regra da janela de 24 horas não muda: mensagens livres só saem com a janela aberta. O que muda é que elas deixam de ser gratuitas.
Os templates já eram pagos e seguem com a cobrança própria deles.
Essa cobrança é só do canal oficial (WABA). Instâncias não oficiais (QR code) não passam por essa cobrança da Meta.

Em resumo

Hoje, responder um cliente dentro da janela de 24 horas não custa nada. A partir de 1 de outubro de 2026, cada uma dessas respostas passa a ter um custo cobrado pela Meta. Se você envia muitas mensagens de atendimento, vale acompanhar o anúncio de preços de setembro de 2026 e já incluir esse custo no seu planejamento.

Fonte: WhatsApp Business Platform: Non-Template Messages Pricing, documentação oficial da Meta. As datas e os valores são definidos pela Meta e podem mudar.

Erros comuns

Quando o payload usa um recurso que a Cloud API não suporta, a Zapster rejeita a requisição na hora com um erro 400 explicando o motivo. Nada é descartado ou adaptado silenciosamente.

Código	Quando acontece	Como resolver
`waba_feature_not_supported`	Botão `call` ou `copyable` em mensagem de sessão, ou áudio junto com botões	Para ligação, use um template com botão `PHONE_NUMBER`. Para copiar código, use um template de Marketing ou Authentication. Para áudio, envie em uma mensagem separada
`waba_invalid_button_combination`	Mistura de botão `url` com `reply`, ou mais de 1 botão `url`	Envie 1 botão `url` sozinho, ou até 3 botões `reply`
`waba_conversation_window_closed`	Mensagem livre fora da janela de 24 horas	Envie um template aprovado para reabrir a conversa
`waba_group_not_supported`	`recipient` de grupo em instância WABA	Grupos só funcionam em instâncias não oficiais
`waba_template_required`	Campo `template` enviado para instância não oficial	Templates só existem em instâncias WABA

Próximos passos

Mensagem com botões para a matriz completa de suporte por tipo de conexão
WABA vs não oficial para escolher o tipo de instância
Conectando uma instância WABA

Introdução

Conceitos

Webhooks

Integrações

Guias

Número 555 da Meta

Enviar mensagens com WABA

Antes de começar

Texto simples

Mídia (imagem, vídeo ou documento)

Botões interativos

Botões de resposta rápida (reply) com imagem

Botão de link (url) com imagem

Template (fora da janela de 24h)

Exemplo simples (variável posicional)

Com header, variáveis posicionais e botões

Variáveis nomeadas

Cobrança das mensagens em 2026

O que é uma “mensagem de serviço”

O que muda e quando

Quanto vai custar

O que continua igual

Em resumo

Erros comuns

Próximos passos

​Antes de começar

​Texto simples

​Mídia (imagem, vídeo ou documento)

​Botões interativos

​Botões de resposta rápida (reply) com imagem

​Botão de link (url) com imagem

​Template (fora da janela de 24h)

​Exemplo simples (variável posicional)

​Com header, variáveis posicionais e botões

​Variáveis nomeadas

​Cobrança das mensagens em 2026

​O que é uma “mensagem de serviço”

​O que muda e quando

​Quanto vai custar

​O que continua igual

​Em resumo

​Erros comuns

​Próximos passos

Antes de começar

Texto simples

Mídia (imagem, vídeo ou documento)

Botões interativos

Botões de resposta rápida (reply) com imagem

Botão de link (url) com imagem

Template (fora da janela de 24h)

Exemplo simples (variável posicional)

Com header, variáveis posicionais e botões

Variáveis nomeadas

Cobrança das mensagens em 2026

O que é uma “mensagem de serviço”

O que muda e quando

Quanto vai custar

O que continua igual

Em resumo

Erros comuns

Próximos passos