API de mensagens

API de envio de mensagens para um grupo de WhatsApp

Envie um texto, uma imagem ou um documento de WhatsApp para um grupo de WhatsApp do qual o seu número conectado participa. Use-a para comunicados à equipe, novidades para a comunidade e notificações em massa.

POSThttps://wbiztool.com/api/v1/send_msg/group/

Corpo: JSON, campos de formulário ou multipart/form-data ao enviar um arquivo

A mensagem entra na fila e é enviada ao grupo a partir do seu número de WhatsApp. A resposta traz um msg_id que você pode usar para verificar o status.

Exemplo rápido#

curl -X POST https://wbiztool.com/api/v1/send_msg/group/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 0,
    "group_name": "Sales Team Mumbai",
    "msg": "Reminder: *weekly review* starts at 4 PM today."
  }'

import requests

response = requests.post(
    "https://wbiztool.com/api/v1/send_msg/group/",
    json={
        "client_id": 12345,
        "api_key": "YOUR_API_KEY",
        "whatsapp_client": 678,
        "msg_type": 0,
        "group_name": "Sales Team Mumbai",
        "msg": "Reminder: *weekly review* starts at 4 PM today.",
    },
    timeout=60,
)
result = response.json()  # read the body even when the HTTP code is 400

if result.get("status") == 1:
    print("Queued with msg_id", result["msg_id"])
else:
    print("Failed:", result.get("message"))

// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/send_msg/group/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    client_id: 12345,
    api_key: "YOUR_API_KEY",
    whatsapp_client: 678,
    msg_type: 0,
    group_name: "Sales Team Mumbai",
    msg: "Reminder: *weekly review* starts at 4 PM today.",
  }),
});
const result = await response.json(); // read the body even when the HTTP code is 400

if (result.status === 1) {
  console.log("Queued with msg_id", result.msg_id);
} else {
  console.error("Failed:", result.message);
}

<?php
$payload = [
    'client_id'       => 12345,
    'api_key'         => 'YOUR_API_KEY',
    'whatsapp_client' => 678,
    'msg_type'        => 0,
    'group_name'      => 'Sales Team Mumbai',
    'msg'             => 'Reminder: *weekly review* starts at 4 PM today.',
];

$ch = curl_init('https://wbiztool.com/api/v1/send_msg/group/');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($result['status'] ?? 0) === 1) {
    echo 'Queued with msg_id ' . $result['msg_id'];
} else {
    echo 'Failed: ' . ($result['message'] ?? 'no response');
}

Substitua 12345, YOUR_API_KEY e 678 pelos seus próprios valores. Veja em Autenticação onde encontrá-los.

Parâmetros da requisição#

Autenticação

client_idintegerobrigatório: Seu ID do Cliente da API, em Configurações → Chaves API.
api_keystringobrigatório: Sua chave de API, na mesma página.
whatsapp_clientintegerObrigatório se o proprietário tiver mais de um número conectado: ID do número de WhatsApp a partir do qual enviar, nas configurações do WhatsApp. Precisa ser um número que pertença ao proprietário do espaço de trabalho. Se você não enviar e o proprietário tiver exatamente um número conectado, esse número será usado.

Grupo e mensagem

group_namestringobrigatório: Nome do grupo de WhatsApp, escrito exatamente como aparece no WhatsApp. Envie-o como string. Um número JSON como 2024 retorna uma página de erro HTML (HTTP 500). Veja Como o grupo é encontrado.
msg_typeintegeropcional: 0 texto (padrão), 1 imagem, 2 arquivo ou documento.
msgstringObrigatório quando msg_type é 0: Texto da mensagem. Para imagens e arquivos, é a legenda e pode ficar vazio. A formatação do WhatsApp funciona: *bold*, _italic_, ~strikethrough~. message é aceito como alias.

Imagens e arquivos

img_urlstringObrigatório quando msg_type é 1 e nenhum arquivo é enviado: URL pública http ou https da imagem.
file_urlstringObrigatório quando msg_type é 2 e nenhum arquivo é enviado: URL pública http ou https a partir da qual o arquivo pode ser baixado diretamente.
filefileopcional: Envie a imagem ou o arquivo em vez de informar uma URL. Envie a requisição como multipart/form-data com o campo chamado file.
file_namestringopcional: Nome do arquivo que o grupo vê, como price-list.pdf. A extensão define como o arquivo é enviado, então inclua uma. Ele é enviado em letras minúsculas, caracteres como & : ? * $ ; são substituídos por _, e ele é cortado em 150 caracteres. Se você não enviar, o nome vem da URL ou do arquivo enviado.

Opções de entrega

expire_after_secondsintegeropcional: Marca a mensagem como expirada (status 4) se ela não tiver sido enviada dentro desse número de segundos, por exemplo 3600 para uma hora. Um processo em segundo plano faz isso pelo menos 30 segundos depois do prazo, então não conte com isso para prazos menores que um minuto.
webhookstringopcional: URL que recebe um POST quando a mensagem é enviada ou falha. O payload é o mesmo de Enviar mensagem.

Imagens e arquivos seguem as mesmas regras de Enviar mensagem: as URLs são baixadas quando você chama a API (até 100 MB). No envio da mensagem, imagens acima de 16 MB e vídeos acima de 64 MB falham, áudio WAV e OGG não é suportado, e arquivos (msg_type 2) sem uma extensão aceita recebem .pdf no final, inclusive os enviados por upload. Os nomes de arquivo são enviados em letras minúsculas. Veja Enviar imagens e arquivos para a lista completa de extensões e erros.

Para enviar um arquivo por upload, use os exemplos multipart de Enviar mensagem, trocando a URL por /api/v1/send_msg/group/ e phone/country_code por group_name.

Imagem a partir de uma URL

