curl --request POST \
  --url https://api.wppfy.com/send/media \
  --header 'Content-Type: application/json' \
  --header 'token: <api-key>' \
  --data '
{
  "number": "5511999999999",
  "type": "image",
  "file": "https://exemplo.com/foto.jpg"
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "messageid": "<string>",
  "chatid": "<string>",
  "sender": "<string>",
  "senderName": "<string>",
  "isGroup": false,
  "fromMe": false,
  "messageType": "<string>",
  "source": "<string>",
  "messageTimestamp": 0,
  "status": "<string>",
  "text": "",
  "quoted": "",
  "edited": "",
  "reaction": "",
  "vote": "",
  "convertOptions": "",
  "buttonOrListid": "",
  "owner": "",
  "error": "",
  "content": {},
  "wasSentByApi": true,
  "pinned": true,
  "sendFunction": "<string>",
  "sendPayload": {},
  "fileURL": "<string>",
  "callPeer": {
    "jid": "<string>",
    "name": "<string>",
    "imagePreviewUrl": "<string>"
  },
  "send_folder_id": "<string>",
  "track_source": "<string>",
  "track_id": "<string>",
  "ai_metadata": {
    "agent_id": "<string>",
    "turn": "<string>",
    "flow_id": "<string>",
    "request": {
      "messages": "<array>",
      "tools": "<array>",
      "options": {
        "model": "<string>",
        "temperature": 123,
        "maxTokens": 123,
        "topP": 123,
        "frequencyPenalty": 123,
        "presencePenalty": 123
      }
    },
    "response": {
      "choices": "<array>",
      "toolResults": "<array>",
      "error": "<string>"
    },
    "outcome": {
      "status": "sent",
      "texts": 123,
      "audio": true,
      "menus": 123,
      "files": 123,
      "handoff": "<string>",
      "lead": [
        "<string>"
      ],
      "detail": "<string>"
    }
  },
  "sender_pn": "<string>",
  "sender_lid": "<string>",
  "sender_image_preview_url": "<string>",
  "response": {
    "status": "success",
    "message": "Media sent successfully",
    "fileUrl": "https://mmg.whatsapp.net/..."
  }
}

{
  "error": "Invalid media type or file format"
}

{
  "error": "Invalid token"
}

{
  "error": "File size exceeds limit"
}

{
  "error": "Unsupported media format"
}

{
  "error": "Failed to upload media"
}

Enviar Mensagem

Enviar mídia (imagem, vídeo, áudio ou documento)

Envia diferentes tipos de mídia para um contato, grupo ou canal/newsletter. Suporta URLs ou arquivos base64.

Tipos de Mídia Suportados

image: Imagens (JPG preferencialmente)
video: Vídeos (apenas MP4)
videoplay: Vídeo com comportamento visual de autoplay/loop no WhatsApp
document: Documentos (PDF, DOCX, XLSX, etc)
audio: Áudio comum (MP3 ou OGG)
myaudio: Mensagem de voz (alternativa ao PTT)
ptt: Mensagem de voz (Push-to-Talk)
ptv: Mensagem de vídeo (Push-to-Video)
sticker: Figurinha/Sticker

Recursos Específicos

Upload por URL ou base64
Caption/legenda opcional com suporte a placeholders
Nome personalizado para documentos (docName)
Geração automática de thumbnails para imagens e vídeos quando thumbnail não é informado
Compressão otimizada conforme o tipo
viewOnce recomendado para mídia compatível

Envio para Newsletter

Para enviar mídia para um canal, use o mesmo campo number, mas informe o JID completo do canal:

Exemplo: 120363123456789012@newsletter

{
  "number": "120363123456789012@newsletter",
  "type": "image",
  "file": "https://exemplo.com/foto.jpg",
  "text": "Imagem publicada no canal"
}

Campos Comuns

Este endpoint suporta todos os campos opcionais comuns documentados na tag “Enviar Mensagem”, incluindo: delay, readchat, readmessages, replyid, mentions, forward, track_source, track_id, placeholders e envio para grupos.

Exemplos Básicos

Visualização Única (`viewOnce`)

O campo viewOnce é recomendado quando quiser mídia de visualização única e hoje produz efeito para os tipos: image, video, videoplay, ptv, audio, myaudio e ptt.

Para document, sticker e demais endpoints de envio, o campo é ignorado silenciosamente.

Thumbnail personalizado

Use thumbnail em image, video, videoplay, ptv ou document. Aceita URL HTTP/HTTPS, Data URL ou base64 de imagem com até 1 MiB e 4096 px por dimensão. A API converte para JPEG e prioriza essa imagem em relação à miniatura automática. Para documentos, envie uma imagem de pelo menos 480 px para uma prévia mais nítida no WhatsApp Web. Documentos sem thumbnail não recebem miniatura automática.

