Pular para o conteúdo
WbizTool

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.

POSThttps://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 "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp_client": 678,
    "msg_type": 0,
    "country_code": "91",
    "phone": "9876543210",
    "msg": "Hi Aman, your order #4821 has shipped and will arrive on Thursday."
  }'

Substitua YOUR_API_KEY e 678 pela sua própria chave e pelo ID do seu número. Veja em Autenticação onde encontrá-los. A chave vai no cabeçalho Authorization: Bearer (recomendado); client_id e api_key no corpo, como JSON ou campos de formulário, também funcionam – os exemplos mais abaixo usam essa forma.

Parâmetros da requisição#

Autenticação

AuthorizationheaderRecomendado

Bearer YOUR_API_KEY: sua chave de API de Configurações → Chaves de API. Com o cabeçalho, client_id e api_key podem ficar fora do corpo; se os dois forem enviados, uma chave válida no cabeçalho é a usada. Veja Enviar a chave em um cabeçalho.

client_idintegerSem o cabeçalho Authorization

Seu ID do Cliente da API, em Configurações → Chaves de API. Opcional com o cabeçalho; se você enviar, ele precisa ser o do espaço de trabalho da chave.

api_keystringSem o cabeçalho Authorization

Sua chave de API, na mesma página, quando você não a envia no cabeçalho.

whatsapp_clientintegerObrigatório se você tiver mais de um número

ID do número de WhatsApp ou da conta do Telegram a partir do qual enviar, nas configurações do WhatsApp. Se você não enviar, o único número conectado é usado, WhatsApp primeiro: um único número de WhatsApp conectado é usado mesmo que uma conta do Telegram também esteja conectada, e uma conta do Telegram só quando nenhum número de WhatsApp estiver conectado. Um @username usa a única conta do Telegram conectada.

Destinatário e mensagem

phonestringobrigatório

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

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, 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_typeintegeropcional

0 texto (padrão), 1 imagem, 2 arquivo ou documento.

msgstringObrigatório quando msg_type é 0

Texto 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 é 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 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_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. Ú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.

webhookstringopcional

URL que recebe um POST quando a mensagem é enviada, falha, é cancelada ou expira. Veja Webhook.

Enviar imagens e arquivos#

Limites de download para img_url e file_url:

  • A URL precisa ser pública: http ou https, 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.

Arquivos enviados com msg_type 2 mantêm estas extensões:

CategoriaExtensões
Imagens.jpg, .jpeg, .jpe, .png, .gif, .webp, .bmp
Documentos.pdf, .doc, .docx, .docm, .xls, .xlsx, .xlsm, .xlsb, .ppt, .pptx, .pptm, .txt, .csv
Áudio.mp3, .mpga, .m4a, .aac, .wav, .ogg, .oga
Vídeo.mp4, .mov, .avi, .webm
Arquivos compactados.zip, .rar

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:

Problemaerror em Status da mensagem
Uma imagem (msg_type 1) acima de 16 MBFile exceeds WhatsApp size limit (16MB max)
Um vídeo (.mp4, .webm) acima de 64 MB, também quando enviado como imagem (msg_type 1)File exceeds WhatsApp size limit (64MB max)
Qualquer outro arquivo (msg_type 2) acima de 100 MBFile exceeds WhatsApp size limit (100MB max)
Um arquivo vazio (0 bytes)The file is empty
Um arquivo .wav ou .ogg enviado como imagem (msg_type 1)File type not supported

Áudios WAV e OGG não podem ser enviados como imagem (msg_type 1). Enviados como arquivo (msg_type 2), eles chegam como documento com o próprio nome, como recording.wav. Arquivos .mp3, .mpga, .m4a e .aac chegam como áudio que toca na conversa, e msg vem depois como mensagem de texto separada (áudio não tem legenda).

Imagem a partir de uma URL
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 🎉"
  }'
Enviar um arquivo
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.pdf

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"].

Resposta#

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

{
  "status": 1,
  "message": "Created",
  "msg_id": 9817263
}
CampoTipoDescrição
statusinteger1 se a mensagem entrou na fila, 0 se a requisição falhou.
messagestringCreated em caso de sucesso; caso contrário, o erro.
msg_idintegerID 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" }
MensagemComo corrigir
Auth Error - Please send correct API key and Client idEnvie uma api_key não vazia.
Invalid client id.Envie client_id como número.
Auth Error: invalid api keyVerifique se a chave existe, não foi excluída e pertence a este client_id.
Either phone or group_name parameter is requiredAdicione phone.
Please provide either phone OR group_name, not bothRemova um dos dois.
Invalid phone numberphone 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 nullMensagens de texto (msg_type 0) precisam de msg.
Message length is too longLimite msg a 3.000 caracteres ou menos.
Image Url Can't be nullPara msg_type 1, envie img_url ou faça upload de um file.
File Url Can't be nullPara msg_type 2, envie file_url ou faça upload de um file.
Invalid file url, Can't download / Invalid file urlA URL não é pública, o download excedeu o tempo limite ou o arquivo tem mais de 100 MB.
Invalid whatsapp clientEsse 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.
Telegram usernames can only be sent to from a Telegram account: pass its id as whatsapp_clientUm @username, um link t.me ou tg:<id> em phone precisa de uma conta do Telegram como whatsapp_client.
Not enough creditsO 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 apisUse uma conta normal.
Account DisabledSua 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, e também quando ela é cancelada ou expira antes de ser enviada. O corpo é codificado como formulário (application/x-www-form-urlencoded), não como JSON:

msg_id=9817263&status=SENT
CampoValores
msg_idO msg_id retornado quando você enviou a mensagem.
statusSENT, FAILED, CANCELLED (cancelada antes de ser enviada: com Cancelar mensagem, pelo painel, ou pela remoção do número de WhatsApp ou da campanha dela) ou EXPIRED (não foi enviada antes de acabar o prazo de expire_after_seconds)

Cada webhook é assinado: os cabeçalhos WbizTool-Timestamp e WbizTool-Signature (v1= e um HMAC-SHA256 de <timestamp>.<raw body> com o segredo de assinatura do seu espaço de trabalho) permitem verificar que ele veio do WbizTool. Veja como obter o segredo e a verificação em Python e Node.js em Assinaturas de webhook; receptores que ignoram os cabeçalhos continuam funcionando.

Responda com qualquer código 2xx; um redirecionamento é seguido, no máximo 3 vezes. Se o seu endpoint não responder em 10 segundos, não puder ser alcançado ou retornar 429 ou 5xx, o WbizTool tenta de novo após 30 segundos, 1 minuto e 2 minutos (4 tentativas no total). Outras respostas 4xx não são repetidas. A URL deve ser um endereço público da internet: um webhook para um endereço privado ou local (como 192.168.x.x ou localhost) não é enviado.

Dicas#

  • Números de telefone: armazene os números em formato internacional e envie-os com country_code para evitar ambiguidades.
  • Novas linhas em JSON: escreva-as como \n dentro de msg. 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.