curl -X POST https://wbiztool.com/api/v1/send_msg/group/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 1,
    "group_name": "Sales Team Mumbai",
    "img_url": "https://example.com/reports/weekly-sales.png",
    "msg": "This week'\''s sales summary"
  }'

import requests

response = requests.post(
    "https://wbiztool.com/api/v1/send_msg/group/",
    json={
        "client_id": 12345,
        "api_key": "YOUR_API_KEY",
        "whatsapp_client": 678,
        "msg_type": 1,
        "group_name": "Sales Team Mumbai",
        "img_url": "https://example.com/reports/weekly-sales.png",
        "msg": "This week's sales summary",
    },
    timeout=60,
)
print(response.json())

// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/send_msg/group/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    client_id: 12345,
    api_key: "YOUR_API_KEY",
    whatsapp_client: 678,
    msg_type: 1,
    group_name: "Sales Team Mumbai",
    img_url: "https://example.com/reports/weekly-sales.png",
    msg: "This week's sales summary",
  }),
});
console.log(await response.json());

<?php
$ch = curl_init('https://wbiztool.com/api/v1/send_msg/group/');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'client_id'       => 12345,
        'api_key'         => 'YOUR_API_KEY',
        'whatsapp_client' => 678,
        'msg_type'        => 1,
        'group_name'      => 'Sales Team Mumbai',
        'img_url'         => 'https://example.com/reports/weekly-sales.png',
        'msg'             => "This week's sales summary",
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);
curl_close($ch);

Como o grupo é encontrado#

O Wbiztool não verifica o nome do grupo quando você chama a API. No momento do envio da mensagem, o Wbiztool pesquisa group_name nas suas conversas do WhatsApp e abre o primeiro resultado. Por isso:

Seu número de WhatsApp conectado precisa ser membro do grupo.
Use o nome completo do grupo exatamente como o WhatsApp o exibe, incluindo emojis e pontuação. Espaços no início e no fim são ignorados.
Use um nome único. Um nome curto ou parcial pode corresponder a outra conversa que aparece antes na pesquisa.
Se nada corresponder, se somente administradores puderem enviar mensagens no grupo e o seu número não for administrador, ou se somente administradores da comunidade puderem publicar, a mensagem falha com o erro Group not found.
Se o seu número tiver saído do grupo, a mensagem falha com o erro Group member blocked.

Problemas com o grupo não aparecem na resposta da API. Use um webhook ou Status da mensagem para saber se a mensagem foi enviada.

Usar o cliente oficial#

O cliente Python chama este endpoint para você.

Python

from wbiztool_client import WbizToolClient

client = WbizToolClient(api_key="YOUR_API_KEY", client_id=12345)

result = client.send_message_to_group(
    group_name="Sales Team Mumbai",
    msg="Reminder: weekly review starts at 4 PM today.",
    whatsapp_client=678,
)
print(result)

Os erros lançam requests.HTTPError. Leia o motivo com e.response.json()["message"].

Resposta#

Uma requisição bem-sucedida retorna HTTP 200:

{
  "status": 1,
  "message": "Created",
  "msg_id": 9817263
}

Campo	Tipo	Descrição
`status`	integer	`1` se a mensagem entrou na fila, `0` se a requisição falhou.
`message`	string	`Created` em caso de sucesso; caso contrário, o erro.
`msg_id`	integer	ID da mensagem na fila. Guarde-o para verificar o status depois. Presente apenas em caso de sucesso.

"status": 1 significa que a mensagem entrou na fila, não que chegou ao grupo. Use um webhook ou Status da mensagem para confirmar que ela foi enviada.

Erros#

Os erros retornam HTTP 400 com status igual a 0:

{ "status": 0, "message": "Group Name cant be null" }

Mensagem	Como corrigir
`Auth Error - Please send correct API key and Client id`	Envie uma `api_key` não vazia.
`Invalid client id.`	Envie `client_id` como número.
`Auth Error: invalid api key`	Verifique se a chave existe, não foi excluída e pertence a este `client_id`.
`Group Name cant be null`	Adicione `group_name`.
`Msg cant be null`	Mensagens de texto (`msg_type` 0) precisam de `msg`.
`Image Url Can't be null`	Para `msg_type` 1, envie `img_url` ou faça upload de um `file`.
`File Url Can't be null`	Para `msg_type` 2, envie `file_url` ou faça upload de um `file`.
`Invalid file url, Can't download` / `Invalid file url`	A URL não é pública, o download excedeu o tempo limite ou o arquivo tem mais de 100 MB.
`Invalid whatsapp client None`	Esse ID de `whatsapp_client` não pertence ao proprietário do espaço de trabalho. Veja o aviso acima.
`Invalid whatsapp client id.`	Envie `whatsapp_client`. Ele é obrigatório, a menos que o proprietário tenha exatamente um número conectado.
`Not enough credits`	Seu plano não tem mais mensagens disponíveis.
`Demo Account can not access apis`	Use uma conta normal.
`Account Disabled`	Sua conta está desativada. Fale com o suporte.
`Invalid JSON format: …`	O corpo JSON não é válido, geralmente por causa de uma vírgula sobrando no final ou de uma quebra de linha sem escape em `msg`. Use `\n` para novas linhas.

Dicas#

Teste o nome primeiro: envie um texto curto para o grupo e confira Status da mensagem antes de automatizar qualquer coisa.
Grupos renomeados: se alguém renomear o grupo no WhatsApp, atualize também o group_name na sua integração.
Tipos de mensagem: somente 0, 1 e 2 são valores válidos para msg_type. Qualquer valor que não seja um número inteiro retorna uma página de erro HTML (HTTP 500) em vez de JSON.
Vários grupos de uma vez: Enviar para vários números aceita nomes de grupos misturados com números de telefone em uma única requisição.