Ao reenviar o mesmo documento, reutilize a mesma miniatura: o WhatsApp pode associar a prévia ao conteúdo do arquivo também em mensagens antigas.

Imagem Simples

{
  "number": "5511999999999",
  "type": "image",
  "file": "https://exemplo.com/foto.jpg"
}

Documento com Nome

{
  "number": "5511999999999",
  "type": "document",
  "file": "https://exemplo.com/contrato.pdf",
  "docName": "Contrato.pdf",
  "text": "Segue o documento solicitado"
}

POST

send

media

curl --request POST \
  --url https://api.wppfy.com/send/media \
  --header 'Content-Type: application/json' \
  --header 'token: <api-key>' \
  --data '
{
  "number": "5511999999999",
  "type": "image",
  "file": "https://exemplo.com/foto.jpg"
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "messageid": "<string>",
  "chatid": "<string>",
  "sender": "<string>",
  "senderName": "<string>",
  "isGroup": false,
  "fromMe": false,
  "messageType": "<string>",
  "source": "<string>",
  "messageTimestamp": 0,
  "status": "<string>",
  "text": "",
  "quoted": "",
  "edited": "",
  "reaction": "",
  "vote": "",
  "convertOptions": "",
  "buttonOrListid": "",
  "owner": "",
  "error": "",
  "content": {},
  "wasSentByApi": true,
  "pinned": true,
  "sendFunction": "<string>",
  "sendPayload": {},
  "fileURL": "<string>",
  "callPeer": {
    "jid": "<string>",
    "name": "<string>",
    "imagePreviewUrl": "<string>"
  },
  "send_folder_id": "<string>",
  "track_source": "<string>",
  "track_id": "<string>",
  "ai_metadata": {
    "agent_id": "<string>",
    "turn": "<string>",
    "flow_id": "<string>",
    "request": {
      "messages": "<array>",
      "tools": "<array>",
      "options": {
        "model": "<string>",
        "temperature": 123,
        "maxTokens": 123,
        "topP": 123,
        "frequencyPenalty": 123,
        "presencePenalty": 123
      }
    },
    "response": {
      "choices": "<array>",
      "toolResults": "<array>",
      "error": "<string>"
    },
    "outcome": {
      "status": "sent",
      "texts": 123,
      "audio": true,
      "menus": 123,
      "files": 123,
      "handoff": "<string>",
      "lead": [
        "<string>"
      ],
      "detail": "<string>"
    }
  },
  "sender_pn": "<string>",
  "sender_lid": "<string>",
  "sender_image_preview_url": "<string>",
  "response": {
    "status": "success",
    "message": "Media sent successfully",
    "fileUrl": "https://mmg.whatsapp.net/..."
  }
}

{
  "error": "Invalid media type or file format"
}

{
  "error": "Invalid token"
}

{
  "error": "File size exceeds limit"
}

{
  "error": "Unsupported media format"
}

{
  "error": "Failed to upload media"
}

Autorizações

token

string

header

obrigatório

Corpo

application/json

number

string

obrigatório

ID do chat para o qual a mensagem será enviada. Pode ser um número de telefone em formato internacional, um ID de grupo (@g.us), um ID de usuário (com @s.whatsapp.net ou @lid) ou um ID de canal/newsletter (@newsletter).

Exemplo:

"5511999999999"

type

enum<string>

obrigatório

Tipo de mídia (image, video, videoplay, document, audio, myaudio, ptt, ptv, sticker)

Opções disponíveis:

image,

video,

videoplay,

document,

audio,

myaudio,

ptt,

ptv,

sticker

Exemplo:

"image"

file

string

obrigatório

URL ou base64 do arquivo

Exemplo:

"https://exemplo.com/imagem.jpg"

text

string

Texto descritivo (caption) - aceita placeholders

Exemplo:

"Veja esta foto!"

docName

string

Nome do arquivo (apenas para documents)

Exemplo:

"relatorio.pdf"

thumbnail

string

URL HTTP/HTTPS, Data URL ou base64 de imagem para image, video, videoplay, ptv e document. Até 1 MiB e 4096 px por dimensão. Tem prioridade sobre a miniatura automática; documentos sem este campo não recebem miniatura automática.

Exemplo:

"https://exemplo.com/thumb.jpg"

mimetype

string

MIME type do arquivo (opcional, detectado automaticamente)

Exemplo:

"application/pdf"

replyid

string

ID da mensagem para responder

Exemplo:

"3EB0538DA65A59F6D8A251"

mentions

string

Números para mencionar (separados por vírgula)

Exemplo:

"5511999999999,5511888888888"

readchat

boolean

Marca conversa como lida após envio

Exemplo:

true

