Ir al contenido

Multimedia ​

Las imágenes, documentos, audio, video y stickers se envían con el mismo endpoint que el texto, POST /api/v1/messages, pero con multipart/form-data en lugar de JSON. Necesitas el scope messages:send.

bash
curl -X POST "https://zappio.cloud/api/v1/messages" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY" \
  -F instance=ins_... \
  -F to=5215500000000 \
  -F type=document \
  -F file=@factura.pdf \
  -F caption="Factura 1042"
CampoQué es
instanceId de la instancia (ins_...).
toNúmero en formato internacional o id de grupo (grp_...).
typeimage, document, audio, video o sticker.
fileEl archivo.
captionTexto opcional de hasta 1024 caracteres. El audio y el sticker no llevan caption.
filenameNombre del archivo, opcional (hasta 200 caracteres).
voiceSolo audio. true: se envía como nota de voz. false: como archivo de audio. Si no lo mandas, un OGG va como nota de voz y lo demás como archivo.

Como en el texto, la respuesta es 202 Accepted con status: "queued" y el envío ocurre en segundo plano.

Formatos y tamaños ​

TipoFormatos aceptadosTamaño máximo
imagejpeg, png, webp5 MB
audiompeg, ogg, mp4, aac, amr, x-m4a16 MB
videomp4, 3gpp16 MB
documentpdf, texto plano, csv, zip, Word, Excel, PowerPoint16 MB
stickerwebp (fijo o animado; idealmente 512×512)1 MB

Los tamaños son los valores por defecto de la plataforma.

Notas de voz ​

Con voice=true el audio llega como nota de voz (con su duración y su onda), igual que si lo grabaras en WhatsApp. ZAPPIO lo convierte a OGG/Opus, así que puedes mandar mp3, m4a, ogg, aac, amr o una grabación del navegador (webm) o wav.

bash
curl -X POST "https://zappio.cloud/api/v1/messages" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY" \
  -F instance=ins_... \
  -F to=5215500000000 \
  -F type=audio \
  -F voice=true \
  -F file=@nota.mp3

Si el archivo no se puede convertir (no es audio o está dañado), el mensaje termina en failed con el código MEDIA_CONVERSION_FAILED. webm y wav solo se aceptan con voice=true.

Errores ​

RespuestaCódigoCuándo
415INVALID_MEDIA_TYPEEl formato no se acepta para ese tipo de mensaje.
413MEDIA_TOO_LARGEEl archivo supera el límite de ese tipo.
413PAYLOAD_TOO_LARGELa petición completa supera el límite del servidor.

Descargar multimedia ​

Los mensajes con archivo (enviados o recibidos) traen media con mime_type, size, filename y available. Cuando available es true, descarga el archivo con:

bash
curl "https://zappio.cloud/api/v1/messages/msg_.../media" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY" -o archivo

Necesita el scope messages:read. Si el mensaje no tiene archivo guardado, responde 404 MEDIA_NOT_AVAILABLE.

En un mensaje recibido o enviado desde el teléfono del negocio, el evento (message.received o message.sent_external) llega antes que el archivo (available: false). Suscríbete a message.media_ready: llega cuando ya puedes descargarlo.

Los eventos de webhook no incluyen el archivo, solo sus metadatos: al recibir un message.received con multimedia, descárgalo con este endpoint.