Para enviar texto com a API de WhatsApp da StackZap, use o endpoint de mensagens da instância conectada. A solicitação precisa levar sua API Key, o identificador da instância e os campos to e text no corpo JSON.

Exemplo com cURL

curl -X POST "$STACKZAP_API_URL/v1/instances/$STACKZAP_INSTANCE_ID/messages/text" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $STACKZAP_API_KEY" \
  -d '{"to":"[email protected]","text":"Olá! Esta é uma mensagem de teste."}'

Defina as variáveis com a URL, o ID e a chave do seu ambiente. No StackZap Cloud, encontre esses dados no painel do ambiente. No self-hosted, use o endereço e a credencial configurados pelo operador.

Campos principais

  • to: identificador do destinatário no formato aceito pela versão da API; os exemplos da referência usam JID, como [email protected].
  • text: conteúdo textual que será enviado.
  • preview: campo opcional documentado para controlar a prévia de link em versões que o aceitam.

O endpoint só envia quando a instância existe e está conectada. A resposta informa o resultado da solicitação; consulte o status e os eventos documentados para acompanhar o fluxo posterior. Não trate uma resposta HTTP como confirmação de leitura.

Planeje o envio antes da chamada

Antes de integrar o endpoint ao seu produto, defina qual evento de negócio autoriza a mensagem. Por exemplo, uma confirmação pode ser enviada depois que um pedido realmente mudou para o estado esperado. Evite enviar uma mensagem sempre que uma tela for aberta ou quando um usuário clicar repetidamente no mesmo botão. Associe cada mensagem a um evento identificável e registre esse vínculo para poder explicar por que o contato recebeu a comunicação.

Separe conteúdo, destinatário e operação. O serviço de negócio decide que mensagem é necessária; um componente de integração formata o telefone, valida os dados e chama a StackZap; outro componente registra o resultado e trata erros. Essa divisão facilita a troca de texto sem espalhar chamadas HTTP pela aplicação. Também permite revisar quem pode acionar o envio, especialmente quando a solicitação vem de um painel administrativo ou agente de IA.

Antes de disparar em produção, verifique se a instância está conectada e se a aplicação usa a URL do ambiente esperado. Em um sistema com homologação e produção, crie configurações distintas. Faça um teste para um número controlado pela equipe e confirme o conteúdo que chegou no aparelho. Não use uma lista de clientes como teste de integração.

Exemplo em cURL com valores de ambiente

O exemplo abaixo mostra a estrutura de uma requisição com os campos to e text documentados para o envio de texto. Confirme o caminho e o identificador da instância na documentação da versão:

curl -X POST "${STACKZAP_BASE_URL}/v1/instances/${STACKZAP_INSTANCE_ID}/messages/text" \
  -H "X-API-Key: ${STACKZAP_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"to":"5521999999999","text":"Sua solicitação foi recebida."}'

Use número de teste autorizado no exemplo e mantenha a chave em variável protegida. O caminho ilustrativo não substitui a referência oficial; versões podem ter nomes ou requisitos diferentes. Se a resposta incluir um identificador da mensagem, armazene-o junto do evento de negócio para relacionar confirmação, webhook e diagnóstico posterior.

Defina a identidade do destinatário

O número deve seguir o formato solicitado pela API da versão instalada. Em geral, sistemas precisam normalizar pontuação, espaços e prefixos antes do envio, mas não invente regra de DDI: valide o país e a origem do contato. Guarde uma representação consistente no banco da sua aplicação e transforme-a para o formato esperado na borda de integração.

Uma validação sintática não prova que o número pertence à pessoa certa nem que ela concordou em receber mensagens. Confirme a origem do telefone no seu fluxo de cadastro, permita correções e evite juntar números de registros diferentes por semelhança. Para atendimento ou notificação, o destinatário deve ter relação com o evento e a finalidade informada. Se a pessoa pedir para parar, registre a preferência e impeça novos envios compatíveis com esse pedido.

Não coloque telefone ou conteúdo de mensagem em logs que todos os operadores possam consultar. Se for preciso investigar uma falha, utilize máscara parcial e um identificador interno. A política de retenção deve considerar a finalidade, os acessos e a legislação aplicável à operação.

Conteúdo claro e adequado ao canal