readmessages

boolean

Marca últimas mensagens recebidas como lidas

Exemplo:

true

delay

integer

Atraso em milissegundos antes do envio, durante o atraso apacerá 'Digitando...' ou 'Gravando áudio...'

Exemplo:

1000

forward

boolean

Marca a mensagem como encaminhada no WhatsApp

Exemplo:

true

track_source

string

Origem do rastreamento da mensagem

Exemplo:

"chatwoot"

track_id

string

ID para rastreamento da mensagem (aceita valores duplicados)

Exemplo:

"msg_123456789"

async

boolean

Se true, envia a mensagem de forma assíncrona via fila interna

Exemplo:

false

viewOnce

boolean

Recomendado para mídia com visualização única em tipos compatíveis (image, video, videoplay, ptv, audio, myaudio, ptt). Em tipos não compatíveis, o campo é ignorado silenciosamente.

Exemplo:

false

Resposta

Mídia enviada com sucesso

Representa uma mensagem trocada no sistema

string<uuid>

ID único interno da mensagem (formato r + 7 caracteres hex aleatórios)

messageid

string

ID original da mensagem no provedor

chatid

string

ID da conversa relacionada

sender

string

ID do remetente da mensagem

senderName

string

Nome exibido do remetente

isGroup

boolean

padrão:false

Indica se é uma mensagem de grupo

fromMe

boolean

padrão:false

Indica se a mensagem foi enviada pelo usuário

messageType

string

Tipo de conteúdo da mensagem

source

string

Plataforma de origem da mensagem

messageTimestamp

integer

padrão:0

Timestamp original da mensagem em milissegundos

status

string

Status do ciclo de vida da mensagem. Exemplos comuns: Queued, Canceled, Failed, Sent, Delivered, Read. Em mensagem de grupo, segue o participante mais adiantado: Delivered quando pelo menos um recebeu, Read quando pelo menos um leu e Played quando pelo menos um ouviu.

text

string

padrão:""

Texto original da mensagem

quoted

string

padrão:""

ID da mensagem citada/respondida

edited

string

padrão:""

Histórico de edições da mensagem

reaction

string

padrão:""

ID da mensagem reagida

vote

string

padrão:""

Dados de votação de enquete e listas

convertOptions

string

padrão:""

Conversão de opções da mensagem, lista, enquete e botões

buttonOrListid

string

padrão:""

ID do botão ou item de lista selecionado

owner

string

padrão:""

Dono da mensagem

error

string

padrão:""

Mensagem de erro caso o envio tenha falhado

content

Conteúdo bruto da mensagem (JSON serializado ou texto)

wasSentByApi

boolean

Indica se a mensagem foi enviada via API

pinned

boolean

Mensagem fixada na conversa (fixar e desafixar chegam também em messages_update, tipos Pinned e Unpinned)

sendFunction

string

Função usada para enviar a mensagem (quando enviada via API)

sendPayload

Payload usado no envio quando disponível. Dados de mídia em base64 são omitidos.

fileURL

string

URL ou referência de arquivo da mensagem

callPeer

object

Contato conhecido associado a uma ligação, quando disponível em messageType: call.

Show child attributes

send_folder_id

string

Pasta associada ao envio (quando aplicável)

track_source

string

Origem de rastreamento

track_id

string

ID de rastreamento (pode repetir)

ai_metadata

object

Registro de uma rodada da IA. O completo (pedido ao modelo, resposta e outcome) fica uma vez, na última mensagem do contato que a rodada respondeu, também quando nada saiu (erro, resposta descartada). Cada mensagem enviada pela IA leva só agent_id e turn (o id dessa mensagem do contato).

Show child attributes

sender_pn

string | null

JID PN resolvido do remetente (quando disponível)

sender_lid

string | null

LID original do remetente (quando disponível)

sender_image_preview_url

string<uri>

URL temporária de preview do remetente, quando conhecida. A hidratação desta versão preenche mensagens recebidas em grupos; o campo pode ser omitido. Não provoca consulta de foto ao WhatsApp na listagem.

response

object

Show child attributes

Instancia

CRM

Proxy

Perfil

Enviar Mensagem

Mensagem Async

Ações na mensagem e Buscar

Grupos e Comunidades

Newsletters e Canais

Server-Sent Events (SSE)

Bloqueios

Etiquetas

Chats

Contatos

Chamadas

Integração Chatwoot

Business

Respostas Rápidas

Enviar mídia (imagem, vídeo, áudio ou documento)

Tipos de Mídia Suportados

Recursos Específicos

Envio para Newsletter

Campos Comuns

Exemplos Básicos

Visualização Única (`viewOnce`)

Thumbnail personalizado

Imagem Simples

Documento com Nome

Autorizações

Corpo

Resposta