Envie mensagens pela API WhatsApp WTOCRM: curl e Node.js

Para enviar uma mensagem pelo WhatsApp com o WTOCRM, faça um POST com o número do destinatário e textMessage.text para https://waapi.wtocrm.com/message/sendText/{instanceName}, usando o cabeçalho apikey. Os exemplos usam seu backend e uma instância já conectada. Você não precisa de SDK. Use este ponto de partida para adicionar uma atualização ao seu SaaS ou criar uma automação para um cliente. Primeiro, confirme que uma mensagem chega ao seu próprio celular de teste. Depois acrescente anexos, retornos de eventos e tentativas controladas.

Pontos principais

Envie texto com um POST JSON para /message/sendText/{instanceName} e autentique com apikey.

Crie e conecte a instância antes. Receber um QR code ou código de pareamento não confirma a conexão.

Upload de mídia, modelos comerciais aprovados e links wa.me resolvem tarefas diferentes.

Corrija as credenciais no 401; examine a resposta e reduza a pressão de requisições no 429. Confira envios de resultado incerto antes de repetir.

Módulo de backend, gateway translúcido e celular conectados por uma rota de mensagem em uma ilustração conceitual — Ilustração conceitual de um backend enviando uma mensagem por um gateway de API até um celular; não é uma captura do produto.

Envie sua primeira mensagem de texto com curl ou Node.js

Antes de executar os exemplos, crie uma instância, conecte por QR code ou código de pareamento e confirme instance.state igual a open pelo endpoint de estado da conexão. Essas etapas descrevem o acesso via protocolo de dispositivo vinculado do WTOCRM, separado da configuração oficial da WhatsApp Business Platform / Cloud API da Meta. Use um terminal com curl ou Node.js 22 ou posterior para o exemplo JavaScript. O Node inclui fetch nativo. Mantenha as credenciais no backend. Defina estas variáveis no terminal que executará o exemplo, substituindo os três valores:

export WTO_API_KEY='YOUR_API_KEY'
export WTO_INSTANCE='YOUR_CONNECTED_INSTANCE'
export WTO_TO='COUNTRY_CODE_AND_YOUR_TEST_NUMBER'

Informe seu próprio número de teste do WhatsApp com código do país e apenas dígitos, sem +, espaços ou pontuação. As variáveis configuram os exemplos; não criam nem conectam uma instância. No aplicativo em produção, injete a chave pelo mecanismo de gestão de segredos que você já utiliza.

curl: uma requisição POST

A referência de envio de texto define esta estrutura:

curl --request POST "https://waapi.wtocrm.com/message/sendText/${WTO_INSTANCE}" \
  --header "apikey: ${WTO_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data "{\"number\":\"${WTO_TO}\",\"textMessage\":{\"text\":\"WTOCRM API test\"}}"

Depois da preparação, esta é a requisição mínima para enviar o texto fixo de teste. A referência documenta HTTP 200 e os campos de resposta key, message e status. Examine o retorno real e confira o celular de destino: o resultado da API não comprova a entrega final.

Node.js: fetch nativo, sem SDK

Salve o código como send-message.mjs e execute node send-message.mjs no terminal configurado:

const response = await fetch(`https://waapi.wtocrm.com/message/sendText/${encodeURIComponent(process.env.WTO_INSTANCE)}`, {
  method: 'POST',
  headers: { apikey: process.env.WTO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ number: process.env.WTO_TO, textMessage: { text: 'WTOCRM API test' } })
});
const body = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${body}`);
console.log(body);

fetch não lança uma exceção apenas porque o servidor devolve 401 ou 429. A verificação explícita de response.ok transforma essas respostas em erros que você pode tratar. Durante a investigação, guarde a resposta completa em um registro de desenvolvimento restrito; remova credenciais, números e conteúdo de mensagens antes de compartilhar registros.

Entenda o endpoint REST e a URL

Um endpoint identifica uma operação pela combinação de método HTTP e URL. Para enviar texto pelo WTOCRM, use estas partes juntas:

Parte	Valor	Função
Método	`POST`	Submeter uma operação de mensagem
URL base da API	`https://waapi.wtocrm.com`	Acessar o serviço WTO WA API
Caminho	`/message/sendText/{instanceName}`	Selecionar o envio de texto de uma instância
Autenticação	Cabeçalho `apikey`	Fornecer uma chave autorizada para a instância
Corpo JSON	`number`, `textMessage.text`	Definir destinatário e mensagem

