Ir para conteúdo principal

Envio de Mensagens API

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

Importante: Você precisa ter 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 que você envie mensagens programaticamente através dos canais configurados na sua conta Atys. Atualmente, suportamos:

WhatsApp

Envio de texto e arquivos pelos canais conectados

WhatsApp Oficial

Templates e janela de 24h — regras próprias da Meta

Telegram

Em breve

Instagram

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.

POST

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
* 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);
Python (Requests)
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 (cURL)
<?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 (Guzzle HTTP Client)
<?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);

?>
Go (net/http)
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 (Terminal)
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:

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

// 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

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

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