Envio de Mensagens API
Envie mensagens de texto e arquivos via API para WhatsApp e outros canais de comunicação.
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 que você envie mensagens programaticamente através dos canais configurados na sua conta Atys. Atualmente, suportamos:
Envio de texto e arquivos pelos canais conectados
Telegram
Em breve
Em breve
Enviar Mensagem
Para enviar uma mensagem, faça uma requisição POST para o endpoint https://api.atys.pro/api/api-send-message com o access_token no header Authorization.
https://api.atys.pro/api/api-send-message
Enviar mensagem de texto ou arquivo
Headers Obrigatórios
| Header | Valor | Descrição |
|---|---|---|
Authorization |
Bearer YOUR_ACCESS_TOKEN | Token de autenticação obtido via login |
Content-Type |
application/json ou multipart/form-data | Use multipart/form-data quando enviar arquivo |
Accept |
application/json | Tipo 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âmetro | Tipo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|---|
platform |
string | ✅ Sim | Plataforma de envio. Aceita whatsapp (não oficial) e ofc_whatsapp (oficial, com regras próprias — veja a API Oficial) |
whatsapp |
sender_key |
string | ✅ Sim | Telefone do remetente (número do canal WhatsApp já cadastrado e conectado na sua conta Atys) | 5511999999999 |
contact_key |
string | ✅ Sim | Telefone do destinatário. Sufixos @g.us, @c.us, @lid e @s.whatsapp.net são removidos automaticamente se enviados |
5511988888888 |
contact_is_group |
boolean | ❌ Não | Se o destinatário é um grupo (true) ou contato individual (false). Default: false |
false |
enqueue |
boolean | ❌ Não | Modo de processamento — veja o alerta abaixo. Default: false (síncrono) |
false |
text |
string | ⚠️ Sim* | Texto da mensagem | Olá! Como posso ajudar? |
file |
file | ⚠️ Sim* | Arquivo a ser enviado (imagem, PDF, vídeo, etc) | arquivo.pdf |
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
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);
import requests
response = requests.post(
'https://api.atys.pro/api/api-send-message',
headers={
'Authorization': 'Bearer SEU_ACCESS_TOKEN',
'Content-Type': 'application/json',
'Accept': 'application/json'
},
json={
'platform': 'whatsapp',
'sender_key': '5511999999999',
'contact_key': '5511988888888',
'contact_is_group': False,
'text': 'Olá! Como posso ajudar você hoje?'
}
)
data = response.json()
print(data)
<?php
$ch = curl_init('https://api.atys.pro/api/api-send-message');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer SEU_ACCESS_TOKEN',
'Content-Type: application/json',
'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'platform' => 'whatsapp',
'sender_key' => '5511999999999',
'contact_key' => '5511988888888',
'contact_is_group' => false,
'text' => 'Olá! Como posso ajudar você hoje?'
]));
$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
print_r($data);
?>
<?php
// composer require guzzlehttp/guzzle
use GuzzleHttp\Client;
$client = new Client();
$response = $client->post('https://api.atys.pro/api/api-send-message', [
'headers' => [
'Authorization' => 'Bearer SEU_ACCESS_TOKEN',
'Content-Type' => 'application/json',
'Accept' => 'application/json'
],
'json' => [
'platform' => 'whatsapp',
'sender_key' => '5511999999999',
'contact_key' => '5511988888888',
'contact_is_group' => false,
'text' => 'Olá! Como posso ajudar você hoje?'
]
]);
$data = json_decode($response->getBody(), true);
print_r($data);
?>
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)
func main() {
payload := map[string]interface{}{
"platform": "whatsapp",
"sender_key": "5511999999999",
"contact_key": "5511988888888",
"contact_is_group": false,
"text": "Olá! Como posso ajudar você hoje?",
}
jsonData, _ := json.Marshal(payload)
req, _ := http.NewRequest(
"POST",
"https://api.atys.pro/api/api-send-message",
bytes.NewBuffer(jsonData),
)
req.Header.Set("Authorization", "Bearer SEU_ACCESS_TOKEN")
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Accept", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
curl -X POST https://api.atys.pro/api/api-send-message \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"platform": "whatsapp",
"sender_key": "5511999999999",
"contact_key": "5511988888888",
"contact_is_group": false,
"text": "Olá! Como posso ajudar você hoje?"
}'
Enviar Mensagem com Arquivo
Para enviar um arquivo (imagem, PDF, vídeo, documento, etc), use Content-Type: multipart/form-data:
Exemplos de Código - Mensagem com Arquivo
// 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();
import requests
files = {
'file': open('documento.pdf', 'rb')
}
data = {
'platform': 'whatsapp',
'sender_key': '5511999999999',
'contact_key': '5511988888888',
'contact_is_group': 'false',
'text': 'Segue o documento solicitado'
}
response = requests.post(
'https://api.atys.pro/api/api-send-message',
headers={
'Authorization': 'Bearer SEU_ACCESS_TOKEN',
'Accept': 'application/json'
},
data=data,
files=files
)
result = response.json()
print(result)
<?php
$ch = curl_init('https://api.atys.pro/api/api-send-message');
$data = [
'platform' => 'whatsapp',
'sender_key' => '5511999999999',
'contact_key' => '5511988888888',
'contact_is_group' => 'false',
'text' => 'Segue o documento solicitado',
'file' => new CURLFile('/path/to/documento.pdf')
];
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer SEU_ACCESS_TOKEN',
'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
$response = curl_exec($ch);
$result = json_decode($response, true);
curl_close($ch);
print_r($result);
?>
<?php
// composer require guzzlehttp/guzzle
use GuzzleHttp\Client;
$client = new Client();
$response = $client->post('https://api.atys.pro/api/api-send-message', [
'headers' => [
'Authorization' => 'Bearer SEU_ACCESS_TOKEN',
'Accept' => 'application/json'
],
'multipart' => [
[
'name' => 'platform',
'contents' => 'whatsapp'
],
[
'name' => 'sender_key',
'contents' => '5511999999999'
],
[
'name' => 'contact_key',
'contents' => '5511988888888'
],
[
'name' => 'contact_is_group',
'contents' => 'false'
],
[
'name' => 'text',
'contents' => 'Segue o documento solicitado'
],
[
'name' => 'file',
'contents' => fopen('/path/to/documento.pdf', 'r'),
'filename' => 'documento.pdf'
]
]
]);
$result = json_decode($response->getBody(), true);
print_r($result);
?>
package main
import (
"bytes"
"fmt"
"io"
"mime/multipart"
"net/http"
"os"
)
func main() {
// Criar buffer para multipart
var b bytes.Buffer
writer := multipart.NewWriter(&b)
// Adicionar campos de texto
writer.WriteField("platform", "whatsapp")
writer.WriteField("sender_key", "5511999999999")
writer.WriteField("contact_key", "5511988888888")
writer.WriteField("contact_is_group", "false")
writer.WriteField("text", "Segue o documento solicitado")
// Adicionar arquivo
file, err := os.Open("/path/to/documento.pdf")
if err != nil {
panic(err)
}
defer file.Close()
part, err := writer.CreateFormFile("file", "documento.pdf")
if err != nil {
panic(err)
}
io.Copy(part, file)
writer.Close()
// Criar requisição
req, err := http.NewRequest(
"POST",
"https://api.atys.pro/api/api-send-message",
&b,
)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer SEU_ACCESS_TOKEN")
req.Header.Set("Content-Type", writer.FormDataContentType())
req.Header.Set("Accept", "application/json")
// Enviar requisição
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
curl -X POST https://api.atys.pro/api/api-send-message \ -H "Authorization: Bearer SEU_ACCESS_TOKEN" \ -H "Accept: application/json" \ -F "platform=whatsapp" \ -F "sender_key=5511999999999" \ -F "contact_key=5511988888888" \ -F "contact_is_group=false" \ -F "text=Segue o documento solicitado" \ -F "file=@/path/to/documento.pdf"
Resposta de Sucesso
O formato da resposta depende do parâmetro enqueue enviado na requisição.
Com enqueue=true
{
"message": "Whatsapp message enqueued successfully"
}
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:
{
"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).
200com{"status": true, "message": "Message delivered, but it could not be persisted locally for the UI", "external_id": "..."}500com um texto informando que o envio ocorreu mas houve erro ao gravar a mensagem no banco
Erros Comuns
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.
Causa: A cota de mensagens do seu plano foi esgotada.
Solução: Faça upgrade do plano para continuar enviando mensagens via API.
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"
}
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).
Causa: O parâmetro contact_key está vazio ou não foi fornecido.
Solução: Informe o telefone do destinatário no formato 5511988888888.
Causa: Nenhum texto ou arquivo foi fornecido.
Solução: Forneça pelo menos um dos dois: parâmetro text com a mensagem ou parâmetro file com o arquivo.
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.
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.
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.
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.
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.
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.
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.
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
- ⚠️ 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