Envío de multimedia

Use POST /v1/instances/{instanceId}/messages/media para enviar imagen, video, audio o documento. Igual que en el envío de texto, la API responde 202 y envía a continuación.

Campos

Campo	Tipo	Descripción
to	texto, obligatorio	Teléfono de quien va a recibir, con código de país y de área
kind	obligatorio	image, video, audio o document
url	texto	Dirección pública del archivo, de hasta 2.048 caracteres
base64	texto	Contenido del archivo en base64
mimeType	texto	Tipo del archivo, como image/png. Obligatorio con base64
fileName	texto, opcional	Nombre del archivo, de hasta 255 caracteres
caption	texto, opcional	Pie de foto o leyenda, hasta 1.024 caracteres
quotedMessageId	texto, opcional	Mensaje al que se responde

Indique el archivo por url o por base64, nunca por ambos ni por ninguno. Los campos que no están en la tabla se rechazan con 400.

Por URL

El archivo debe estar en una dirección http o https pública. La API descarga el archivo en el momento del envío.

curl -X POST https://api.zap.nigora.com.br/v1/instances/INSTANCIA_ID/messages/media \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "5511999999999", "kind": "image", "url": "https://exemplo.com/foto.jpg", "caption": "Seu comprovante" }'

• Las direcciones de la red interna, como localhost o IP privadas, se rechazan con 400 y url_not_allowed.
• Una dirección que no sea http ni https, o que esté mal formada, se rechaza con 400 y invalid_media_url.
• El archivo puede pesar hasta 16 MB; para document, hasta 100 MB. Por encima de eso, el mensaje falla después de ser aceptado, con error: "media_too_large" en el webhook message.status.
• Sin mimeType, la API usa el tipo informado por el servidor del archivo.

Por base64

curl -X POST https://api.zap.nigora.com.br/v1/instances/INSTANCIA_ID/messages/media \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "5511999999999", "kind": "document", "base64": "JVBERi0xLjQK...", "mimeType": "application/pdf", "fileName": "boleto.pdf" }'

• El archivo decodificado puede pesar hasta 16 MB. Por encima de eso, la respuesta es 400 con media_too_large. Para archivos más grandes, use url.
• El cuerpo completo de la solicitud puede pesar hasta 25 MB. Por encima de eso, la respuesta es 413 con payload_too_large.
• Un base64 inválido, o sin mimeType, devuelve 400 con invalid_media.

Errores

Estado	Código	Cuándo
400	validation_error	Campo fuera de la tabla, demasiado grande o con formato inválido (como un mimeType que no es tipo/subtipo)
400	invalid_phone	Teléfono inválido
400	invalid_media	Ni url ni base64, ambos a la vez, base64 inválido o sin mimeType
400	invalid_media_url	url mal formada o que no usa http/https
400	media_too_large	base64 de más de 16 MB
400	url_not_allowed	url apunta a una dirección que no es pública
402	instance_suspended	Instancia suspendida o con pago pendiente
409	instance_not_connected	Instancia desconectada, con disableQueueWhenDisconnected activada
413	payload_too_large	Cuerpo de más de 25 MB
422	contact_opted_out	El contacto pidió no recibir mensajes

Los fallos que solo aparecen en el momento del envío (archivo demasiado grande en la url, descarga que no funcionó, número sin WhatsApp) llegan por el webhook message.status, con status: "failed". Vea la lista de valores de error en Envío de mensajes.