Uma mensagem transacional funciona melhor quando deixa evidente quem está falando, por que o contato recebeu o texto e qual ação pode tomar. Evite textos vagos, links sem contexto ou comandos que pressionem a pessoa. Se houver uma etapa seguinte, indique-a em linguagem simples e ofereça um canal legítimo para dúvidas. Confira acentos, variáveis, datas, moeda e links antes de habilitar o modelo em produção.

Mensagens personalizadas precisam tratar campos ausentes. Uma saudação com nome em branco ou um valor incorreto reduz confiança; forneça um fallback neutro e valide limites e caracteres. Se o conteúdo vier de um usuário, agente ou sistema externo, escape ou normalize o que a aplicação precisa antes de enviar. Não permita que conteúdo arbitrário transforme uma mensagem de confirmação em uma mensagem promocional sem revisão.

Evite envios duplicados

Uma chamada pode atingir o servidor e a resposta se perder no caminho. Se a aplicação repetir automaticamente a operação, o contato pode receber a mesma mensagem duas vezes. Antes de implementar repetição, confira se a versão oferece chave de idempotência ou outro mecanismo documentado. Se não houver, crie controle no seu sistema: grave o evento de negócio, gere um identificador estável e mantenha o resultado do envio associado a ele.

Um padrão robusto é criar um registro pendente, processar uma tentativa, salvar o retorno e só permitir novo envio depois de uma decisão explícita. Uma restrição única no banco para o evento que origina a mensagem ajuda a impedir cliques duplos. Diferencie falha antes de enviar de resultado desconhecido: um timeout pode ocorrer depois de o provedor ter aceitado a operação. Nessa situação, consulte a confirmação ou os webhooks disponíveis antes de repetir.

Erros e respostas HTTP

Valide a resposta HTTP, o corpo e os campos descritos na documentação. Não trate qualquer resposta sem exceção como confirmação de entrega. A chamada de API pode indicar que a operação foi aceita ou registrada; o estado posterior deve ser acompanhado conforme os eventos que sua instalação oferece.

  • Não autorizado: confira X-API-Key e se a chave pertence ao ambiente chamado.
  • Instância desconectada: pause novas tentativas automáticas e restaure a conexão.
  • Campo inválido: confira telefone, texto, JSON e limite documentado.
  • Timeout ou erro 5xx: registre contexto e determine se o resultado ficou desconhecido antes de repetir.
  • Resposta de sucesso: armazene o identificador de retorno e acompanhe os eventos associados.

Use backoff e limite de tentativas quando a repetição for segura. Uma pausa progressiva evita criar rajadas quando o serviço está indisponível. Não repita erros permanentes, como credencial incorreta ou conteúdo inválido, sem alterar a causa. Respeite limites da conta e as cotas do plano Cloud.

Observabilidade do fluxo

Para cada tentativa, registre o identificador interno do evento, ambiente lógico, instância, status HTTP, duração e eventual identificador retornado pela StackZap. Masque segredos e reduza a presença de números e textos em telemetria. Acompanhe métricas como taxa de falha, idade da fila e mensagens com resultado desconhecido; um painel com esses números permite detectar regressões sem abrir conversas individuais.

O suporte consegue investigar melhor com uma amostra pequena e segura: horário com fuso, ambiente, ID da instância, endpoint, status e request ID se existir. Evite anexar exportações completas, tokens ou listas de destinatários. Na StackZap Cloud, use o widget do ambiente para falar com o time; no self-hosted, o operador deve verificar aplicação, rede, logs e serviços sob seu controle.

Checklist de implantação

  • Documente o evento que autoriza o envio e a finalidade da mensagem.
  • Use URL, chave e instância do ambiente correspondente.
  • Mantenha autenticação somente no backend.
  • Normalize e valide o telefone sem presumir consentimento.
  • Teste conteúdo e destinatário em ambiente controlado.
  • Implemente deduplicação antes de habilitar repetição automática.
  • Trate timeout como resultado potencialmente desconhecido.
  • Acompanhe respostas e webhooks documentados.
  • Oculte dados pessoais e credenciais em logs e tickets.

Crie um contrato interno para o envio

