API de mensagens

API de agendamento de mensagens de WhatsApp

Agende um texto, uma imagem ou um documento de WhatsApp para ser enviado a um número de telefone ou grupo na data e hora que você escolher. Use-a para lembretes de consulta, mensagens de aniversário, follow-ups e ofertas com prazo.

POSThttps://wbiztool.com/api/v1/schedule_msg/

Corpo: JSON ou campos de formulário

A mensagem aguarda na sua fila até o horário agendado e então é enviada do seu número de WhatsApp. A resposta traz um msg_id que você pode usar para verificar o status ou cancelá-la.

Exemplo rápido#

curl -X POST https://wbiztool.com/api/v1/schedule_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, a reminder that your appointment is today at 11:30 AM.",
    "date": "24/12/2026",
    "time": "09:00",
    "timezone": "Asia/Kolkata"
  }'

import requests

response = requests.post(
    "https://wbiztool.com/api/v1/schedule_msg/",
    json={
        "client_id": 12345,
        "api_key": "YOUR_API_KEY",
        "whatsapp_client": 678,
        "msg_type": 0,
        "country_code": "91",
        "phone": "9876543210",
        "msg": "Hi Aman, a reminder that your appointment is today at 11:30 AM.",
        "date": "24/12/2026",
        "time": "09:00",
        "timezone": "Asia/Kolkata",
    },
    timeout=60,
)
result = response.json()  # read the body even when the HTTP code is 400

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

// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/schedule_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, a reminder that your appointment is today at 11:30 AM.",
    date: "24/12/2026",
    time: "09:00",
    timezone: "Asia/Kolkata",
  }),
});
const result = await response.json(); // read the body even when the HTTP code is 400

if (result.status === 1) {
  console.log("Scheduled with msg_id", result.msg_id);
} else {
  console.error("Failed:", result.message ?? "no message in response");
}

<?php
$payload = [
    'client_id'       => 12345,
    'api_key'         => 'YOUR_API_KEY',
    'whatsapp_client' => 678,
    'msg_type'        => 0,
    'country_code'    => '91',
    'phone'           => '9876543210',
    'msg'             => 'Hi Aman, a reminder that your appointment is today at 11:30 AM.',
    'date'            => '24/12/2026',
    'time'            => '09:00',
    'timezone'        => 'Asia/Kolkata',
];

