Envio de mídia

Use POST /v1/instances/{instanceId}/messages/media para enviar imagem, vídeo, áudio ou documento. Como no envio de texto, a API responde 202 e envia em seguida.

Campos

Campo	Tipo	Descrição
to	texto, obrigatório	Telefone de quem vai receber, com DDI e DDD
kind	obrigatório	image, video, audio ou document
url	texto	Endereço público do arquivo, com até 2.048 caracteres
base64	texto	Conteúdo do arquivo em base64
mimeType	texto	Tipo do arquivo, como image/png. Obrigatório com base64
fileName	texto, opcional	Nome do arquivo, com até 255 caracteres
caption	texto, opcional	Legenda, até 1.024 caracteres
quotedMessageId	texto, opcional	Mensagem a responder

Informe a mídia por url ou por base64, nunca pelos dois nem por nenhum. Campos que não estão na tabela são recusados com 400.

Por URL

O arquivo precisa estar num endereço http ou https público. A API baixa o arquivo na hora do envio.

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" }'

• Endereços da rede interna, como localhost ou IPs privados, são recusados com 400 e url_not_allowed.
• Endereço que não é http nem https, ou malformado, é recusado com 400 e invalid_media_url.
• O arquivo pode ter até 16 MB; para document, até 100 MB. Acima disso, a mensagem falha depois de aceita, com error: "media_too_large" no webhook message.status.
• Sem mimeType, a API usa o tipo informado pelo servidor do arquivo.

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" }'

• O arquivo decodificado pode ter até 16 MB. Acima disso, a resposta é 400 com media_too_large. Para arquivos maiores, use url.
• O corpo inteiro da requisição pode ter até 25 MB. Acima disso, a resposta é 413 com payload_too_large.
• base64 inválido, ou sem mimeType, volta 400 com invalid_media.

Erros

Status	Código	Quando
400	validation_error	Campo fora da tabela, grande demais ou com formato inválido (como um mimeType que não é tipo/subtipo)
400	invalid_phone	Telefone inválido
400	invalid_media	Nem url nem base64, os dois juntos, base64 inválido ou sem mimeType
400	invalid_media_url	url malformada ou que não usa http/https
400	media_too_large	base64 acima de 16 MB
400	url_not_allowed	url aponta para um endereço que não é público
402	instance_suspended	Instância suspensa ou com pagamento pendente
409	instance_not_connected	Instância desconectada, com disableQueueWhenDisconnected ligada
413	payload_too_large	Corpo acima de 25 MB
422	contact_opted_out	O contato pediu para não receber mensagens

As falhas que só aparecem na hora do envio (arquivo grande demais na url, download que não funcionou, número sem WhatsApp) chegam pelo webhook message.status, com status: "failed". Veja a lista de valores de error em Enviando mensagens.