Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🎙️Ligações - Áudios

Os Áudios são as gravações que a plataforma toca quando disca para os seus contatos. Através destes endpoints você pode criar um áudio (enviando um arquivo ou gerando a locução a partir de um texto), listar, consultar, renomear, configurar as ações de teclado (DTMF) e remover.

É o mesmo recurso da tela Áudios do painel: o áudio criado pela API aparece lá, e vice-versa. O mesmo áudio serve tanto para um Broadcast de Voz quanto para uma sequência de voz dentro de uma campanha.

A URL de base de todos os endpoints é: https://web.smsfunnel.com.br/api/parceiros/v1

Os endpoints de listagem utilizam paginação simples. A resposta traz current_page, data, per_page, next_page_url e prev_page_url — não há campos total ou last_page. Para navegar, utilize o parâmetro de query page.

Os endpoints ficam sob /calls/. O prefixo é do canal, não do fornecedor — os endpoints legados /call4u/* (ligação avulsa) continuam existindo e não mudaram.

Fluxo de uso

1. POST /calls/audios          → cria o áudio                (audio_id)
2. GET  /calls/audios/{id}     → repete até "ready": true
3. POST /calls/broadcasts      → dispara usando o audio_id

Status possíveis

Status do áudio (status): processing (medindo duração e transcodificando), approved (pronto para uso), rejected (recusado — veja rejection_reason) e error (falha no processamento).

Não interprete o status diretamente. Use o booleano ready: ele é true apenas quando o áudio já foi processado e pode ser usado em um disparo. Enquanto ready for false, os campos duration_seconds e credits_per_call ainda valem 0.

Créditos

O custo é de 1 crédito de ligação a cada 30 segundos de áudio, arredondado para cima, por ligação atendida — é o valor devolvido em credits_per_call. Multiplicado pelo tamanho da lista, ele dá o custo máximo de um disparo.

Criar um áudio por upload não consome crédito. Criar por TTS consome, porque a locução é gerada por um provedor pago — inclusive na pré-escuta (preview-tts).

Endpoints

GET /calls/audios

Função: Lista os seus áudios, do mais recente para o mais antigo.

Parâmetros de query (opcionais):

Corpo de resposta — 200 OK:

O campo rejection_reason só aparece quando o status é rejected ou error, explicando o motivo da recusa.

O caminho do arquivo (file_path/file_url) não faz parte do contrato: o áudio é servido ao discador, não ao integrador.

POST /calls/audios

Função: Cria um áudio. Há dois caminhos, escolhidos pelo campo type: enviar um arquivo (upload) ou deixar a plataforma gerar a locução a partir de um texto (tts).

Corpo de envio — locução gerada (type: "tts", application/json):

Corpo de envio — arquivo (type: "upload", multipart/form-data):

Campo
Valor

title

Obrigatório. Até 255 caracteres.

type

Obrigatório. upload.

file

Obrigatório. MP3, WAV, OGG ou M4A. Até 10 MB e 30 segundos.

tts_text

Opcional. Transcrição do áudio, para você reconhecê-lo depois sem precisar ouvi-lo.

actions

Opcional. Neste formato, envie como string JSON: [{"dtmf_key":"1","action_type":"mark_interested"}]

Corpo de resposta — 202 Accepted:

A resposta é 202, e não 201. O áudio já existe, mas ainda não serve para disparar: a plataforma precisa medir a duração e transcodificá-lo para o formato que o discador reproduz.

Consulte GET /calls/audios/{id} até que ready seja true. Só então duration_seconds e credits_per_call são válidos, e só então um disparo aceita este audio_id (antes disso, 422 AUDIO_NOT_READY).

Áudio acima de 30 segundos é recusado — inclusive no TTS. No TTS a recusa acontece depois de gerar a locução: um texto longo custa a chamada ao provedor e ainda assim retorna 422. Encurte o texto antes de enviar.

GET /calls/audios/{id}

Função: Consulta um áudio específico. A resposta tem exatamente o mesmo formato dos itens de data na listagem.

É este o endpoint a ser consultado repetidamente após a criação, até que ready seja true.

Áudio inexistente ou de outra conta retorna 404 NOT_FOUND.

PUT /calls/audios/{id} Função: Renomeia o áudio e reconfigura as suas ações de teclado (DTMF). Atualização parcial: envie apenas os campos que deseja alterar.

Corpo de envio:

Corpo de resposta — 200 OK: o áudio atualizado, no mesmo formato do GET /calls/audios/{id}.

O campo actions, quando presente, substitui todas as ações existentes. Envie [] para remover todas, ou omita o campo para preservar as atuais.

Este endpoint não troca o áudio. Os campos type, file e tts_voice_id são recusados com 422, e tts_text aqui apenas corrige a transcrição gravada — não regera a locução. O que o contato escuta continua sendo o mesmo arquivo.

Para mudar o áudio, crie outro e aponte o disparo para o novo audio_id. O motivo: a duração já entrou no cálculo de créditos dos disparos que usam este áudio, e trocar o arquivo mudaria o custo de um disparo em andamento.

DELETE /calls/audios/{id}

Função: Remove o áudio. A remoção apaga o registro e o arquivo.

Corpo de resposta: 204 No Content.

Como o arquivo é apagado, um áudio em uso não pode ser removido — as próximas ligações tocariam um arquivo inexistente. Retorna 409 AUDIO_IN_USE quando:

  • o áudio é usado por um broadcast de voz que ainda não encerrou (qualquer status que não seja completed ou cancelled) — os IDs vêm em details.broadcast_ids;

  • o áudio é usado por uma sequência de voz de uma campanha, ativa ou não — os IDs vêm em details.sequence_ids. Uma automação não "termina" sozinha: troque o áudio da sequência (PUT /sms/sequences/{id}) ou remova a sequência antes.

Broadcast já completed ou cancelled não impede a remoção — o histórico e os relatórios dele seguem intactos.

POST /calls/audios/preview-tts

Função: Gera a locução e devolve o binário MP3 (Content-Type: audio/mpeg), sem gravar nada. Existe para quem monta a própria tela de criação de áudio e precisa deixar o usuário ouvir antes de confirmar.

Corpo de envio:

Corpo de resposta — 200 OK: o arquivo MP3 em binário. É o único endpoint da API de Parceiros que não responde JSON.

Cada chamada é paga. Mesmo sem criar nenhum áudio, cada pré-escuta é uma chamada ao provedor de locução e exige saldo de créditos de ligação. Não utilize em laço de teste.

Ações de teclado (DTMF)

Uma ação define o que acontece quando o contato digita uma tecla durante a ligação. Elas são configuradas no áudio, em actions, e valem para todos os disparos que o utilizam.

| action_type | action_params | O que faz | | ----------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------- | | mark_interested | — | Marca o contato como interessado | | mark_not_interested | — | Marca o contato como não interessado | | add_tag | tag_id | Adiciona a tag ao contato | | remove_tag | tag_id | Remove a tag do contato | | move_to_list | list_id | Move o lead para outra lista sua | | add_to_list | list_id | Copia o lead para outra lista sua (mantém na atual) | | trigger_sequence | sequence_id | Inscreve o lead em uma sequência sua | | webhook | url | Envia um POST ao seu endereço com {lead_id, name, phone, dtmf_key, sequence_id, broadcast_call_id, action_type} |

Exemplo com parâmetros:

  • dtmf_key é uma tecla do teclado telefônico: 0 a 9, * ou #.

  • Uma ação por tecla. Repetir a mesma tecla no array retorna 422: a plataforma executaria apenas uma delas, e não haveria como dizer qual.

  • São aceitas no máximo 12 ações por áudio.

  • list_id e sequence_id precisam pertencer à sua conta. Um ID desconhecido e um ID de outro parceiro retornam o mesmo 422, com a mesma mensagem — de propósito, para não revelar o que existe na conta alheia.

  • A url de webhook não pode apontar para endereços privados ou internos (422).

Código de Erros Comuns

  • 401 Unauthorized (UNAUTHORIZED): Não foi possível identificar o parceiro a partir da Chave de API.

  • 402 Payment Required (INSUFFICIENT_CREDITS): Créditos de ligação insuficientes. Ocorre apenas em type: "tts" e em preview-tts — o upload de arquivo não consome crédito. O saldo atual vem em details.available_credits.

  • 404 Not Found (NOT_FOUND): O áudio não foi encontrado ou não pertence à sua conta.

  • 409 Conflict (AUDIO_IN_USE): O áudio está em uso e não pode ser removido. Os IDs vêm em details.broadcast_ids e details.sequence_ids.

  • 422 Unprocessable Entity (VALIDATION_ERROR): Algum campo do corpo da requisição é inválido — inclui arquivo que não é um áudio válido, áudio acima de 30 segundos, tecla DTMF repetida, ação sem o parâmetro obrigatório e list_id/sequence_id que não pertence à sua conta. à sua conta.

  • 429 Too Many Requests (RATE_LIMIT_EXCEEDED): Limite de 60 requisições por minuto excedido. Consulte o header Retry-After.

  • 502 Bad Gateway (AUDIO_PROVIDER_ERROR): O provedor de locução falhou. Nada foi gravado; repetir a chamada mais tarde costuma resolver.

  • 502 Bad Gateway (AUDIO_UPLOAD_FAILED): Falha ao armazenar o arquivo enviado. Nada foi gravado.

Corpo de resposta de erro:

Dúvidas?

Em caso de dúvidas, entre em contato com nosso suporte.

PreviousBroadcasts
NextLigações - Broadcasts

Last updated