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 "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."
  }'

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 você tiver mais de um número

ID 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ório

O 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 com country_code. Com campos de formulário, não inclua um 0 inicial de discagem interurbana (09876543210): ele não é removido antes de country_code ser adicionado, então a mensagem vai para o número errado. Requisições JSON o removem para você.

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

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:

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, ou um arquivo vazioFile 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.

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 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 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.
Not enough creditsSeu plano não tem mais mensagens disponíveis.
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. 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 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_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.