API de mensagens
API de envio de mensagens
Envie um texto, uma imagem ou um documento de WhatsApp para um número de telefone a partir do seu número de WhatsApp conectado. Use-a para confirmações de pedido, lembretes de pagamento, alertas e respostas de suporte.
https://wbiztool.com/api/v1/send_msg/Corpo: JSON, campos de formulário ou multipart/form-data ao enviar um arquivo
A mensagem entra na fila e é enviada do seu número de WhatsApp em instantes. 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/ \
-H "Content-Type: application/json" \
-d '{
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"whatsapp_client": 678,
"msg_type": 0,
"country_code": "91",
"phone": "9876543210",
"msg": "Hi Aman, your order #4821 has shipped and will arrive on Thursday."
}'import requests
response = requests.post(
"https://wbiztool.com/api/v1/send_msg/",
json={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"whatsapp_client": 678,
"msg_type": 0,
"country_code": "91",
"phone": "9876543210",
"msg": "Hi Aman, your order #4821 has shipped and will arrive on Thursday.",
},
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/", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
client_id: 12345,
api_key: "YOUR_API_KEY",
whatsapp_client: 678,
msg_type: 0,
country_code: "91",
phone: "9876543210",
msg: "Hi Aman, your order #4821 has shipped and will arrive on Thursday.",
}),
});
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,
'country_code' => '91',
'phone' => '9876543210',
'msg' => 'Hi Aman, your order #4821 has shipped and will arrive on Thursday.',
];
$ch = curl_init('https://wbiztool.com/api/v1/send_msg/');
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órioSeu ID do Cliente da API, em Configurações → Chaves API.
api_keystringobrigatórioSua chave de API, na mesma página.
whatsapp_clientintegerObrigatório se você tiver mais de um númeroID do número de WhatsApp a partir do qual enviar, nas configurações do WhatsApp. Se você não enviar e o seu espaço de trabalho tiver exatamente um número conectado, esse número será usado.
Destinatário e mensagem
phonestringobrigatórioO número de WhatsApp do destinatário, somente dígitos. Espaços,
+,-,.e parênteses são removidos automaticamente. Envie o número com o código do país (919876543210) ou sem ele (9876543210) junto comcountry_code. Com campos de formulário, não inclua um0inicial de discagem interurbana (09876543210): ele não é removido antes decountry_codeser adicionado, então a mensagem vai para o número errado. Requisições JSON o removem para você.country_codestringopcionalCódigo de discagem do país sem
+, por exemplo91para a Índia ou1para os EUA. Ele é adicionado antes dephone, a menos que o número já comece com ele. Exceção: com91, um número de 10 dígitos sempre recebe o prefixo. Com outros códigos, um número local que comece com os mesmos dígitos não recebe o prefixo, então envie-o já com o código do país.msg_typeintegeropcional0texto (padrão),1imagem,2arquivo ou documento.msgstringObrigatório quando msg_type é 0Texto da mensagem, com até 3.000 caracteres. 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 é enviadoURL pública
httpouhttpsda imagem.file_urlstringObrigatório quando msg_type é 2 e nenhum arquivo é enviadoURL pública
httpouhttpsa partir da qual o arquivo pode ser baixado diretamente.filefileopcionalEnvie a imagem ou o arquivo em vez de informar uma URL. Envie a requisição como
multipart/form-datacom o campo chamadofile.file_namestringopcionalNome do arquivo que o destinatário vê, como
invoice-4821.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_secondsintegeropcionalMarca a mensagem como expirada (status
4) se ela não tiver sido enviada dentro desse número de segundos, por exemplo3600para uma hora. Útil para mensagens com prazo, como previsões de entrega. 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.webhookstringopcionalURL que recebe um
POSTquando a mensagem é enviada ou falha. Veja Webhook.
Enviar imagens e arquivos#
Limites de download para img_url e file_url:
- A URL precisa ser pública:
httpouhttps, acessível pela internet. São seguidos até 5 redirecionamentos, e cada um deles também precisa levar a um endereço público. - Os arquivos por link podem ter até 100 MB. O servidor precisa começar a responder em até 45 segundos e não pode ficar parado por mais tempo que isso.
- O arquivo é baixado quando você chama a API, então um link quebrado falha imediatamente com
Invalid file url.
Extensões aceitas: .pdf, .xlsx, .xls, .txt, .docx, .png, .jpg, .jpeg, .webp, .mp3, .mpga, .m4a, .mp4, .webm.
Estas verificações acontecem quando a mensagem é enviada, e não quando você chama a API, então as falhas só aparecem em Status da mensagem e no webhook:
| Problema | error em Status da mensagem |
|---|---|
Uma imagem (msg_type 1) acima de 16 MB | File exceeds WhatsApp size limit (16MB max) |
Um vídeo (.mp4, .webm) acima de 64 MB, ou um arquivo vazio | File exceeds WhatsApp size limit (…) |
Um arquivo .ogg, ou um arquivo .wav enviado como imagem (msg_type 1) | File type not supported |
Áudios WAV e OGG não são suportados. Um arquivo .wav enviado como arquivo (msg_type 2) não é rejeitado, mas chega como recording.wav.pdf. Converta o áudio para .mp3 ou .m4a antes.
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
-H "Content-Type: application/json" \
-d '{
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"whatsapp_client": 678,
"msg_type": 1,
"country_code": "91",
"phone": "9876543210",
"img_url": "https://example.com/offers/diwali-sale.jpg",
"msg": "Our Diwali sale starts today 🎉"
}'import requests
response = requests.post(
"https://wbiztool.com/api/v1/send_msg/",
json={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"whatsapp_client": 678,
"msg_type": 1,
"country_code": "91",
"phone": "9876543210",
"img_url": "https://example.com/offers/diwali-sale.jpg",
"msg": "Our Diwali sale starts today 🎉",
},
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/", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
client_id: 12345,
api_key: "YOUR_API_KEY",
whatsapp_client: 678,
msg_type: 1,
country_code: "91",
phone: "9876543210",
img_url: "https://example.com/offers/diwali-sale.jpg",
msg: "Our Diwali sale starts today 🎉",
}),
});
console.log(await response.json());<?php
$ch = curl_init('https://wbiztool.com/api/v1/send_msg/');
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,
'country_code' => '91',
'phone' => '9876543210',
'img_url' => 'https://example.com/offers/diwali-sale.jpg',
'msg' => 'Our Diwali sale starts today 🎉',
]),
CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);
curl_close($ch);curl -X POST https://wbiztool.com/api/v1/send_msg/ \
-F client_id=12345 \
-F api_key=YOUR_API_KEY \
-F whatsapp_client=678 \
-F msg_type=2 \
-F country_code=91 \
-F phone=9876543210 \
-F "msg=Your invoice for order #4821 is attached." \
-F file_name=invoice-4821.pdf \
-F file=@./invoice-4821.pdfimport requests
with open("invoice-4821.pdf", "rb") as f:
response = requests.post(
"https://wbiztool.com/api/v1/send_msg/",
data={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"whatsapp_client": 678,
"msg_type": 2,
"country_code": "91",
"phone": "9876543210",
"msg": "Your invoice for order #4821 is attached.",
"file_name": "invoice-4821.pdf",
},
files={"file": f},
timeout=120,
)
print(response.json())// Node.js 20+ (built-in fetch, FormData and fs.openAsBlob). Save as .mjs to use top-level await.
import { openAsBlob } from "node:fs";
const form = new FormData();
form.append("client_id", "12345");
form.append("api_key", "YOUR_API_KEY");
form.append("whatsapp_client", "678");
form.append("msg_type", "2");
form.append("country_code", "91");
form.append("phone", "9876543210");
form.append("msg", "Your invoice for order #4821 is attached.");
form.append("file_name", "invoice-4821.pdf");
form.append("file", await openAsBlob("./invoice-4821.pdf"), "invoice-4821.pdf");
// Don't set Content-Type yourself; fetch adds the multipart boundary.
const response = await fetch("https://wbiztool.com/api/v1/send_msg/", { method: "POST", body: form });
console.log(await response.json());<?php
$ch = curl_init('https://wbiztool.com/api/v1/send_msg/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
// An array body (not json_encode) makes cURL send multipart/form-data.
CURLOPT_POSTFIELDS => [
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
'whatsapp_client' => 678,
'msg_type' => 2,
'country_code' => '91',
'phone' => '9876543210',
'msg' => 'Your invoice for order #4821 is attached.',
'file_name' => 'invoice-4821.pdf',
'file' => new CURLFile('/path/to/invoice-4821.pdf', 'application/pdf', 'invoice-4821.pdf'),
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 120,
]);
echo curl_exec($ch);
curl_close($ch);Usar os clientes oficiais#
Os clientes para Python e Node.js chamam este endpoint para você.
from wbiztool_client import WbizToolClient
client = WbizToolClient(api_key="YOUR_API_KEY", client_id="12345")
result = client.send_message(
phone="9876543210",
country_code="91",
msg="Hi Aman, your order #4821 has shipped.",
whatsapp_client=678,
)
print(result)Os erros lançam requests.HTTPError. Leia o motivo com e.response.json()["message"].
const { WbizToolClient } = require("wbiztool-client");
const client = new WbizToolClient({
clientId: 12345,
apiKey: "YOUR_API_KEY",
whatsappClient: 678,
});
(async () => {
// Errors throw, with the API's response in the error message.
const result = await client.sendMessage({
phone: "9876543210",
countryCode: "91",
message: "Hi Aman, your order #4821 has shipped.",
});
console.log(result);
})().catch(console.error);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 já chegou ao destinatário. Use um webhook ou Status da mensagem para confirmar que ela foi enviada.
Erros#
Os erros retornam HTTP 400 com status igual a 0 (Account Disabled não tem o campo status):
{ "status": 0, "message": "Msg 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. |
Either phone or group_name parameter is required | Adicione phone. |
Please provide either phone OR group_name, not both | Remova um dos dois. |
Invalid phone number | phone deve conter somente dígitos (de 6 a 17), podendo começar com +. |
Invalid Contact Number "…" | Com o código do país incluído, o número deve ter de 6 a 15 dígitos. |
Msg cant be null | Mensagens de texto (msg_type 0) precisam de msg. |
Message length is too long | Limite msg a 3.000 caracteres ou menos. |
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 | Esse ID de whatsapp_client não está no seu espaço de trabalho. |
Invalid whatsapp client id. | Envie whatsapp_client. Ele é obrigatório quando seu espaço de trabalho tem mais de 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. |
Uma mensagem na fila ainda pode falhar no envio, por exemplo com File exceeds WhatsApp size limit (…). Esses erros nunca aparecem nesta resposta. Veja Enviar imagens e arquivos e confira Status da mensagem.
Webhook#
Se você informar webhook, o Wbiztool envia um POST para essa URL quando a mensagem é enviada ou falha. O corpo é codificado como formulário (application/x-www-form-urlencoded), não como JSON:
msg_id=9817263&status=SENT
| Campo | Valores |
|---|---|
msg_id | O msg_id retornado quando você enviou a mensagem. |
status | SENT ou FAILED |
Responda com qualquer código 2xx. Se o seu endpoint exceder o tempo limite (após 3 segundos) ou retornar 5xx, a chamada é repetida, até 3 vezes no total. Uma resposta 4xx não é repetida. Nenhum webhook é enviado quando uma mensagem é cancelada ou expira; para esses casos, use Status da mensagem.
Dicas#
- Números de telefone: armazene os números em formato internacional e envie-os com
country_codepara evitar ambiguidades. - Novas linhas em JSON: escreva-as como
\ndentro demsg. Uma quebra de linha literal deixa o JSON inválido. - Mantenha seu número conectado: as mensagens são enviadas do seu número de WhatsApp, então ele precisa continuar conectado nas configurações do WhatsApp.
- Muitos destinatários: para enviar a mesma mensagem para vários números em uma única requisição, use Enviar para vários números. Para campanhas grandes, envie uma planilha pela página Campanhas.
