Mensagem de Áudio

O tipo AUDIO permite enviar arquivos de áudio e notas de voz para o destinatário.

Payload

{
  "channelId": "uuid-do-canal",
  "content": {
    "type": "AUDIO",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "base64": "T2dnUwACAAAAAAAAAAA...",
    "filename": "mensagem-voz.ogg",
    "mimetype": "audio/ogg; codecs=opus",
    "isPTT": true
  }
}

Campos

string

required

Deve ser "AUDIO".

Address

required

Endereço do destinatário. Veja formatos de endereço.

string

Conteúdo do áudio codificado em Base64. Use este campo ou uma das URLs de download (downloadUrl / externalDownloadUrl). O limite recomendado para envio via Base64 é de aproximadamente 70 MB.

string

URL pública para download do áudio. Use este campo ou base64.

string

URL externa alternativa para download do áudio. Assim como downloadUrl, é uma opção de origem do arquivo quando você não envia base64.

string

Identificador da mídia no storage da plataforma. Presente principalmente em mensagens recebidas, referenciando o arquivo já armazenado.

string

URL de download da mídia diretamente no provedor. Aparece tipicamente em mensagens recebidas.

string

required

Nome do arquivo de áudio. Obrigatório para mensagens de mídia — a ausência retorna 400.

integer

default:"0"

Duração do áudio em segundos. Opcional; usado para exibir a duração correta da nota de voz.

string

Tipo MIME do áudio. Importante para que o provedor reproduza corretamente.

string

Legenda opcional associada ao áudio.

boolean

default:"false"

Marca o áudio como nota de voz push-to-talk (PTT). Quando true, o WhatsApp exibe o áudio como nota de voz (bolha com forma de onda) em vez de um arquivo de áudio genérico. Padrão: false.

Para que o áudio apareça como nota de voz (bolha azul com forma de onda) no WhatsApp, envie isPTT: true e use o formato OGG com codec Opus (audio/ogg; codecs=opus). Sem esses parâmetros, o áudio é enviado como arquivo de áudio genérico.

Formatos Suportados

Formato	MIME Type	Nota de Voz no WhatsApp?
OGG Opus	`audio/ogg; codecs=opus`	Sim — exibe como nota de voz (com `isPTT: true`)
MP3	`audio/mpeg`	Não — exibe como arquivo de áudio
AAC	`audio/aac`	Não — exibe como arquivo de áudio
WAV	`audio/wav`	Não — exibe como arquivo de áudio
M4A	`audio/mp4`	Não — exibe como arquivo de áudio

Exemplos

Nota de voz (OGG Opus)

curl -X POST https://api-dev.messagefy.io/api/v1/message/SendMessage \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: sua-api-key-aqui" \
  -d '{
    "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "content": {
      "type": "AUDIO",
      "to": {
        "type": "WHATSAPP",
        "number": "5511999999999"
      },
      "base64": "T2dnUwACAAAAAAAAAABdxd4RAAAAAG3M9ZIBH...",
      "filename": "nota-de-voz.ogg",
      "mimetype": "audio/ogg; codecs=opus",
      "isPTT": true
    }
  }'

import requests
import base64

with open("nota-de-voz.ogg", "rb") as f:
    audio_base64 = base64.b64encode(f.read()).decode("utf-8")

response = requests.post(
    "https://api-dev.messagefy.io/api/v1/message/SendMessage",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "sua-api-key-aqui"
    },
    json={
        "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "content": {
            "type": "AUDIO",
            "to": {
                "type": "WHATSAPP",
                "number": "5511999999999"
            },
            "base64": audio_base64,
            "filename": "nota-de-voz.ogg",
            "mimetype": "audio/ogg; codecs=opus",
            "isPTT": True
        }
    }
)
print(response.json())

import { readFileSync } from "fs";

const audioBase64 = readFileSync("nota-de-voz.ogg").toString("base64");

const response = await fetch(
  "https://api-dev.messagefy.io/api/v1/message/SendMessage",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": "sua-api-key-aqui",
    },
    body: JSON.stringify({
      channelId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      content: {
        type: "AUDIO",
        to: {
          type: "WHATSAPP",
          number: "5511999999999",
        },
        base64: audioBase64,
        filename: "nota-de-voz.ogg",
        mimetype: "audio/ogg; codecs=opus",
        isPTT: true,
      },
    }),
  }
);
const data = await response.json();
console.log(data);

Áudio via URL

{
  "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "content": {
    "type": "AUDIO",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "downloadUrl": "https://cdn.suaempresa.com/audios/atendimento-resposta.ogg",
    "filename": "resposta-atendimento.ogg",
    "mimetype": "audio/ogg; codecs=opus",
    "isPTT": true
  }
}

Arquivo MP3

