Envio de mídia

Mídia (imagens, áudios, vídeos, documentos e figurinhas) é enviada pelo mesmo endpoint POST /v1/messages usado para texto. Os campos de mídia ficam dentro do objeto content. O tipo vem do campo âncora presente (image_url, video_url, audio_url, document_url ou sticker_url).

Usando números extras?

Para enviar mídia a partir de um número extra, use /v1/numbers/{ref}/messages onde {ref} é o alias do seu número extra (ou o id dele, num_…). Saiba mais.

Tipos de mídia suportados

Variante	Campo âncora	Formatos comuns	Tamanho máximo	caption?	filename?
image	image_url	JPEG, PNG, WebP	16 MB	✓	—
video	video_url	MP4	100 MB	✓	—
audio	audio_url	MP3, OGG, M4A	16 MB	—	—
document	document_url	PDF, DOCX, XLSX, etc.	100 MB	✓	✓
sticker	sticker_url	WebP (estático ou animado), exatamente 512×512px	500 KB	—	—

caption não é aceito em audio e sticker. A API retorna 422 se o campo for enviado nesses tipos.

Depois do envio, só a legenda de imagem, vídeo e documento pode ser editada. O arquivo, o áudio e a figurinha não podem: apagar é a única alteração. Veja o que pode ser alterado depois do envio.

Modalidade: URL pública

Informe uma URL HTTPS acessível publicamente. O Turbo Notify baixa o arquivo antes de entregá-lo ao WhatsApp.

Imagem

cURL

send-image.sh

curl -X POST \
  https://api.turbonotify.com/v1/messages \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {"number": "+5511988887777"},
    "content": {
      "image_url": "https://cdn.exemplo.com/foto-produto.jpg",
      "mime_type": "image/jpeg",
      "caption": "Foto do produto"
    }
  }'

Node

send-image.js

await fetch('https://api.turbonotify.com/v1/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SUA_CHAVE',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: { number: '+5511988887777' },
    content: {
      image_url: 'https://cdn.exemplo.com/foto-produto.jpg',
      mime_type: 'image/jpeg',
      caption: 'Foto do produto'
    }
  })
});

Python

send_image.py

import requests

requests.post(
    "https://api.turbonotify.com/v1/messages",
    headers={
        "Authorization": "Bearer SUA_CHAVE",
        "Content-Type": "application/json",
    },
    json={
        "to": {"number": "+5511988887777"},
        "content": {
            "image_url": "https://cdn.exemplo.com/foto-produto.jpg",
            "mime_type": "image/jpeg",
            "caption": "Foto do produto",
        },
    },
)

Menções na legenda

O caption de imagem aceita tokens de menção @<numero> (por exemplo "caption": "Confere essa foto, @5511977776666?") com as mesmas regras do text: a menção é detectada no próprio texto, os dígitos vão em E.164 sem + e um token inválido fica como texto comum, sem impedir o envio. Veja Menções (@mentions).

Vídeo

cURL

send-video.sh

curl -X POST \
  https://api.turbonotify.com/v1/messages \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {"number": "+5511988887777"},
    "content": {
      "video_url": "https://cdn.exemplo.com/clip-produto.mp4",
      "mime_type": "video/mp4",
      "caption": "Veja o vídeo"
    }
  }'

Node

send-video.js

await fetch('https://api.turbonotify.com/v1/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SUA_CHAVE',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: { number: '+5511988887777' },
    content: {
      video_url: 'https://cdn.exemplo.com/clip-produto.mp4',
      mime_type: 'video/mp4',
      caption: 'Veja o vídeo'
    }
  })
});

Python

send_video.py

import requests

requests.post(
    "https://api.turbonotify.com/v1/messages",
    headers={
        "Authorization": "Bearer SUA_CHAVE",
        "Content-Type": "application/json",
    },
    json={
        "to": {"number": "+5511988887777"},
        "content": {
            "video_url": "https://cdn.exemplo.com/clip-produto.mp4",
            "mime_type": "video/mp4",
            "caption": "Veja o vídeo",
        },
    },
)

O caption de vídeo também aceita menções @<numero>.

Áudio

cURL

send-audio.sh

curl -X POST \
  https://api.turbonotify.com/v1/messages \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {"number": "+5511988887777"},
    "content": {
      "audio_url": "https://cdn.exemplo.com/audio.ogg",
      "mime_type": "audio/ogg"
    }
  }'

Node

send-audio.js

await fetch('https://api.turbonotify.com/v1/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SUA_CHAVE',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: { number: '+5511988887777' },
    content: {
      audio_url: 'https://cdn.exemplo.com/audio.ogg',
      mime_type: 'audio/ogg'
    }
  })
});

Python

send_audio.py

import requests

requests.post(
    "https://api.turbonotify.com/v1/messages",
    headers={
        "Authorization": "Bearer SUA_CHAVE",
        "Content-Type": "application/json",
    },
    json={
        "to": {"number": "+5511988887777"},
        "content": {
            "audio_url": "https://cdn.exemplo.com/audio.ogg",
            "mime_type": "audio/ogg",
        },
    },
)

mime_type é opcional e não muda como o arquivo é enviado: o formato que o WhatsApp recebe vem do que o próprio servidor da URL entrega.

Áudio chega como arquivo, não como mensagem de voz

O áudio enviado pela API sempre chega como arquivo de áudio, com a barra de reprodução comum. Não existe parâmetro que o transforme em mensagem de voz (aquela gravada segurando o microfone), e mime_type não faz isso: ele só descreve o formato.

Documento

