Envío de mensajes

El envío es asíncrono. La API coloca el mensaje en la cola y responde 202 al instante; el envío real ocurre a continuación. El resultado llega mediante los webhooks message.sent y message.status.

Para enviar imagen, video, audio o documento, vea Envío de multimedia.

Texto

POST /v1/instances/{instanceId}/messages/text

Campo	Tipo	Descripción
to	texto, obligatorio	Teléfono de quien va a recibir (vea más abajo)
text	texto, obligatorio	Mensaje, de 1 a 10.000 caracteres
quotedMessageId	texto, opcional	Identificador del mensaje al que se responde, de hasta 128 caracteres

curl -X POST https://api.zap.nigora.com.br/v1/instances/INSTANCIA_ID/messages/text \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "5511999999999", "text": "Seu pedido saiu para entrega." }'

Respuesta (202):

{ "id": "…", "status": "queued" }

Guarde el id: con él usted relaciona la respuesta con los webhooks. Los campos que no están en la tabla se rechazan con 400.

El teléfono

La API ignora todo lo que no sea un dígito, así que +55 (11) 99999-9999 es válido. Con 10 u 11 dígitos (código de área y número), agrega el 55. El resultado debe tener 12 o 13 dígitos; de lo contrario la respuesta es 400 con invalid_phone.

Para responder a un mensaje recibido, use su waMessageId en quotedMessageId.

Seguimiento del resultado

Configure los webhooks y usted recibe:

1. message.sent, cuando el mensaje salió de la cola y fue enviado. El cuerpo trae el id devuelto en el 202, el waMessageId y el type.
2. message.status, en cada cambio de situación del mensaje. El status es sent, delivered, read o failed.

Si el envío falla después de haber sido aceptado, el message.status llega con status: "failed" y un campo error:

error	Qué ocurrió
number_not_on_whatsapp	El teléfono no tiene WhatsApp
send_failed	El envío falló después de 3 intentos
instance_suspended	La instancia fue suspendida antes del envío
expired	El mensaje estuvo más de 7 días en la cola (por ejemplo, con la instancia desconectada)
media_too_large	El archivo descargado de la url superó el límite de tamaño
media_download_failed	La API no pudo descargar el archivo de la url

Cola de envío

Operación	Ruta	Qué hace
Ver la cola	GET /queue	Devuelve { "waiting": n, "delayed": n }: mensajes esperando su turno y mensajes con un nuevo intento programado
Vaciar la cola	DELETE /queue	Elimina los mensajes que aún no se enviaron y devuelve { "removed": n }

Los mensajes ya enviados no se ven afectados por el vaciado. Los eliminados no se envían.

Verificar si el número tiene WhatsApp

POST /v1/instances/{instanceId}/contacts/check acepta de 1 a 50 teléfonos por llamada y exige que la instancia esté conectada:

curl -X POST https://api.zap.nigora.com.br/v1/instances/INSTANCIA_ID/contacts/check \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "phones": ["5511999999999", "5511888888888"] }'

La respuesta es una lista con un elemento por teléfono: { "phone": "...", "exists": true, "jid": "..." }. Cuando el número no tiene WhatsApp, viene exists: false y no hay jid.

Errores de envío

Estado	Código	Cuándo
400	validation_error	Campo ausente, demasiado grande o fuera de la tabla; el mensaje lista los campos
400	invalid_phone	Teléfono fuera de las reglas anteriores
402	instance_suspended	Instancia suspendida o con pago pendiente
409	instance_not_connected	Instancia desconectada, cuando la opción disableQueueWhenDisconnected está activada en PATCH /settings
422	contact_opted_out	El contacto pidió no recibir mensajes

Con disableQueueWhenDisconnected desactivada (el valor predeterminado), la API acepta el mensaje aunque la instancia esté desconectada y este espera en la cola.

Consejo

Evite enviar a quien no conversa con usted. Los mensajes masivos a desconocidos aumentan el riesgo de que WhatsApp bloquee el número. Active la baja de contactos para respetar a quien pide salir.