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

📤Ligações - Broadcasts

Um Broadcast de Voz disca para todos os leads de uma lista, toca um áudio gravado e reporta o desfecho de cada ligação — atendeu, escutou até o fim, digitou uma tecla, não atendeu.

É o equivalente exato dos Broadcasts de SMS — mesmo nome e mesmo formato — e o mesmo recurso da tela Broadcasts de Voz do painel: o disparo criado pela API aparece lá, e vice-versa.

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 completo

1. POST /calls/audios                    → cria o áudio      (audio_id)
2. POST /lists                           → cria a lista      (list_id)
3. POST /lists/{id}/leads                → insere os telefones
4. POST /calls/broadcasts                → cria e dispara    (broadcast_id)
5. GET  /calls/broadcasts/{id}/contacts  → desfecho de cada ligação

Os telefones sempre vêm de uma Lista — não há inserção de números no corpo do disparo. O caminho da lista já normaliza o telefone, aplica a blacklist e é idempotente por Idempotency-Key, e a mesma lista pode alimentar uma campanha de SMS e um disparo de voz.

Status possíveis

Status do broadcast: pending (criado, importando os contatos), processing (discando), paused (pausado), completed (encerrado), cancelled (cancelado).

Desfecho de cada ligação: waiting, no_answer, answered_hangup, answered_listened, answered_dtmf, cancelled e error — a tabela completa está mais abaixo.

Janela de silêncio: 23:00–07:30 (America/Sao_Paulo). Nada é discado nesse intervalo. Um scheduled_date que caia dentro dele é reagendado para 07:30, e não recusado — o valor devolvido na resposta é o horário efetivo.

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 por ligação é o credits_per_call do áudio.

Saldo parcial não impede a criação. Apenas o saldo zerado retorna 402 INSUFFICIENT_CREDITS. Ter menos crédito que o estimated_credits é aceito de propósito: quando o crédito acaba no meio do disparo, o contato volta para a fila em vez de se perder, e é discado novamente após a recarga.

Endpoints

POST /calls/broadcasts

Função: Cria o disparo e inicia a importação dos telefones da lista.

Corpo de envio:

Corpo de resposta — 201 Created:

estimated_credits, credits_per_call e leads_count aparecem apenas nesta resposta de criação — eles são conhecidos no momento do disparo. O custo real acumulado vive em total_credits_used, disponível em todas as consultas.

As validações são checadas antes de qualquer coisa ser gravada, nesta ordem:

  1. Lista inexistente ou de outra conta → 404 NOT_FOUND

  2. Áudio inexistente ou de outra conta → 404 NOT_FOUND

  3. Áudio ainda em processamento → 422 AUDIO_NOT_READY (com details.audio_status)

  4. Lista sem nenhum lead → 422 EMPTY_LEAD_LIST

  5. Saldo de ligação zerado → 402 INSUFFICIENT_CREDITS

GET /calls/broadcasts

Função: Lista os seus broadcasts de voz, do mais recente para o mais antigo.

Parâmetros de query (opcionais):

Corpo de resposta — 200 OK:

Um valor desconhecido em ?status= é ignorado (a listagem vem completa), em vez de retornar erro ou uma lista vazia sem explicação.

GET /calls/broadcasts/{id}

Função: Detalhe do broadcast, acrescido do bloco report — o mesmo recorte da tela de acompanhamento do painel.

Corpo de resposta — 200 OK:

O report não conta os contatos cancelados nem os que ainda estão na fila — por isso, num broadcast em andamento, a soma dos desfechos é menor que total_contacts.

PUT /calls/broadcasts/{id}

Função: Atualização parcial do broadcast. Envie apenas os campos que deseja alterar.

Corpo de envio:

Corpo de resposta — 200 OK: o broadcast atualizado, no mesmo formato da listagem (sem o bloco report).

lead_list_id é proibido neste endpoint (422). A lista já foi copiada para os contatos durante a importação, e trocá-la deixaria o broadcast apontando para uma lista que não corresponde ao que foi discado. Para outra lista, crie outro broadcast.

