Enviar un mensaje de WhatsApp con PHP

Objetivo

Al final, tendrá un script PHP que envía un mensaje de texto mediante la Nigora Zap API y muestra la respuesta.

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.
• PHP 8 o más nuevo, con la extensión cURL activada. Compruébelo con php -m.

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

<?php
$instanciaId = getenv('NIGORA_INSTANCIA_ID');
$token = getenv('NIGORA_TOKEN');
if (!$instanciaId || !$token) {
    fwrite(STDERR, "Defina NIGORA_INSTANCIA_ID e NIGORA_TOKEN.\n");
    exit(1);
}

$url = "https://api.zap.nigora.com.br/v1/instances/{$instanciaId}/messages/text";
$corpo = json_encode([
    'to' => '5511999999999',
    'text' => 'Olá! Esta mensagem saiu pela API.',
], JSON_UNESCAPED_UNICODE);

$curl = curl_init($url);
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $corpo,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {$token}",
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
]);

$resposta = curl_exec($curl);
if ($resposta === false) {
    fwrite(STDERR, 'Falha de rede: ' . curl_error($curl) . "\n");
    exit(1);
}
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

echo "Status HTTP: {$status}\n{$resposta}\n";
exit($status < 300 ? 0 : 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

php enviar.php

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

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.