> ## Documentation Index > Fetch the complete documentation index at: https://docs.wtocrm.com/llms.txt > Use this file to discover all available pages before exploring further. # Envie mensagens pela API WhatsApp WTOCRM: curl e Node.js > Envie sua primeira mensagem pela API WhatsApp com curl ou Node.js. Veja o endpoint REST, escolha texto, mídia ou modelos e resolva respostas 401 e 429. **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](https://assets.wtocrm.com/blog/2026/send-whatsapp-message-api/cover-e5bfbefd61.webp) 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](https://docs.wtocrm.com/pt-BR/waapi/create-instance.md), [conecte por QR code ou código de pareamento](https://docs.wtocrm.com/pt-BR/waapi/connect-instance.md) e confirme `instance.state` igual a `open` pelo [endpoint de estado da conexão](https://docs.wtocrm.com/pt-BR/waapi/get-connection-state.md). 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](https://nodejs.org/docs/latest-v22.x/api/globals.html#fetch). Mantenha as credenciais no backend. Defina estas variáveis no terminal que executará o exemplo, substituindo os três valores: ```bash theme={null} 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](https://docs.wtocrm.com/pt-BR/waapi/send-text-message.md) define esta estrutura: ```bash theme={null} 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: ```javascript theme={null} 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](https://wtocrm.com) 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](https://docs.wtocrm.com/pt-BR/waapi/send-media-message.md) exige `number`, `mediatype` e um arquivo binário em `media`. Para um PDF que você preparou como `quote.pdf` no diretório atual: ```bash theme={null} 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](https://docs.wtocrm.com/pt-BR/waapi/send-template-message.md), 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](https://docs.wtocrm.com/pt-BR/user-guides/channels/whatsapp-setup.md). 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/?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](https://www.rfc-editor.org/rfc/rfc6585.html#section-4) 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](https://docs.wtocrm.com/pt-BR/waapi/set-webhook.md) 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](https://docs.wtocrm.com/pt-BR/waapi/connect-instance.md)** para conectar a instância, confirmar `open` e executar sua primeira requisição de texto. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.