Qual é a diferença entre auto-reply e resposta rápida?

/auto-reply avalia mensagens recebidas segundo regras configuradas e pode enviar uma resposta quando há correspondência. Cada regra tem nome, tipo e valores de correspondência, conteúdo de resposta, escopo, prioridade e opções de comportamento. Mensagens vazias e mensagens enviadas pela própria instância não acionam a avaliação.

/quickreply mantém modelos para consulta e uso posterior. A API aceita gravar e listar respostas rápidas com campos como shortCut, text, type, file, docName, owner e onWhatsApp. Não há rota de exclusão nem gatilho automático associado a shortCut documentado no contrato consultado. Portanto, trate o atalho como dado do modelo, sem presumir que digitar o texto em uma conversa envie o conteúdo.

Rota O que faz
POST /auto-reply/rule Cria uma regra.
GET /auto-reply/rules Lista regras.
GET /auto-reply/rule/{id} Consulta uma regra.
PUT /auto-reply/rule/{id} Atualiza uma regra com o objeto de regra.
DELETE /auto-reply/rule/{id} Remove uma regra.
POST /auto-reply/rule/{id}/toggle Ativa ou desativa pelo campo active.
GET, POST /auto-reply/settings Consulta ou atualiza configurações gerais.
POST /quickreply/edit Salva ou atualiza um modelo de resposta rápida.
GET /quickreply/showall Lista os modelos salvos.

Como os gatilhos decidem quando responder?

O campo match_type define a comparação. Em keywords, a regra procura qualquer item de match_value como trecho de texto, sem diferenciar maiúsculas de minúsculas. Em exact, compara a mensagem inteira, também sem diferenciar maiúsculas, com pattern. Em pattern, interpreta pattern como expressão regular case-insensitive. Como a regra exata depende de pattern, mantenha esse campo com o valor esperado quando usar esse modo.

O escopo restringe onde a regra pode atuar: groups limita a grupos, private a conversas privadas, e vazio ou all não aplica esse filtro. allowed_jids cria uma lista de remetentes permitidos e blocked_jids exclui remetentes. priority organiza regras. Com multi_match=false, a avaliação para depois da primeira regra que disparar; quando habilitado, outras correspondências podem ser processadas.

Uma regra nova fica ativa por padrão. A simulação de digitação também inicia habilitada; sem configuração, o serviço usa 1500 ms para essa simulação, cooldown global de 2000 ms e multi_match=false. cooldown_ms=0 usa o cooldown global. Os valores são intervalos em milissegundos: estabeleça configurações compatíveis com o ritmo do atendimento e evite criar respostas em sequência sem necessidade.

Como criar uma regra de resposta?

O exemplo cria uma resposta de texto para mensagens que contenham “horário”. response_payload contém o texto da resposta. Placeholders documentados incluem {{sender}}, {{chat}}, {{pushName}} e capturas no formato {{match_N}}. Use o token real da instância no header token; o endereço e a credencial abaixo são ilustrativos.

curl -X POST 'https://SEU-DOMINIO/auto-reply/rule' \
  -H 'Content-Type: application/json' \
  -H 'token: SEU_TOKEN' \
  -d '{"name":"Horário de atendimento","match_type":"keywords","match_value":["horário"],"pattern":"","response_type":"text","response_payload":{"text":"Olá {{pushName}}, nosso atendimento funciona em dias úteis."},"scope":"private","allowed_jids":[],"blocked_jids":[],"priority":10,"cooldown_ms":0,"typing_duration_ms":1500,"quoted":false,"simulate_typing":true,"active":true}'

O mesmo corpo pode ser enviado com fetch no Node.js:

const body = {name:"Horário de atendimento",match_type:"keywords",match_value:["horário"],pattern:"",response_type:"text",response_payload:{text:"Olá {{pushName}}, nosso atendimento funciona em dias úteis."},scope:"private",allowed_jids:[],blocked_jids:[],priority:10,cooldown_ms:0,typing_duration_ms:1500,quoted:false,simulate_typing:true,active:true};
const response = await fetch('https://SEU-DOMINIO/auto-reply/rule', {method:'POST', headers:{'Content-Type':'application/json', token:'SEU_TOKEN'}, body:JSON.stringify(body)});
console.log(await response.json());