{
  "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "content": {
    "type": "AUDIO",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "downloadUrl": "https://cdn.suaempresa.com/audios/jingle-promocional.mp3",
    "filename": "promocao-natal.mp3",
    "mimetype": "audio/mpeg"
  }
}

Se sua aplicação gera áudio sintetizado (TTS — Text-to-Speech), converta para o formato OGG Opus antes de enviar. Ferramentas como ffmpeg podem fazer isso facilmente: ffmpeg -i audio.mp3 -c:a libopus audio.ogg

Resposta

{
  "packageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Recebimento

Quando o canal recebe um áudio, a plataforma entrega um webhook com content.type igual a "AUDIO". O conteúdo carrega os mesmos campos de mídia usados no envio, além do envelope comum do pacote e dos campos base de mensagem.

Diferente do envio, mensagens recebidas trazem from (remetente) e referências de mídia como mediaId, downloadUrl e externalDownloadUrl em vez do base64 inline. O download do arquivo pode ficar disponível de forma assíncrona através do evento DOWNLOAD_AVAILABLE.

{
  "packageId": "019a1234-5678-7abc-def0-123456789ac4",
  "channelId": "019a1258-177c-7286-b060-9ee02a0800c7",
  "correlationId": null,
  "content": {
    "type": "AUDIO",
    "mediaId": "5f3a9c1e-2b74-4d8a-9e2f-1c6b0d8a7e33",
    "downloadUrl": "https://storage.messagefy.io/media/5f3a9c1e-audio.ogg",
    "externalDownloadUrl": "https://cdn.provedor.com/audio/5f3a9c1e.ogg",
    "filename": "audio.ogg",
    "mimetype": "audio/ogg; codecs=opus",
    "isPTT": true,
    "from": {
      "type": "WHATSAPP",
      "jid": "5511999998888@s.whatsapp.net",
      "number": "5511999998888",
      "name": "Cliente"
    },
    "to": {
      "type": "WHATSAPP",
      "jid": "5511988887777@s.whatsapp.net",
      "number": "5511988887777",
      "name": "Minha Empresa"
    },
    "messageId": "3EB08209536937A66D8437",
    "isFromMe": false,
    "isGroupMessage": false,
    "isForwarded": false,
    "isStatusMessage": false,
    "isHistoryMessage": false,
    "timestamp": "2025-12-01T14:37:00+00:00"
  },
  "timestamp": "2025-12-01T14:37:00.100+00:00",
  "providerMetadata": null
}

Campos recebidos

string

Sempre "AUDIO".

string

Identificador da mídia no storage da plataforma.

string

URL de download do áudio.

string

URL de download do áudio diretamente no provedor.

string

URL externa de download do áudio.

string

Nome do arquivo de áudio.

string

Tipo MIME do áudio (ex.: audio/ogg).

boolean

true quando o áudio foi enviado como nota de voz push-to-talk.

Address

Endereço do remetente. Veja formatos de endereço.

Address

Endereço do destinatário (o seu canal).

string

Identificador da mensagem no WhatsApp. Guarde-o para responder ou reagir à mensagem posteriormente.

boolean

Indica se a mensagem foi enviada pelo próprio canal.

boolean

Indica se a mensagem veio de um grupo.

boolean

Indica se a mensagem foi encaminhada.

boolean

Indica se a mensagem é de status (story).

boolean

Indica se a mensagem veio de uma sincronização de histórico.

boolean

true se a mensagem foi enviada para uma lista de transmissão (broadcast list).

boolean

true se a mensagem foi enviada para um grupo de avisos da comunidade.

boolean

true se a mensagem foi enviada para o grupo de avisos da comunidade.

true se a mensagem foi enviada para um canal/newsletter.

Para o envelope completo do pacote recebido (packageId, correlationId, channelId, timestamp, providerMetadata, echoMessage) consulte Recebendo Eventos.

Início

Contas

API Keys

Canais

WhatsApp Oficial

Tipos de Mensagem

Operações de Mensagem

Sessão e Conexão

Consultas

Interação

Mensagem de Áudio

Mensagem de Áudio

Payload

Campos

Formatos Suportados

Exemplos

Nota de voz (OGG Opus)

Áudio via URL

Arquivo MP3

Resposta

Recebimento

Campos recebidos

​Mensagem de Áudio

​Payload

​Campos

​Formatos Suportados

​Exemplos

​Nota de voz (OGG Opus)

​Áudio via URL

​Arquivo MP3

​Resposta

​Recebimento

​Campos recebidos

Mensagem de Áudio

Payload

Campos

Formatos Suportados

Exemplos

Nota de voz (OGG Opus)

Áudio via URL

Arquivo MP3

Resposta

Recebimento

Campos recebidos