Ver planos

Envio de Mensagens

Envie mensagens de texto e arquivos via API para WhatsApp e outros canais de comunicação.

Acelere sua integração!

Baixe nossa coleção do Postman com os envios desta página já pré-configurados — texto síncrono, texto assíncrono e arquivo.

Baixar coleção Postman 3 requisições · JSON · Collection v2.1
Importante: você precisa de um access_token válido para usar este endpoint. Consulte a documentação de autenticação para obter seu token.

Como funciona

O endpoint de envio de mensagens permite enviar mensagens programaticamente através dos canais configurados na sua conta Atys. Atualmente, suportamos:

WhatsApp

Envio de texto e arquivos pelos canais conectados.

Telegram

Em breve.

Instagram

Em breve.

Enviar mensagem

Para enviar uma mensagem, faça uma requisição POST para https://api.atys.pro/api/api-send-message com o access_token no header Authorization.

POST https://api.atys.pro/api/api-send-message Enviar mensagem de texto ou arquivo

Headers obrigatórios

HeaderValorDescrição
AuthorizationBearer YOUR_ACCESS_TOKENToken de autenticação obtido via login
Content-Typeapplication/json ou multipart/form-dataUse multipart/form-data quando enviar arquivo
Acceptapplication/jsonTipo de resposta esperada

Enviar mensagem de texto

Para enviar uma mensagem de texto simples, use Content-Type: application/json e inclua os seguintes parâmetros:

Parâmetros do body (JSON)

ParâmetroTipoObrigatórioDescriçãoExemplo
platformstring Sim Plataforma de envio. Aceita whatsapp (não oficial) e ofc_whatsapp (oficial, com regras próprias — veja a API Oficial) whatsapp
sender_keystring Sim Telefone do remetente (número do canal WhatsApp já cadastrado e conectado na sua conta Atys) 5511999999999
contact_keystring Sim Telefone do destinatário. Sufixos @g.us, @c.us, @lid e @s.whatsapp.net são removidos automaticamente se enviados 5511988888888
contact_is_groupboolean Não Se o destinatário é um grupo (true) ou contato individual (false). Default: false false
enqueueboolean Não Modo de processamento — veja o alerta abaixo. Default: false (síncrono) false
textstring Sim* Texto da mensagem Olá! Como posso ajudar?
filefile Sim* Arquivo a ser enviado (imagem, PDF, vídeo, etc.) arquivo.pdf
* Importante: você deve fornecer text OU file. Pelo menos um dos dois é obrigatório.
enqueue — síncrono vs. assíncrono: com enqueue=false (o default) a requisição só retorna depois que a mensagem foi de fato enviada ao WhatsApp — a resposta já confirma entrega (ou o erro real de envio), mas o tempo de resposta acompanha o round-trip até o WhatsApp. Com enqueue=true a resposta é imediata (200 com a mensagem enfileirada), mas só confirma que o envio foi aceito para processamento — não que chegou ao destinatário. Escolha false quando precisa confirmar entrega na hora; escolha true para envios em lote onde a latência da resposta importa mais que a confirmação síncrona.

Exemplos de código — mensagem de texto

JavaScript (Fetch API)
const response = await fetch('https://api.atys.pro/api/api-send-message', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SEU_ACCESS_TOKEN',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    platform: 'whatsapp',
    sender_key: '5511999999999',
    contact_key: '5511988888888',
    contact_is_group: false,
    text: 'Olá! Como posso ajudar você hoje?'
  })
});

const data = await response.json();
console.log(data);

Enviar mensagem com arquivo

Para enviar um arquivo (imagem, PDF, vídeo, documento, etc.), use Content-Type: multipart/form-data:

Tipos de arquivo suportados: imagens (jpg, png, gif), documentos (pdf, doc, docx, xlsx), vídeos (mp4, avi), áudios (mp3, ogg), entre outros.

Exemplos de código — mensagem com arquivo

JavaScript (FormData)
// Enviar arquivo com FormData
const formData = new FormData();
formData.append('platform', 'whatsapp');
formData.append('sender_key', '5511999999999');
formData.append('contact_key', '5511988888888');
formData.append('contact_is_group', 'false');
formData.append('text', 'Segue o documento solicitado');
formData.append('file', fileInput.files[0]); // arquivo do input type="file"

const response = await fetch('https://api.atys.pro/api/api-send-message', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SEU_ACCESS_TOKEN',
    'Accept': 'application/json'
    // NÃO incluir Content-Type, o navegador define automaticamente
  },
  body: formData
});

const data = await response.json();

Resposta de sucesso

O formato da resposta depende do parâmetro enqueue enviado na requisição.

Com enqueue=true

200 OK — mensagem enfileirada
{
  "message": "Whatsapp message enqueued successfully"
}
Este 200 confirma apenas que a mensagem foi aceita e agendada. O envio real acontece depois, em segundo plano — esta resposta não confirma entrega ao destinatário.

Com enqueue=false (default)

A requisição aguarda o envio real ao WhatsApp antes de responder. Em caso de sucesso, a resposta é o retorno bruto do serviço de envio:

200 OK — mensagem enviada
{
  "Status": true,
  "Channel": "5511999999999",
  "Message": "Message sended successfully",
  "Data": {
    "ExternalID": "3EB0C767D26A1D4F8E3D",
    "PlatformAt": "2026-08-18 10:32:15",
    "Response": { }
  }
}
Data.ExternalID é o ID da mensagem no WhatsApp — guarde-o se precisar correlacionar a mensagem depois. Data.Response é o payload interno do serviço de envio (estrutura de debug, não documentada como contrato estável — não recomendamos parsear campos dentro dela).
Caso de borda: a mensagem pode ser entregue ao WhatsApp e ainda assim falhar ao ser salva localmente para exibição na interface do Atys. Há duas respostas possíveis, e em ambas a mensagem já foi entregue — não reenvie:
  • 200 com {"status": true, "message": "Message delivered, but it could not be persisted locally for the UI", "external_id": "..."}
  • 500 com um texto informando que o envio ocorreu mas houve erro ao gravar a mensagem no banco

Erros comuns

509 Produto de envios não contratado

Causa: sua empresa não possui o produto de envios de WhatsApp via API contratado no plano.

Solução: entre em contato com o atendimento Atys para habilitar o envio via API.

509 Limite de envios do plano atingido

Causa: a cota de mensagens do seu plano foi esgotada.

Solução: faça upgrade do plano para continuar enviando mensagens via API.

400 Invalid platform / Platform not allowed yet

Causa: "message": "Invalid platform" quando o valor de platform não é reconhecido; "message": "Platform not allowed yet" quando é um valor reconhecido mas ainda não suportado por este endpoint (telegram, instagram, messenger).

Solução: use "platform": "whatsapp" para o canal não oficial ou "platform": "ofc_whatsapp" para o oficial. As demais plataformas ainda não estão disponíveis neste endpoint.

{
  "message": "Invalid platform"
}
400 Sender key is required

Causa: o parâmetro sender_key está vazio ou não foi fornecido.

Solução: informe o telefone do canal remetente no formato 5511999999999 (código do país + DDD + número).

400 Contact key is required

Causa: o parâmetro contact_key está vazio ou não foi fornecido.

Solução: informe o telefone do destinatário no formato 5511988888888.

400 Text or file is required

Causa: nenhum texto ou arquivo foi fornecido.

Solução: forneça pelo menos um dos dois: o parâmetro text com a mensagem ou o parâmetro file com o arquivo.

400 sender_key not found

Causa: o número fornecido em sender_key não está cadastrado como canal na sua conta.

Solução: verifique se o número está correto e se o canal WhatsApp está configurado e ativo na plataforma Atys.

400 Sem permissão para enviar ao grupo

Causa: apenas relevante quando contact_is_group=true. O número de sender_key não é membro do grupo, ou o grupo não permite mensagens de não-administradores.

Solução: verifique se o número remetente participa do grupo e tem permissão de envio.

404 Contact not found on WhatsApp

Causa: o número em contact_key não tem WhatsApp ativo.

Solução: confirme que o destinatário realmente usa WhatsApp antes de enviar.

503 Canal não autenticado ou indisponível

Causa: o número do sender_key está desconectado do WhatsApp (sessão perdida) ou o serviço de envio está temporariamente fora do ar.

Solução: verifique na plataforma Atys se o canal WhatsApp continua conectado. Se caiu, reconecte escaneando o QR code novamente.

503 Canal temporariamente restrito pelo WhatsApp

Causa: o WhatsApp aplicou uma restrição temporária de envio ao número (proteção antispam da própria plataforma WhatsApp).

Solução: a mensagem é reagendada automaticamente para nova tentativa quando a restrição expirar — não é necessário reenviar manualmente. Reduza o volume/frequência de envios deste número.

502 Failed to send message

Causa: o serviço de envio respondeu, mas reportou falha ao entregar a mensagem ao WhatsApp.

Solução: verifique o campo details da resposta para a causa específica. Tente novamente; se persistir, contate o suporte.

500 Erro interno durante o envio

Causa: falha inesperada durante a verificação do contato, o envio propriamente dito ou a persistência da mensagem. Se ocorrer após o envio já ter sido confirmado ao WhatsApp, a mensagem foi entregue mesmo com o erro 500 — o problema foi apenas em salvá-la para exibição na interface do Atys.

Solução: se precisar ter certeza sobre a entrega em caso de 500, consulte o suporte Atys informando o horário e o contact_key usado.

401 Unauthenticated

Causa: o token de autenticação está inválido, expirado ou não foi fornecido.

Solução: obtenha um novo access_token através do endpoint de autenticação.

Dicas e boas práticas

Recomendações
  • Valide os números de telefone antes de enviar.
  • Use formato internacional sem caracteres especiais.
  • Mantenha mensagens curtas e objetivas.
  • Teste em ambiente de desenvolvimento primeiro.
  • Implemente retry logic para falhas temporárias.
  • Monitore os logs de envio na plataforma.
Limitações
  • Tamanho máximo de arquivo: 16 MB.
  • O WhatsApp tem limite de caracteres (4096).
  • Respeite as regras do WhatsApp Business.
  • Evite spam ou mensagens não solicitadas.
  • Rate limits podem ser aplicados.
  • Telegram e Instagram em breve.

Recebemos seu contato!

Um especialista da Atys vai falar com você em breve para agendar a demonstração.

Agendar demonstração

Em 20 minutos um especialista mostra a Atys na sua realidade.

BR +55