Enviar uma mensagem de WhatsApp com Python

Objetivo

Ao final, você terá um script Python que envia uma mensagem de texto pela Nigora Zap API e mostra a resposta. Usa só a biblioteca padrão, sem instalar nada.

Pré-requisitos

• Uma instância conectada. Se ainda não conectou, veja Conexão.
• O ID e o token da instância, como em Primeiros passos.
• Python 3.9 ou mais novo. Confira com python3 --version.

1. Guarde as credenciais no ambiente

Não escreva o token no código. Leia-o de variáveis de ambiente:

export NIGORA_INSTANCIA_ID="cole-aqui-o-id-da-instancia"
export NIGORA_TOKEN="cole-aqui-o-token"

2. Crie o script

Salve como enviar.py:

import json
import os
import sys
import urllib.error
import urllib.request

instancia_id = os.environ.get("NIGORA_INSTANCIA_ID")
token = os.environ.get("NIGORA_TOKEN")
if not instancia_id or not token:
    sys.exit("Defina NIGORA_INSTANCIA_ID e NIGORA_TOKEN.")

requisicao = urllib.request.Request(
    f"https://api.zap.nigora.com.br/v1/instances/{instancia_id}/messages/text",
    data=json.dumps({
        "to": "5511999999999",
        "text": "Olá! Esta mensagem saiu pela API.",
    }).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    method="POST",
)

try:
    with urllib.request.urlopen(requisicao, timeout=15) as resposta:
        status, corpo = resposta.status, resposta.read().decode("utf-8")
except urllib.error.HTTPError as erro:
    # A API respondeu com erro: o corpo explica o motivo.
    status, corpo = erro.code, erro.read().decode("utf-8")

print("Status HTTP:", status)
print(corpo)
sys.exit(0 if status < 300 else 1)

Troque 5511999999999 pelo telefone de quem vai receber, com DDI e DDD. A API ignora tudo que não for dígito e acrescenta o 55 quando o número tem 10 ou 11 dígitos.

3. Execute

python3 enviar.py

Resultado esperado:

Status HTTP: 202
{"id":"…","status":"queued"}

O 202 quer dizer que a mensagem entrou na fila. Ela ainda não foi entregue. Guarde o id: é com ele que você liga a resposta aos eventos message.sent e message.status, que chegam por webhook.

Se algo der errado

Status	Código	O que fazer
400	invalid_phone	Corrija o telefone: ele precisa ter 12 ou 13 dígitos com o 55
401	invalid_token	Confira o token e o ID da instância
402	instance_suspended	A instância está suspensa ou com pagamento pendente
422	contact_opted_out	O contato pediu para não receber mensagens

Se faltar rede, o urlopen lança URLError e o Python mostra o erro no terminal.

Próximos passos

• Enviando mensagens: respostas, fila e acompanhamento do resultado.
• Receber mensagens por webhook: veja as respostas chegarem ao seu sistema.
• Envio de mídia: imagem, vídeo, áudio e documento.