$ch = curl_init('https://wbiztool.com/api/v1/schedule_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 'Scheduled with msg_id ' . $result['msg_id'];
} else {
    echo 'Failed: ' . ($result['message'] ?? 'no message in 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: ID do número de WhatsApp ou da conta do Telegram a partir do qual enviar, nas configurações do WhatsApp. Ao contrário de Enviar mensagem, este endpoint nunca escolhe um número por você.

Agendamento

datestringobrigatório: Dia de envio da mensagem, no formato dd/mm/yyyy, por exemplo 24/12/2026.
timestringobrigatório: Horário de envio da mensagem, no formato de 24 horas HH:MM, por exemplo 09:00 ou 18:45. Não inclua segundos.
timezonestringopcional: Fuso horário em que date e time estão. O padrão é IST (Índia) se você não enviar. Veja Fusos horários.

Destinatário e mensagem

phonestringObrigatório, a menos que você envie group_name: O número de WhatsApp do destinatário. Espaços, +, -, ., parênteses e um 00 inicial são removidos automaticamente, então +91 98765-43210 funciona. Valores de planilha como 919876543210.0 e 9.19876543210E+11 são lidos como os seus dígitos, mas um valor arredondado como 9.19877E+11 é recusado, porque faltam dígitos. Envie o número com o código do país (919876543210) ou sem ele (9876543210) junto com country_code. Um número local escrito com o 0 inicial também funciona: 09876543210 com country_code 91 vai para 919876543210, e 0612345678 com 39 (Itália, onde o 0 faz parte do número) vai para 390612345678. Um número escrito com + ou 00 já traz o próprio código do país: country_code não é adicionado a ele, e um (0) entre parênteses depois do código é removido, então +44 (0)20 7946 0018 vai para 442079460018. De uma conta do Telegram, phone também pode ser um @username, um link t.me/username ou tg:<id>.
group_namestringObrigatório, a menos que você envie phone: Nome de um grupo de WhatsApp do qual o seu número participa. Ele é encontrado da mesma forma que em Enviar para um grupo. Envie phone ou group_name, nunca os dois.
country_codestringopcional: Código de discagem do país sem +, por exemplo 91 para a Índia ou 1 para os EUA. Ele é adicionado antes de phone, a menos que o número já comece com ele ou esteja escrito com + ou 00. Exceção: com 91, um número de 10 dígitos sempre recebe o prefixo. Com outros códigos, envie os números locais que começam com os mesmos dígitos já com o código do país. Ignorado para grupos.
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: URL pública http ou https da imagem.
file_urlstringObrigatório quando msg_type é 2: URL pública http ou https a partir da qual o arquivo pode ser baixado diretamente.
file_namestringopcional: Nome do arquivo que o destinatário vê, como invoice-4821.pdf. 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.

Opções de entrega

webhookstringopcional: URL que recebe um POST quando a mensagem é enviada, falha, é cancelada ou expira. O payload é o mesmo de Enviar mensagem.

Quando a mensagem é enviada#

O WbizTool converte date, time e timezone em um único instante e envia a mensagem assim que esse instante passar, desde que o seu número de WhatsApp esteja conectado.
Um horário no passado é aceito. A mensagem é enviada imediatamente, como um envio normal. Confira bem o formato da data (dd/mm/yyyy, dia primeiro) para não enviar uma mensagem meses antes.
Se o seu número estiver desconectado no horário agendado, a mensagem aguarda e é enviada assim que o número se reconectar, mesmo que isso aconteça muito depois do planejado. Este endpoint não tem expiração, então cancele a mensagem se ela não fizer mais sentido. Uma mensagem que ainda esteja aguardando em um número desconectado ou excluído 90 dias depois do horário agendado é excluída.
Até ser enviada, a mensagem tem status 0 (Criada) e pode ser cancelada. Ela conta no limite diário do número no dia em que você a agenda (e nas mensagens do plano gratuito).

Fusos horários#

timezone aceita um nome de fuso horário ou uma das abreviações abaixo.

Nomes de fuso horário como Asia/Kolkata, America/New_York, Europe/London ou Australia/Sydney. Qualquer nome do banco de dados de fusos horários IANA funciona. Esta é a opção mais confiável. Veja a lista na Referência de fusos horários.

Abreviações funcionam em maiúsculas ou minúsculas (IST ou ist). Cada uma corresponde a uma região, e o horário de verão dessa região é aplicado automaticamente:

Abreviação	Tratada como
`IST`	`Asia/Kolkata`
`UTC`	`UTC`
`GMT`	`GMT`
`EST`	`US/Eastern`
`CST`	`US/Central`
`MST`	`US/Mountain`
`PST`	`US/Pacific`
`CET`, `CEST`	`Europe/Paris`
`EET`, `EEST`	`Europe/Athens`
`JST`	`Asia/Tokyo`
`AEST`, `AEDT`	`Australia/Sydney`

Por exemplo, EST em julho significa o horário de verão de Nova York (UTC−4), e não um UTC−5 fixo.

Agendar para um grupo#

curl -X POST https://wbiztool.com/api/v1/schedule_msg/ \
  -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": "Team meeting starts in 15 minutes.",
    "date": "24/12/2026",
    "time": "14:45",
    "timezone": "Asia/Kolkata"
  }'

import requests

response = requests.post(
    "https://wbiztool.com/api/v1/schedule_msg/",
    json={
        "client_id": 12345,
        "api_key": "YOUR_API_KEY",
        "whatsapp_client": 678,
        "msg_type": 0,
        "group_name": "Sales Team Mumbai",
        "msg": "Team meeting starts in 15 minutes.",
        "date": "24/12/2026",
        "time": "14:45",
        "timezone": "Asia/Kolkata",
    },
    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/schedule_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,
    group_name: "Sales Team Mumbai",
    msg: "Team meeting starts in 15 minutes.",
    date: "24/12/2026",
    time: "14:45",
    timezone: "Asia/Kolkata",
  }),
});
console.log(await response.json());

<?php
$ch = curl_init('https://wbiztool.com/api/v1/schedule_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'        => 0,
        'group_name'      => 'Sales Team Mumbai',
        'msg'             => 'Team meeting starts in 15 minutes.',
        'date'            => '24/12/2026',
        'time'            => '14:45',
        'timezone'        => 'Asia/Kolkata',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);
curl_close($ch);

Resposta#

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

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

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

