Apariencia
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"| Campo | Qué es |
|---|---|
instance | Id de la instancia (ins_...). |
to | Número en formato internacional o id de grupo (grp_...). |
type | image, document, audio, video o sticker. |
file | El archivo. |
caption | Texto opcional de hasta 1024 caracteres. El audio y el sticker no llevan caption. |
filename | Nombre del archivo, opcional (hasta 200 caracteres). |
voice | Solo 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
| Tipo | Formatos aceptados | Tamaño máximo |
|---|---|---|
image | jpeg, png, webp | 5 MB |
audio | mpeg, ogg, mp4, aac, amr, x-m4a | 16 MB |
video | mp4, 3gpp | 16 MB |
document | pdf, texto plano, csv, zip, Word, Excel, PowerPoint | 16 MB |
sticker | webp (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.mp3Si 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
| Respuesta | Código | Cuándo |
|---|---|---|
| 415 | INVALID_MEDIA_TYPE | El formato no se acepta para ese tipo de mensaje. |
| 413 | MEDIA_TOO_LARGE | El archivo supera el límite de ese tipo. |
| 413 | PAYLOAD_TOO_LARGE | La 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 archivoNecesita 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.