Substitua {instanceName}; não envie as chaves literalmente. Use o nome da instância, não o telefone do destinatário. Abrir a URL no navegador normalmente faz um GET sem o cabeçalho ou o corpo JSON necessário, e não executa esta operação POST. Esta URL e esta estrutura pertencem ao WTOCRM. Não as misture com exemplos de token Bearer, caminhos da Graph API ou campos de outros provedores. O WTOCRM publica este guia; as referências de produto vinculadas definem os contratos atuais das requisições. Como verificamos os exemplos: em 3 de novembro de 2026, verificamos os trechos de curl e Node.js com um serviço HTTP simulado localmente e Node.js v24.22.2. Os testes cobriram caminhos, apikey, JSON de texto, upload multipart e o tratamento de HTTP 200/401/429 no Node. Não enviamos mensagens reais pelo WhatsApp.

Escolha texto, mídia ou modelos de mensagem

Escolha o formato de acordo com o conteúdo e o canal conectado, em vez de trocar o endpoint até conseguir uma resposta.

Tipo	Quando usar	Referência WTOCRM	O que conferir primeiro
Texto	Uma resposta em texto ou mensagem de teste	`/message/sendText/{instanceName}`	Instância conectada e campos JSON documentados
Mídia	PDF de cotação, imagem, vídeo ou áudio	`/message/sendMedia/{instanceName}`	Formato de upload e tipo de mídia
Modelo	Notificação comercial em um canal que exige modelos aprovados	`/message/sendTemplate/{instanceName}`	Suporte do canal, aprovação e parâmetros exigidos pelo provedor

Envie mídia com formulário multipart

A referência atual de mídia exige number, mediatype e um arquivo binário em media. Para um PDF que você preparou como quote.pdf no diretório atual:

curl --request POST "https://waapi.wtocrm.com/message/sendMedia/${WTO_INSTANCE}" \
  --header "apikey: ${WTO_API_KEY}" \
  --form "number=${WTO_TO}" \
  --form 'mediatype=document' \
  --form 'media=@./quote.pdf;type=application/pdf'

Deixe o curl definir o delimitador multipart. Não reutilize Content-Type: application/json do exemplo de texto. Os tipos documentados são image, video, audio e document; também há os campos opcionais caption e fileName. O exemplo envia seu arquivo local, sem presumir que media aceite uma URL remota.

Confirme o suporte a modelos antes de implementar

Um modelo comercial aprovado é diferente de um texto reutilizável salvo no aplicativo. Use modelos quando o canal comercial escolhido exigir esse formato aprovado para a notificação que você quer enviar. Um link wa.me ou uma requisição de texto comum não substitui a aprovação do modelo. O WTOCRM lista um endpoint de mensagem de modelo, mas o contrato público atual apresenta number e textMessage.text sem definir o nome, o idioma ou o mapeamento de componentes de um modelo aprovado. Também não especifica quais modos de conexão aceitam a operação. Confirme o canal e os parâmetros antes de implementar; trocar sendText por sendTemplate não é uma conversão verificada. Para configurar o canal Cloud API oficial no WTOCRM, siga a configuração separada do canal WhatsApp. Não presuma que a instância vinculada por QR code deste exemplo tenha o mesmo fluxo ou as mesmas capacidades de modelos.

Diferencie três sentidos de link da API WhatsApp

“Link da API WhatsApp” pode indicar três destinos. Identifique quem abre o link e qual ação ele deve executar.

Sentido	Exemplo ou destino	O que faz
Endpoint REST	`https://waapi.wtocrm.com/message/sendText/{instanceName}`	Seu backend envia uma requisição estruturada de mensagem
Link para iniciar conversa	`https://wa.me/<international-number>?text=<encoded-text>`	Uma pessoa abre o chat com texto opcional preenchido e decide se vai enviar
Entrada de vinculação da conta ou canal	Guia de conexão ou configurações de canais do WTOCRM	A pessoa responsável vincula um dispositivo ou autoriza o canal escolhido