A resposta não repete o horário agendado nem o fuso horário, então registre o que você enviou.

Erros#

A maioria dos erros retorna HTTP 200 com status igual a 0, então sempre verifique status no corpo:

{ "message": "Scheduled date & time is not in valid format", "status": 0 }

Mensagem	Como corrigir
`Auth Error`	Envie `client_id` e `api_key`.
`Invalid Client Id`	Envie `client_id` como número. Retornado com HTTP `403`.
`Auth Error: invalid api key`	Verifique se a chave existe, não foi excluída e pertence a este `client_id`. Retornado com HTTP `400`.
`Either phone or group_name parameter is required`	Adicione `phone` ou `group_name`.
`Please provide either phone OR group_name, not both`	Remova um dos dois.
`Invalid phone number`	`phone` deve ser um número de 6 a 17 dígitos. Letras e outros símbolos não são permitidos, nem um valor de planilha arredondado como `9.19877E+11`.
`Invalid Contact Number "…"`	Com o código do país incluído, o número deve ter de 7 a 15 dígitos.
`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`.
`File Url Can't be null`	Para `msg_type` 2, envie `file_url`.
`Scheduled date & time is not in valid format`	`date` ou `time` está ausente, ou `timezone` é uma string vazia.
`Scheduled date & time is not in valid format: date DD/MM/YYYY and time HH:MM (24-hour)`	`date` ou `time` está em outro formato (por exemplo `2026-12-24` ou `09:00:00`) ou não é uma data real (`31/02/2026`).
`Unknown timezone "…": …`	`timezone` não é um nome de fuso horário nem uma das abreviações acima. Deslocamentos como `GMT+5:30` não são aceitos.
`Invalid msg_type: use 0 (text), 1 (image) or 2 (file)`	Envie `msg_type` como `0`, `1` ou `2`.
`Invalid whatsapp client …`	`whatsapp_client` está ausente ou não é um dos seus números. Use o ID exibido para um número conectado no seu painel.
`Telegram usernames can only be sent to from a Telegram account: pass its id as whatsapp_client`	Um `@username`, um link `t.me` ou `tg:<id>` em `phone` precisa de uma conta do Telegram como `whatsapp_client`.
`Server error: the message was not scheduled. Please try again.`	Algo falhou do nosso lado. Retornado com HTTP `500`; nada foi agendado, então tente novamente.
`Not enough credits`	O espaço de trabalho está no plano gratuito e não tem mais mensagens: os planos pagos enviam mensagens ilimitadas. Veja Quando as mensagens acabam.
`Daily limit reached: a number can send 1,000 messages in 24 hours (fair use). Send the rest tomorrow.` (HTTP `429`, `"code": "daily_limit_reached"`)	Este número já aceitou 1.000 mensagens nas últimas 24 horas (uso justo). A resposta ainda traz o `msg_id` da mensagem recusada, que aparece com falha. Envie o restante mais tarde ou de outro número.
`Demo Account can not access apis`	Use uma conta normal.
`Invalid JSON format: …`	O corpo JSON não é válido, ou você enviou campos de formulário sem `client_id`.

Dicas#

Monte a data com cuidado: em Python, use strftime("%d/%m/%Y") e strftime("%H:%M"). Em JavaScript, formate a data e a hora no mesmo fuso horário que você envia em timezone, e não no horário local do seu servidor:

const tz = "Asia/Kolkata"; // d is the Date to send at
const date = new Intl.DateTimeFormat("en-GB", { timeZone: tz, day: "2-digit", month: "2-digit", year: "numeric" }).format(d); // "24/12/2026"
const time = new Intl.DateTimeFormat("en-GB", { timeZone: tz, hour: "2-digit", minute: "2-digit", hourCycle: "h23" }).format(d); // "09:00"

Confirme o horário: agende uma mensagem de teste para cinco minutos à frente e verifique se ela chega quando você espera.
Mudança de planos: para reagendar, cancele a mensagem e agende uma nova.
Por enquanto, não use os clientes oficiais para agendar: o schedule_message do Python envia a data como YYYY-MM-DD (recusado por não estar em um formato válido), e o scheduleMessage do Node envia schedule_time, que este endpoint não lê. Chame o endpoint diretamente, como mostrado acima.
Mensagens recorrentes: para mensagens que se repetem, como lembretes mensais de pagamento, veja Criar lembrete.