Atualizado em 25/10/2026
Na API oficial do WhatsApp, mensagem de boas-vindas, de ausência e de horário de atendimento não são configurações prontas como no app WhatsApp Business: quem envia é o seu sistema, a partir do webhook de mensagem recebida. A lógica é simples: quando o cliente escreve, você verifica se é o primeiro contato e se está dentro do horário, e responde com texto livre, já que a janela de 24 horas acabou de abrir. A Cloud API oferece só um complemento nativo, os ice breakers e comandos, que aparecem antes da primeira mensagem.
O que muda em relação ao app WhatsApp Business
No app, essas mensagens são ligadas em poucos toques. A Central de Ajuda do WhatsApp descreve dois recursos:
- Mensagem de saudação: enviada quando o cliente escreve pela primeira vez ou volta a escrever depois de 14 dias sem conversa.
- Mensagem de ausência: enviada sempre, num horário personalizado ou fora do horário comercial definido no perfil da empresa.
Na API oficial do WhatsApp não existe esse painel. O número é operado por software, e o software decide o que responder. Isso dá mais trabalho no início e muito mais controle depois: dá para usar feriados, horários diferentes por equipe, idioma do cliente, fila de atendimento e status do pedido.
| Recurso | App WhatsApp Business | API (Cloud API) |
|---|---|---|
| Saudação no primeiro contato | Configuração nativa | Seu webhook detecta o primeiro contato e responde |
| Mensagem de ausência | Configuração nativa, com horário do perfil | Seu webhook compara o horário e responde |
| Feriados e exceções | Limitado | Livre: você define a regra |
| Botões, listas, links | Limitado | Mensagens interativas completas |
| Opções antes da primeira mensagem | Não | Ice breakers e comandos (nativo) |
Ice breakers e comandos: o único recurso nativo
A Cloud API tem os chamados componentes conversacionais, configurados por número com POST /<PHONE_NUMBER_ID>/conversational_automation. Segundo a documentação de componentes conversacionais:
- Ice breakers (
prompts): até 4 por número, com até 80 caracteres cada, sem emojis. Aparecem como opções tocáveis quando o cliente abre uma conversa nova com a empresa. - Comandos (
commands): até 30, com nome de até 32 caracteres e descrição de até 256. O cliente digita/e vê a lista.
Quando o cliente toca num ice breaker ou envia um comando, chega um webhook comum de mensagem recebida, com o texto em messages[].text.body. Ou seja, o ice breaker não responde nada sozinho: ele só facilita a primeira mensagem, e o seu sistema responde.
Dois cuidados. Os ice breakers só aparecem se ainda não existe conversa entre o cliente e o número; para testar, apague a conversa no seu celular antes. E um link wa.me com texto pré-preenchido esconde os ice breakers, porque o cliente já chega com uma mensagem pronta.
A Meta chegou a oferecer, no mesmo recurso, uma opção de mensagem de boas-vindas que disparava um evento request_welcome quando o cliente abria a conversa pela primeira vez. A página atual da documentação descreve apenas ice breakers e comandos. Não construa o fluxo dependendo desse evento: detecte o primeiro contato no seu próprio banco, como mostramos a seguir.
Como montar boas-vindas, ausência e horário no webhook
O fluxo completo cabe em quatro passos:
- Receba o webhook de mensagem (
field: "messages", comvalue.messages[]). - Descubra se é o primeiro contato do cliente (ou o primeiro depois de X dias).
- Verifique se o horário atual, no fuso da empresa, está dentro do expediente e não é feriado.
- Escolha a resposta: boas-vindas, ausência ou nada (deixa o atendente ou o bot responder).
O timestamp da mensagem recebida vem em segundos Unix, em UTC. Converta para o fuso da operação (no Brasil, normalmente America/Sao_Paulo) antes de comparar com o horário comercial.
Exemplo em Node.js
const EXPEDIENTE = {
fuso: 'America/Sao_Paulo',
// 0 = domingo ... 6 = sábado; horários em HH:MM
dias: { 1: ['08:00', '18:00'], 2: ['08:00', '18:00'], 3: ['08:00', '18:00'],
4: ['08:00', '18:00'], 5: ['08:00', '17:00'], 6: ['09:00', '12:00'] },
feriados: ['2026-11-02', '2026-11-15', '2026-11-20', '2026-12-25'],
};
function agoraNoFuso(tsSegundos, fuso) {
const d = new Date(Number(tsSegundos) * 1000);
const p = Object.fromEntries(
new Intl.DateTimeFormat('en-CA', {
timeZone: fuso, year: 'numeric', month: '2-digit', day: '2-digit',
hour: '2-digit', minute: '2-digit', weekday: 'short', hour12: false,
}).formatToParts(d).map((x) => [x.type, x.value])
);
const dias = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
return { data: `${p.year}-${p.month}-${p.day}`, hora: `${p.hour}:${p.minute}`, dia: dias[p.weekday] };
}
function dentroDoExpediente(ts) {
const { data, hora, dia } = agoraNoFuso(ts, EXPEDIENTE.fuso);
if (EXPEDIENTE.feriados.includes(data)) return false;
const faixa = EXPEDIENTE.dias[dia];
return Boolean(faixa) && hora >= faixa[0] && hora < faixa[1];
}
export async function aoReceberMensagem(msg, db, enviarTexto) {
const contato = await db.buscarContato(msg.from);
const primeiroContato = !contato || Date.now() - contato.ultimaMensagemEm > 14 * 864e5;
const aberto = dentroDoExpediente(msg.timestamp);
await db.registrarMensagem(msg.from, Number(msg.timestamp) * 1000);
if (!aberto) {
// evita repetir a ausência a cada mensagem do cliente
if (contato?.ausenciaEnviadaEm && Date.now() - contato.ausenciaEnviadaEm < 12 * 36e5) return;
await db.marcarAusencia(msg.from, Date.now());
return enviarTexto(msg.from,
'Oi! Nosso atendimento funciona de segunda a sexta, das 8h às 18h, e sábado das 9h às 12h. ' +
'Sua mensagem ficou registrada e respondemos assim que abrirmos.');
}
if (primeiroContato) {
return enviarTexto(msg.from,
'Olá! Aqui é a Loja Exemplo. Me conta como podemos ajudar: pedido, troca ou dúvida sobre produto?');
}
// dentro do horário e cliente recorrente: segue para o bot ou para a fila de atendentes
}Os feriados acima são exemplos de feriados nacionais de 2026; inclua os estaduais e municipais da sua operação e mantenha a lista num lugar fácil de editar.
O envio da resposta
A resposta é uma mensagem de texto comum, permitida porque o cliente acabou de abrir a janela de atendimento. Pela Vectalk, o payload é o mesmo da Cloud API:
curl -X POST https://apis.vectalk.com.br/api/messages \
-H "Authorization: Bearer $VECTALK_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "5511999999999",
"type": "text",
"text": { "body": "Oi! Nosso atendimento funciona de segunda a sexta, das 8h às 18h." }
}'Para boas-vindas, vale trocar o texto por botões de resposta (“Fazer pedido”, “Falar com atendente”, “Segunda via”). O cliente toca em vez de digitar, e o seu sistema recebe uma resposta estruturada.
Quanto custa responder automaticamente
Mensagens de texto livre enviadas dentro da janela de atendimento são da categoria serviço. Segundo a página de preços da Meta, desde 1º de outubro de 2026 as mensagens de serviço são cobradas a partir da 1.001ª entregue no mês, por número; as primeiras 1.000 continuam gratuitas. Mensagens do cliente para a empresa nunca são cobradas.
Na prática, isso muda o desenho:
- Não responda toda mensagem fora do horário. Uma ausência a cada 12 horas por contato, como no exemplo, basta.
- Evite duas mensagens quando uma resolve. Boas-vindas com botões substitui “Olá!” seguido de um menu.
- Acompanhe o volume. O webhook de status traz o tipo de cobrança de cada mensagem; os detalhes estão no artigo de preços da API no Brasil.
E fora da janela de 24 horas?
Boas-vindas e ausência são respostas: sempre acontecem logo depois de uma mensagem do cliente, com a janela aberta. O problema aparece no dia seguinte. Se o cliente escreveu às 22h, ficou com a ausência e ninguém respondeu até as 22h do outro dia, a janela fechou e você só pode retomar com um template aprovado. Detalhes no artigo sobre a janela de 24 horas.
Duas defesas simples: uma fila que prioriza, na abertura do expediente, as conversas recebidas fora do horário, e um alerta para conversas que estão perto de completar 24 horas sem resposta. As métricas de atendimento mostram como medir isso.
Boas práticas para mensagens automáticas
- Diga o horário real e o próximo passo. “Respondemos a partir das 8h” é melhor do que “retornaremos em breve”.
- Ofereça um caminho para humano. A Política de Mensagens do WhatsApp Business exige caminhos de escalonamento claros quando o atendimento é automatizado.
- Não peça dados sensíveis na boas-vindas. CPF, cartão e senha não cabem numa mensagem automática.
- Respeite quem pediu para sair. Uma resposta automática não é motivo para reativar marketing. Veja LGPD e WhatsApp.
- Combine com a distribuição. Dentro do horário, a boas-vindas pode já perguntar o assunto para encaminhar ao time certo, como no multiatendimento.
- Em agendamento, deixe o bot trabalhar fora do horário. Uma clínica pode marcar consultas às 23h com um agendamento com IA em vez de mandar só a ausência.
Como fazer isso com a Vectalk
Na Vectalk, os webhooks que chegam ao seu sistema são os da Meta. Registre sua URL com POST /api/webhooks, trate as mensagens recebidas como no exemplo e responda com POST /api/messages. Para os ice breakers e comandos, use POST /api/automation com prompts e commands, e GET /api/automation para conferir a configuração atual; os dois endpoints usam o token de instância. O endpoint também aceita enable_welcome_message, que liga a opção de boas-vindas da Meta descrita acima; como ela não está mais na documentação atual da Meta, mantenha a boas-vindas no seu webhook.
curl -X POST https://apis.vectalk.com.br/api/automation \
-H "Authorization: Bearer $VECTALK_TOKEN_INSTANCIA" \
-H "Content-Type: application/json" \
-d '{
"prompts": ["Quero fazer um pedido", "Acompanhar meu pedido", "Trocas e devoluções", "Falar com atendente"],
"commands": [{ "command_name": "horario", "command_description": "Mostra o horário de atendimento" }]
}'Referência em docs.vectalk.com.br. Para começar, crie sua conta em apps.vectalk.com.br/register.
Perguntas frequentes
Dá para usar a mensagem de ausência do app junto com a API?
A mensagem de ausência é um recurso do app WhatsApp Business. A documentação de coexistência da Meta lista as mensagens de saudação e de ausência entre as ferramentas do app que não são suportadas na Cloud API. Mesmo com o número no app e na API ao mesmo tempo, mantenha boas-vindas e ausência no seu sistema.
Preciso de template para a mensagem de boas-vindas?
Não. A boas-vindas responde a uma mensagem do cliente, então a janela de 24 horas está aberta e você pode enviar texto livre ou mensagem interativa. Template só é necessário para iniciar ou retomar a conversa fora da janela.
A mensagem automática é cobrada?
Ela é uma mensagem de serviço. Desde 1º de outubro de 2026, a Meta cobra as mensagens de serviço a partir da 1.001ª entregue no mês, por número. Por isso vale limitar a ausência a uma vez por período.
Como sei se é o primeiro contato do cliente?
A Cloud API não informa isso diretamente. Guarde no seu banco a data da última mensagem de cada wa_id e defina sua própria regra, como “nenhuma mensagem nos últimos 14 dias”, parecida com a do app.
Os ice breakers aparecem para todo mundo?
Só para quem abre uma conversa nova com o número. Quem já tem histórico com a empresa não vê os ice breakers, e quem chega por link com texto pré-preenchido também não.
Fontes oficiais consultadas em 25/10/2026: Componentes conversacionais (ice breakers e comandos), Coexistência, Webhook de mensagens, Preços da plataforma, Política de Mensagens do WhatsApp Business, Central de Ajuda do WhatsApp: mensagens de saudação, Central de Ajuda do WhatsApp: mensagens de ausência, Docs da Vectalk: automação conversacional.