Para um link wa.me, use o número internacional completo sem + ou pontuação e codifique o texto opcional para URL. O link não autentica seu backend nem envia uma mensagem automaticamente. Na vinculação de dispositivos, GET /instance/connect/{instanceName} solicita as informações de QR code ou pareamento; a pessoa responsável ainda precisa concluir a etapa no celular. Um link de vinculação do canal é uma entrada de configuração, não uma URL universal de envio. Proteja QR codes e códigos de pareamento e siga o fluxo de conexão documentado.

Resolva 401 e 429 sem duplicar envios

Comece registrando o status HTTP, os cabeçalhos e o corpo da resposta. Durante a investigação, acrescente --include à requisição curl acima; no Node, examine response.status, response.headers e body. Remova dados pessoais antes de compartilhar o registro.

401: corrija a autenticação antes de repetir

As referências de texto e mídia do WTOCRM definem 401 como autenticação ausente ou inválida. Verifique se WTO_API_KEY está definida, se o cabeçalho se chama apikey e se a chave pertence ao ambiente de destino e tem autorização para a instância. Se houver um proxy, confirme que ele encaminha esse cabeçalho. A falta do nome da instância é um problema separado de roteamento. Essas referências definem HTTP 403 como permissão insuficiente, enquanto 404 pode indicar uma instância desconhecida. Repetir a mesma requisição sem autorização não corrige esses problemas.

429: reduza a pressão e siga a resposta

HTTP 429 significa excesso de requisições em um período. O padrão permite o cabeçalho Retry-After, mas não o exige. Se o serviço o fornecer, respeite a espera indicada. Caso contrário, use espera progressiva com limite máximo, variação aleatória, número finito de tentativas e uma fila que limite a concorrência. As referências de envio do WTOCRM ainda não publicam um contrato para 429 nem uma franquia fixa de requisições por segundo. Esta é uma orientação geral para um 429 devolvido pelo caminho real da API, gateway ou provedor. Examine o corpo e os cabeçalhos para identificar a origem; não importe limites numéricos de outros provedores nem suponha que repetir contorne uma restrição da conta. Se você desenvolve automações para clientes, coordene os processos que compartilham a mesma conta ou franquia de serviço. Processos independentes repetindo ao mesmo tempo podem manter a pressão elevada. Preserve a identidade da tarefa original e pare quando o limite configurado de tentativas acabar.

Separe entrada inválida, timeout e falhas de entrega

Resultado	Próxima ação
`400`	Compare corpo, formato do destinatário e campos de mídia com a referência
`403`	Verifique permissões da chave; não trate como limitação temporária
`404`	Confira URL base, rota e nome da instância
Timeout ou resposta perdida	Determine se o envio terminou antes de submetê-lo novamente
Resposta de sucesso, mensagem ausente no celular	Confira a conexão e os eventos disponíveis; registre o resultado real

Não presuma um cabeçalho de idempotência: as referências atuais de envio não documentam esse recurso. Seu aplicativo deve registrar tarefas e os identificadores de mensagem retornados, quando disponíveis, e verificar resultados incertos antes de repetir. Um identificador local da tarefa, sozinho, não impede um segundo envio após uma falha de rede ambígua.

Valide uma mensagem e conecte seu fluxo

O primeiro teste deve confirmar três observações: resposta da API, mensagem recebida no celular de teste e uma resposta chegando ao aplicativo. Use a referência de configuração de webhook para selecionar eventos aceitos pela instância e associar o retorno à instância e ao contato corretos. Envie apenas mensagens que os destinatários concordaram em receber. Separe falhas de conexão de falhas de autenticação e valide o comportamento das tentativas antes de adicionar processos ou clientes. Abra o guia de conexão da API WTOCRM para conectar a instância, confirmar open e executar sua primeira requisição de texto.

​Envie sua primeira mensagem de texto com curl ou Node.js

​curl: uma requisição POST

​Node.js: fetch nativo, sem SDK

​Entenda o endpoint REST e a URL

​Escolha texto, mídia ou modelos de mensagem

​Envie mídia com formulário multipart

​Confirme o suporte a modelos antes de implementar

​Diferencie três sentidos de link da API WhatsApp

​Resolva 401 e 429 sem duplicar envios

​401: corrija a autenticação antes de repetir

​429: reduza a pressão e siga a resposta

​Separe entrada inválida, timeout e falhas de entrega

​Valide uma mensagem e conecte seu fluxo