A rediscagem só vale para importações futuras. max_attempts e retry_interval_minutes são copiados para cada contato no momento da importação. Alterá-los depois que a importação terminou não reescreve os contatos já criados. É o mesmo comportamento do painel.

Broadcast já encerrado (completed ou cancelled) não pode ser editado → 409 INVALID_STATUS_TRANSITION, com o status atual em details.current_status.

PUT /calls/broadcasts/{id}/cancel

Função: Cancela o broadcast. Permitido nos status pending, processing e paused — nos demais, 409 INVALID_STATUS_TRANSITION.

Corpo de resposta:

  • 200 OK — broadcast pending ou paused: cancelamento completo ("cancellation": "complete"), nada estava no ar.

  • 202 Accepted — broadcast processing: cancelamento parcial ("cancellation": "partial"); ligações já publicadas no discador ainda podem completar.

Os contatos ainda não discados recebem o desfecho cancelled; quem já foi discado mantém o desfecho original.

PUT /calls/broadcasts/{id}/pause

PUT /calls/broadcasts/{id}/resume

Função: Interrompe e retoma a discagem.

  • pause aceita pending e processing → passa para paused.

  • resume aceita apenas paused → volta para processing. Fora dessas transições, 409 INVALID_STATUS_TRANSITION com o status atual em details.current_status.

Corpo de resposta — 200 OK: o broadcast atualizado, no mesmo formato da listagem.

Pausar não descarta contatos: o que faltava discar continua na fila e volta a ser processado no resume.

GET /calls/broadcasts/{id}/contacts

Função: Lista os contatos do broadcast com o desfecho individual de cada ligação.

Parâmetros de query (opcionais):

Corpo de resposta — 200 OK:

Cada tentativa de rediscagem é uma linha própria, preservando o histórico. Um contato com max_attempts: 3 que não atendeu duas vezes aparece em até três linhas, com tries 1, 2 e 3.

Desfecho de cada ligação (status)

status

Significado

waiting

Ainda não discado, ou aguardando a próxima tentativa

no_answer

Não atendeu, ocupado, congestionado ou número indisponível

answered_hangup

Atendeu e desligou antes do fim do áudio (ouviu menos de 95%)

answered_listened

Atendeu e escutou 95% ou mais do áudio

answered_dtmf

Atendeu e digitou uma tecla — a tecla está em dtmf_response

cancelled

O broadcast foi cancelado antes deste contato ser discado

error

Falhou antes de chegar ao discador (telefone fora do formato brasileiro, p. ex.)

Use status para programar em cima do retorno. O status_label é o texto em português que o painel exibe e pode mudar.

answered_at é o momento em que o desfecho voltou do discador — não é o horário exato do atendimento.

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): Saldo de créditos de ligação zerado. Vêm em details o estimated_credits e o available_credits.

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

  • 409 Conflict (INVALID_STATUS_TRANSITION): O broadcast não aceita a operação no status atual (editar encerrado, cancelar encerrado, pausar pausado, retomar o que não está pausado). O status atual vem em details.current_status.

  • 422 Unprocessable Entity (AUDIO_NOT_READY): O áudio ainda não terminou de ser processado. O status dele vem em details.audio_status; aguarde ready: true em GET /calls/audios/{id}.

  • 422 Unprocessable Entity (EMPTY_LEAD_LIST): A lista informada não tem nenhum lead. Insira leads antes de criar o disparo.

  • 422 Unprocessable Entity (EMPTY_LEAD_LIST): A lista informada não tem nenhum lead. Insira leads antes de criar o disparo.

  • 422 Unprocessable Entity (VALIDATION_ERROR): Algum campo do corpo é inválido — inclui lead_list_id no PUT, scheduled_date no passado, scheduled_end_date anterior ao início efetivo e postback_url apontando para endereço privado ou interno.

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

Corpo de resposta de erro:

Dúvidas?

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

PreviousLigações - Áudios
NextAgências

Last updated