Em Python com requests:

import requests

body = {"name":"Horário de atendimento","match_type":"keywords","match_value":["horário"],"pattern":"","response_type":"text","response_payload":{"text":"Olá {{pushName}}, nosso atendimento funciona em dias úteis."},"scope":"private","allowed_jids":[],"blocked_jids":[],"priority":10,"cooldown_ms":0,"typing_duration_ms":1500,"quoted":False,"simulate_typing":True,"active":True}
response = requests.post('https://SEU-DOMINIO/auto-reply/rule', headers={'token':'SEU_TOKEN'}, json=body)
print(response.json())

Em PHP com cURL:

<?php
$body = ['name'=>'Horário de atendimento','match_type'=>'keywords','match_value'=>['horário'],'pattern'=>'','response_type'=>'text','response_payload'=>['text'=>'Olá {{pushName}}, nosso atendimento funciona em dias úteis.'],'scope'=>'private','allowed_jids'=>[],'blocked_jids'=>[],'priority'=>10,'cooldown_ms'=>0,'typing_duration_ms'=>1500,'quoted'=>false,'simulate_typing'=>true,'active'=>true];
$curl = curl_init('https://SEU-DOMINIO/auto-reply/rule');
curl_setopt_array($curl, [CURLOPT_POST=>true, CURLOPT_RETURNTRANSFER=>true, CURLOPT_HTTPHEADER=>['Content-Type: application/json','token: SEU_TOKEN'], CURLOPT_POSTFIELDS=>json_encode($body)]);
echo curl_exec($curl);
curl_close($curl);

O corpo é o mesmo nos quatro clientes. Authorization: Bearer SEU_TOKEN também é aceito no lugar do header token. Em respostas rápidas, shortCut e text são os campos que o modelo precisa ter; um identificador é gerado quando id não é enviado. Use /quickreply/showall para listar o que foi guardado.

Como ajustar regras e conteúdo sem surpresas?

Use GET /auto-reply/settings para ler as opções globais: simulate_typing, typing_duration_ms, global_cooldown_ms e multi_match. O POST aceita esses campos e grava os valores enviados; campos omitidos assumem valores padrão do objeto. Na prática, envie de forma explícita as opções que deseja controlar e leia a resposta para confirmar a configuração retornada.

Para uma regra existente, use GET antes de PUT para conservar campos que ainda importam. O toggle recebe {"active":true} ou {"active":false}. O corpo de criação e atualização usa campos como name, match_type, match_value, pattern, response_type e response_payload; o tipo de resposta pode ser text, media, location, contact ou interactive. O objeto de conteúdo precisa corresponder ao tipo selecionado.

text pode incluir placeholders. Respostas de mídia, localização, contato e menu dependem dos campos próprios desses conteúdos. Se o campo não estiver claro para o seu caso, a documentação da API GoZAP é o lugar para conferir o contrato antes de integrar. Para o fluxo geral de envio, veja também grupos, comunidades, canais e status pela API e o guia de eventos e webhooks GoZAP.

Toda API não oficial opera fora dos termos do WhatsApp e tem risco de restrição; a GoZAP não garante contra bloqueio. Planeje a automação com mensagens esperadas, saída clara para atendimento humano e uma forma de desligar regras caso o conteúdo precise ser revisto.

Quando não escolher a GoZAP

Não escolha a GoZAP se sua operação exige exclusivamente a plataforma oficial da Meta, ou se a equipe depende de uma rota automática de exclusão de respostas rápidas. A GoZAP oferece conexão pelos modos Web e Mobile, ambos fora da API oficial da Meta. O contrato de /quickreply aqui descrito salva e lista modelos, sem gatilho automático por atalho documentado. Se esse requisito for central, confirme que a solução escolhida oferece o fluxo que sua equipe pretende operar.

Para planejar autenticação e operações, leia a referência da API GoZAP. Avalie também o guia de risco de uso de API não oficial.