cURL

send-document.sh

curl -X POST \
  https://api.turbonotify.com/v1/messages \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {"number": "+5511988887777"},
    "content": {
      "document_url": "https://cdn.exemplo.com/fatura.pdf",
      "mime_type": "application/pdf",
      "filename": "Fatura-Abril.pdf",
      "caption": "Sua fatura do mês de abril"
    }
  }'

Node

send-document.js

await fetch('https://api.turbonotify.com/v1/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SUA_CHAVE',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: { number: '+5511988887777' },
    content: {
      document_url: 'https://cdn.exemplo.com/fatura.pdf',
      mime_type: 'application/pdf',
      filename: 'Fatura-Abril.pdf',
      caption: 'Sua fatura do mês de abril'
    }
  })
});

Python

send_document.py

import requests

requests.post(
    "https://api.turbonotify.com/v1/messages",
    headers={
        "Authorization": "Bearer SUA_CHAVE",
        "Content-Type": "application/json",
    },
    json={
        "to": {"number": "+5511988887777"},
        "content": {
            "document_url": "https://cdn.exemplo.com/fatura.pdf",
            "mime_type": "application/pdf",
            "filename": "Fatura-Abril.pdf",
            "caption": "Sua fatura do mês de abril",
        },
    },
)

filename aparece como o nome do anexo no chat do destinatário. O caption de documento também aceita menções @<numero>.

Figurinha (sticker)

cURL

send-sticker.sh

curl -X POST \
  https://api.turbonotify.com/v1/messages \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {"number": "+5511988887777"},
    "content": {
      "sticker_url": "https://cdn.exemplo.com/sticker-animado.webp",
      "mime_type": "image/webp"
    }
  }'

Node

send-sticker.js

await fetch('https://api.turbonotify.com/v1/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SUA_CHAVE',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: { number: '+5511988887777' },
    content: {
      sticker_url: 'https://cdn.exemplo.com/sticker-animado.webp',
      mime_type: 'image/webp'
    }
  })
});

Python

send_sticker.py

import requests

requests.post(
    "https://api.turbonotify.com/v1/messages",
    headers={
        "Authorization": "Bearer SUA_CHAVE",
        "Content-Type": "application/json",
    },
    json={
        "to": {"number": "+5511988887777"},
        "content": {
            "sticker_url": "https://cdn.exemplo.com/sticker-animado.webp",
            "mime_type": "image/webp",
        },
    },
)

Stickers devem ser WebP (estático ou animado), com dimensões exatas de 512×512 pixels (qualquer outra dimensão é rejeitada mesmo que o WebP seja válido) e respeitar o limite de 500 KB.

Esquema de campos (todos os tipos)

Os campos de mídia ficam dentro do objeto content. O campo âncora (ex.: image_url) determina a variante. Todo envio de mídia é feito por URL pública; não é possível enviar um arquivo informando apenas a chave dele no seu BYO Storage.

Campo em content	Tipo	Obrigatório	Notas
image_url	URL	condicional	Campo âncora para imagens; URL pública HTTPS
video_url	URL	condicional	Campo âncora para vídeos; URL pública HTTPS
audio_url	URL	condicional	Campo âncora para áudios; URL pública HTTPS
document_url	URL	condicional	Campo âncora para documentos; URL pública HTTPS
sticker_url	URL	condicional	Campo âncora para figurinhas; URL pública HTTPS
mime_type	string	não	opcional e informativo: não altera o envio. O formato é identificado a partir do próprio arquivo baixado da URL
caption	string	parcial	aceito em image, video, document; não aceito em audio e sticker (retorna 422). Aceita tokens de menção @<numero>, detecção implícita, mesmas regras do text
filename	string	não	apenas em document; aparece como nome do anexo no chat

Resposta

Status HTTP: 202

{
  "message_id": "msg_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "status": {
    "state": "pending",
    "at": "2026-04-27T10:00:05Z",
    "error": null
  }
}

A confirmação real chega via webhook message.sent. Em caso de falha (URL inacessível, formato não suportado, tamanho excedido) você recebe message.send.failed com um objeto error ({ code, message, hint }) específico.

Webhook outbound

Quando o envio é confirmado pelo WhatsApp, o webhook message.sent traz content_type e preview (mesmo formato de message.received):

webhook-message-sent.json

{
  "id": "evt_3f9a1c2b4d5e6f708192a3b4c5d6e7f8",
  "type": "message.sent",
  "organization_id": "org_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "number_alias": "main",
  "number_id": "num_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "created_at": "2026-04-27T10:00:08Z",
  "data": {
    "id": "msg_a1b2c3d4e5f60718293a4b5c6d7e8f90",
    "from": { "alias": "main", "number": "5511973117056" },
    "to":   { "number": "5511988887777" },
    "preview": "Foto do produto",
    "content_type": "image",
    "direction": "outbound",
    "channel": "whatsapp",
    "origin": "tn",
    "at": "2026-04-27T10:00:08Z"
  }
}

Para baixar o arquivo de uma mídia recebida, consulte GET /v1/numbers/{ref}/messages/{id}: os campos de mídia aparecem diretamente no objeto específico do content_type (image, video, audio, document, sticker), sem sub-objeto media. Com BYO Object Storage configurado, esse objeto vem com kind: "available" e url contendo a URL pré-assinada de download.

Relacionado

• Envio de mensagens: texto, localização, contato, calendário (mesmo endpoint).
• Webhook outbound: payloads de message.sent e message.delivered.
• Consultar mensagem: obter o conteúdo completo, inclusive mídia.