Defina uma interface no seu backend que receba um evento conhecido, não uma rota que permita qualquer pessoa mandar texto livre para qualquer número. A função pode validar finalidade, autorização registrada, formato do destinatário, tamanho do texto, instância e permissão do operador. Esse contrato interno protege a API mesmo que a interface web ou um agente envie parâmetros inesperados.

Guarde uma chave de idempotência no seu domínio, associada ao evento que originou a mensagem. Antes de criar novo envio, confira se o evento já tem uma operação em andamento ou concluída. Se o endpoint não oferecer idempotência para a versão utilizada, essa camada local é especialmente importante. Aplique também uma regra de expiração: uma confirmação atrasada pode ser útil, enquanto um aviso de horário pode perder o sentido.

Revise respostas antes de liberar

Confirme texto, telefone e ambiente numa tela de revisão para ações manuais. Mostre o número parcialmente mascarado e a finalidade. Para mensagens automáticas, crie testes de renderização com valores ausentes, acentos, emojis, links e limites de tamanho. Uma variável não preenchida pode transformar uma mensagem legítima em texto confuso ou revelar um placeholder técnico ao destinatário.

Após publicar uma mudança de template, envie primeiro para a equipe interna. Mantenha histórico da versão do texto e de quem aprovou. Assim, se alguém relatar conteúdo incorreto, você consegue identificar qual versão foi usada sem reproduzir uma campanha.

Torne a operação recuperável

Grave a intenção de envio no banco antes de chamar a API e atualize o registro com o resultado recebido. Se a aplicação parar entre essas duas etapas, um reconciliador pode revisar operações em andamento. Não marque como falha definitiva somente porque o processo local perdeu a conexão; o servidor pode ter aceitado a mensagem.

O reconciliador deve usar IDs fornecidos pela API ou eventos disponíveis para procurar confirmação. Se não houver maneira técnica de concluir, apresente a operação para revisão humana com status “resultado desconhecido”. É mais seguro investigar esse caso do que reenviar automaticamente. Retenha somente os dados necessários e respeite sua política de privacidade.

Faça rollout gradual

Ao liberar uma automação nova, habilite primeiro para uma pequena parte dos eventos autorizados. Monitore erros, duplicidade, respostas e pedidos de saída. Amplie somente quando os resultados estiverem dentro do esperado. Mantenha um interruptor no backend que pause o fluxo sem apagar jobs ou configuração.

Faça um primeiro envio controlado

Antes de ligar o endpoint a uma campanha ou automação, use um número de teste autorizado. Confirme a URL e o ID da instância, valide a resposta JSON e registre o status HTTP sem gravar a API Key em logs. Caso a resposta indique instância desconectada ou corpo inválido, resolva isso antes de tentar novamente.

Confira o schema atual de SendTextRequest, respostas e autenticação na referência da API StackZap. Os nomes e formatos da documentação da versão instalada devem prevalecer sobre exemplos copiados de outro ambiente.

Diferencie conteúdo transacional e promocional

Uma atualização sobre ação iniciada pela pessoa tem contexto diferente de uma divulgação comercial. Separe essas finalidades no código e no registro de autorização. Não use uma confirmação de pedido para inserir oferta não relacionada sem avaliar se a pessoa espera esse conteúdo. Se o usuário pedir para parar comunicações promocionais, mantenha a escolha nos jobs futuros.

Essa separação também facilita medir a operação: identifique qual fluxo originou a mensagem, quem é responsável e qual regra determina a frequência. Se uma automação muda de finalidade, revise autorização, conteúdo, retenção e termos antes de reutilizar a mesma lista.

Faça rollout gradual

Ao liberar automação nova, habilite primeiro para uma pequena parte dos eventos autorizados. Monitore erros, duplicidade, respostas e pedidos de saída. Amplie somente quando os resultados estiverem dentro do esperado. Mantenha um interruptor no backend que pause o fluxo sem apagar jobs ou configuração.

Revise a resposta da chamada

Valide o status HTTP e o corpo JSON conforme o contrato do endpoint. Armazene o ID retornado quando existir e associe-o ao evento de negócio, sem assumir que uma resposta de aceitação significa entrega. Se a resposta vier vazia ou não puder ser interpretada, preserve status e request ID para diagnóstico. Não faça retry antes de entender se a operação foi processada; um timeout ou erro de parsing pode ocorrer depois de o servidor aceitar a solicitação.