Pular para conteúdo

Envio de Áudio

Visão Geral

Este endpoint permite o envio (upload), processamento e cadastro automático de arquivos de áudio e música de espera (MOH) na plataforma Voipper. O sistema realiza automaticamente a conversão dos arquivos para os formatos exigidos pela telefonia (WAV/RAW).

Recursos Disponíveis

  • Upload de arquivos de áudio via API (Multipart/Form-Data).
  • Conversão automática de MP3 para RAW (8kHz, Mono, Signed-Integer).
  • Classificação entre Áudio Padrão (URA/Mensagens) e Música de Espera (MOH).
  • Recarregamento automático do serviço de MOH no Asterisk (se aplicável).

Endpoints Principais

Enviar Arquivo de Áudio (POST)

POST /api/audio/upload/{API_TOKEN}/{API_KEY}

Nota: Este endpoint requer o envio de dados como multipart/form-data.

Parâmetros do Corpo (Body Parameters):
Parâmetro Tipo Obrigatório Descrição
client_id integer Sim ID do cliente (assinante) vinculado ao áudio.
file file Sim O arquivo de áudio. Apenas formato .mp3.
description string Não Descrição/Nome amigável para o arquivo. Se omitido, será gerado automaticamente.
is_moh integer Não Define o tipo de arquivo. 0 = Áudio Padrão (Mensagem/URA) - Default 1 = Música de Espera (MOH).
status integer Não Define o status inicial. 1 = Ativo - Default 0 = Inativo.

Exemplo de Requisição (cURL):

Bash

curl -X POST \
'https://call.voipper.com.br/api/audio/upload/TOKEN/KEY' \
-H 'Content-Type: multipart/form-data' \
-F 'client_id=100' \
-F 'description=Audio Promocional Natal' \
-F 'is_moh=0' \
-F 'status=1' \
-F 'file=@/caminho/para/meuarquivo.mp3'

Resposta de Sucesso (200 OK):

JSON

{
  "error": false,
  "success": true,
  "msg": "Arquivo enviado e processado com sucesso.",
  "data": {
    "id": 542,
    "file_name": "AUDIO_100-aB3dE9fG2h1",
    "duration": 45
  }
}

Resposta de Erro de Validação (200 OK com flag de erro):

JSON

{
  "error": true,
  "msg": "Apenas arquivos MP3 são permitidos."
}

Campos da Resposta
Campo Tipo Descrição
error boolean Indica se houve falha na operação (false = sucesso).
success boolean Confirmação da operação (true = sucesso).
msg string Mensagem descritiva do resultado.
data object Objeto contendo os metadados do arquivo criado.
data.id integer ID único do áudio gerado no banco de dados (tbaudio).
data.file_name string Nome interno do arquivo gerado no servidor (sem extensão).
data.duration integer Duração do áudio em segundos.

Tratamento de Erros
Código HTTP Status Causa Provável
403 Forbidden Token inválido ou usuário sem permissão de escrita no módulo manutAudio.
500 Internal Server Error Falha de permissão no diretório do servidor, erro na conversão (Lame/SoX) ou falha ao salvar no banco de dados.

Limitações e Boas Práticas

  • Formato de Arquivo: O sistema aceita apenas arquivos com extensão .mp3. Outros formatos serão rejeitados.
  • Conversão: O upload pode levar alguns segundos dependendo do tamanho do arquivo, pois o servidor realiza a conversão MP3 -> WAV -> RAW em tempo real.
  • Permissões: Certifique-se de que o usuário da API possui a permissão de escrita (W) habilitada no perfil de acesso.
  • Asterisk: Se is_moh=1, o comando moh reload é enviado automaticamente ao Asterisk. Evite uploads massivos simultâneos de MOH para não sobrecarregar o serviço de telefonia.