Enviar un mensaje de WhatsApp con Python

Objetivo

Al final, tendrá un script Python que envía un mensaje de texto mediante la Nigora Zap API y muestra la respuesta. Usa solo la biblioteca estándar, sin instalar nada.

Requisitos previos

• Una instancia conectada. Si aún no la conectó, vea Conexión.
• El ID y el token de la instancia, como en Primeros pasos.
• Python 3.9 o más nuevo. Compruébelo con python3 --version.

1. Guarde las credenciales en el entorno

No escriba el token en el código. Léalo de variables de entorno:

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

2. Cree el script

Guárdelo 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:
    # La API respondió con un error: el cuerpo explica el motivo.
    status, corpo = erro.code, erro.read().decode("utf-8")

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

Cambie 5511999999999 por el teléfono de quien va a recibir el mensaje, con código de país y de área. La API ignora todo lo que no sea un dígito y agrega el 55 cuando el número tiene 10 u 11 dígitos.

3. Ejecute

python3 enviar.py

Resultado esperado:

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

El 202 significa que el mensaje entró en la cola. Todavía no fue entregado. Guarde el id: con él usted relaciona la respuesta con los eventos message.sent y message.status, que llegan por webhook.

Si algo sale mal

Status	Código	Qué hacer
400	invalid_phone	Corrija el teléfono: debe tener 12 o 13 dígitos con el 55
401	invalid_token	Revise el token y el ID de la instancia
402	instance_suspended	La instancia está suspendida o con un pago pendiente
422	contact_opted_out	El contacto pidió no recibir mensajes

Si falla la red, urlopen lanza URLError y Python muestra el error en la terminal.

Próximos pasos

• Envío de mensajes: respuestas, cola y seguimiento del resultado.
• Recibir mensajes por webhook: vea las respuestas llegar a su sistema.
• Envío de multimedia: imagen, video, audio y documento.