> ## Documentation Index
> Fetch the complete documentation index at: https://docs.messagefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Mensagem de Áudio

> Envie mensagens de áudio e notas de voz via WhatsApp e outros canais

# Mensagem de Áudio

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

## Payload

```json theme={null}
{
  "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

<ParamField body="content.type" type="string" required>
  Deve ser `"AUDIO"`.
</ParamField>

<ParamField body="content.to" type="Address" required>
  Endereço do destinatário. Veja [formatos de endereço](/mensagens/visao-geral#enderecamento-address).
</ParamField>

<ParamField body="content.base64" type="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.
</ParamField>

<ParamField body="content.downloadUrl" type="string">
  URL pública para download do áudio. Use este campo **ou** `base64`.
</ParamField>

<ParamField body="content.externalDownloadUrl" type="string">
  URL externa alternativa para download do áudio. Assim como `downloadUrl`, é uma opção de origem do arquivo quando você não envia `base64`.
</ParamField>

<ParamField body="content.mediaId" type="string">
  Identificador da mídia no storage da plataforma. Presente principalmente em mensagens **recebidas**, referenciando o arquivo já armazenado.
</ParamField>

<ParamField body="content.downloadProviderUrl" type="string">
  URL de download da mídia diretamente no provedor. Aparece tipicamente em mensagens **recebidas**.
</ParamField>

<ParamField body="content.filename" type="string" required>
  Nome do arquivo de áudio. **Obrigatório** para mensagens de mídia -- a ausência retorna `400`.
</ParamField>

<ParamField body="content.seconds" type="integer" default="0">
  Duração do áudio em segundos. Opcional; usado para exibir a duração correta da nota de voz.
</ParamField>

<ParamField body="content.mimetype" type="string">
  Tipo MIME do áudio. Importante para que o provedor reproduza corretamente.
</ParamField>

<ParamField body="content.caption" type="string">
  Legenda opcional associada ao áudio.
</ParamField>

<ParamField body="content.isPTT" type="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`.
</ParamField>

<Warning>
  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.
</Warning>

## 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)

<CodeGroup>
  ```bash cURL theme={null}
  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
      }
    }'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript Node.js theme={null}
  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);
  ```
</CodeGroup>

### Áudio via URL

```json theme={null}
{
  "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

```json theme={null}
{
  "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"
  }
}
```

<Tip>
  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`
</Tip>

## Resposta

```json theme={null}
{
  "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.

<Note>
  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`](/recebendo-eventos).
</Note>

```json theme={null}
{
  "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

<ResponseField name="content.type" type="string">
  Sempre `"AUDIO"`.
</ResponseField>

<ResponseField name="content.mediaId" type="string">
  Identificador da mídia no storage da plataforma.
</ResponseField>

<ResponseField name="content.downloadUrl" type="string">
  URL de download do áudio.
</ResponseField>

<ResponseField name="content.downloadProviderUrl" type="string">
  URL de download do áudio diretamente no provedor.
</ResponseField>

<ResponseField name="content.externalDownloadUrl" type="string">
  URL externa de download do áudio.
</ResponseField>

<ResponseField name="content.filename" type="string">
  Nome do arquivo de áudio.
</ResponseField>

<ResponseField name="content.mimetype" type="string">
  Tipo MIME do áudio (ex.: `audio/ogg`).
</ResponseField>

<ResponseField name="content.isPTT" type="boolean">
  `true` quando o áudio foi enviado como nota de voz *push-to-talk*.
</ResponseField>

<ResponseField name="content.from" type="Address">
  Endereço do remetente. Veja [formatos de endereço](/mensagens/visao-geral#enderecamento-address).
</ResponseField>

<ResponseField name="content.to" type="Address">
  Endereço do destinatário (o seu canal).
</ResponseField>

<ResponseField name="content.messageId" type="string">
  Identificador da mensagem no WhatsApp. Guarde-o para responder ou reagir à mensagem posteriormente.
</ResponseField>

<ResponseField name="content.isFromMe" type="boolean">
  Indica se a mensagem foi enviada pelo próprio canal.
</ResponseField>

<ResponseField name="content.isGroupMessage" type="boolean">
  Indica se a mensagem veio de um grupo.
</ResponseField>

<ResponseField name="content.isForwarded" type="boolean">
  Indica se a mensagem foi encaminhada.
</ResponseField>

<ResponseField name="content.isStatusMessage" type="boolean">
  Indica se a mensagem é de status (story).
</ResponseField>

<ResponseField name="content.isHistoryMessage" type="boolean">
  Indica se a mensagem veio de uma sincronização de histórico.
</ResponseField>

<ResponseField name="content.isBroadcast" type="boolean">
  `true` se a mensagem foi enviada para uma lista de transmissão (broadcast list).
</ResponseField>

<ResponseField name="content.isAnnounceGroup" type="boolean">
  `true` se a mensagem foi enviada para um grupo de avisos da comunidade.
</ResponseField>

<ResponseField name="content.isCommunityNotices" type="boolean">
  `true` se a mensagem foi enviada para o grupo de avisos da comunidade.
</ResponseField>

<ResponseField name="content.isNewsletter" type="boolean">
  `true` se a mensagem foi enviada para um canal/newsletter.
</ResponseField>

<Note>
  Para o envelope completo do pacote recebido (`packageId`, `correlationId`, `channelId`, `timestamp`, `providerMetadata`, `echoMessage`) consulte [Recebendo Eventos](/recebendo-eventos).
</Note>