# Bemmelhor Telecom — API

> Plataforma de telefonia (PSTN, WhatsApp oficial e não oficial) com API REST para consultar ligações, gravações, transcrições e resumos, disparar click-to-call, transferir chamadas, ver e pausar ramais, administrar Telefonia & URA (ramais, filas, áudios, URAs e DIDs), receber eventos por webhook assinado e incorporar o softphone Web (iframe ou SIP.js via proxy WSS).

- Documentação: https://www.bemmelhor.com.br/docs
- Base da API de integração: `https://service.bemmelhor.com.br/api/integrations/v1`
- Base da Partner API: `https://service.bemmelhor.com.br/api/partner/v1`
- Formato: JSON sobre HTTPS, UTF-8. Datas em ISO 8601.

Versão completa num arquivo só, com parâmetros, exemplos e respostas de todos os endpoints: https://www.bemmelhor.com.br/llms-full.txt

## Começar

- [Introdução](https://www.bemmelhor.com.br/docs#introducao): o que a API faz, base URL e formato.
- [Autenticação](https://www.bemmelhor.com.br/docs#autenticacao): chave de API (Bearer ou x-api-key), escopos e token de partner.

## API de integração

- [GET /calls](https://www.bemmelhor.com.br/docs#api-get-calls): Listar ligações. Retorna lista paginada de ligações da organização. (escopo calls:list)
- [GET /calls/:callId](https://www.bemmelhor.com.br/docs#api-get-calls-callId): Ver ligação. Retorna os detalhes de uma ligação pelo ID. (escopo calls:get)
- [GET /recordings/:linkedId](https://www.bemmelhor.com.br/docs#api-get-recordings-linkedId): Ver gravação. Retorna o stream de áudio da gravação. Use o linkedId da ligação (campo LinkedID do CDR/webhook). Se não encontrar, tente uniqueId e, por último, o callId. (escopo recording:get)
- [GET /calls/:callId/transcription](https://www.bemmelhor.com.br/docs#api-get-calls-callId-transcription): Ver transcrição. Retorna a transcrição da ligação. Prefira o linkedId no path; se não encontrar, use uniqueId ou callId. Se não existir e a integração estiver habilitada, gera e retorna. (escopo transcription:get)
- [GET /calls/:callId/summary](https://www.bemmelhor.com.br/docs#api-get-calls-callId-summary): Ver resumo. Retorna o resumo da ligação. Prefira o linkedId no path; se não encontrar, use uniqueId ou callId. Se não existir e a integração estiver habilitada, gera transcrição e resumo. (escopo summary:get)
- [GET /calls/:callId/hangup-by](https://www.bemmelhor.com.br/docs#api-get-calls-callId-hangup-by): Ver quem encerrou. Diz quem desligou a ligação, direto do registro da central: client quando foi o telefone físico e agent quando foi o ramal. Funciona com chave SK- (scope calls:get) ou token partner PT-. Use o linkedId, que é o campo Linkedid do webhook. Responde 404 quando a ligação não tem registro de encerramento. O mesmo valor chega sozinho no webhook de Hangup, no campo hangup_by_role. (escopo calls:get)
- [POST /click-to-call](https://www.bemmelhor.com.br/docs#api-post-click-to-call): Click to call. Inicia uma ligação entre o ramal e o número informado. (escopo click_to_call)
- [POST /calls/supervised-transfer](https://www.bemmelhor.com.br/docs#api-post-calls-supervised-transfer): Transferência assistida. Com o ramal em ligação, inicia transferência assistida. Responde 202 imediatamente (destino tocando); o agente permanece com o cliente até conclusão, cancelamento, falha ou timeout. Emite TransferStarted e os eventos finais via webhook e /ws/telephony-events. Consulte o status em GET /calls/supervised-transfer/:transferId. (escopo calls:transfer)
- [POST /calls/supervised-transfer/cancel](https://www.bemmelhor.com.br/docs#api-post-calls-supervised-transfer-cancel): Cancelar transferência assistida. Solicita o cancelamento da consulta ao destino. A ligação permanece com o agente. Se a transferência ainda estiver ringing, retorna 200 e emite TransferCancelled em seguida. Se já tiver finalizado, também retorna 200 informando o status final. (escopo calls:transfer)
- [GET /calls/supervised-transfer/:transferId](https://www.bemmelhor.com.br/docs#api-get-calls-supervised-transfer-transferId): Status da transferência assistida. Consulta o andamento da transferência. status possível: ringing, completed, failed, cancelled ou timeout. Em failed/timeout o campo error pode vir preenchido; em completed, transferMethod indica o método AMI usado. (escopo calls:transfer)
- [GET /extensions](https://www.bemmelhor.com.br/docs#api-get-extensions): Ramais e Status. Lista ramais com status de registro (online/offline) e de chamada em tempo real (idle, ringing, in_call, dialing). Funciona com chave SK- (scope) ou token partner PT-. Não exige Telefonia & WhatsApp, apenas Asterisk configurado na organização. (escopo extensions:status)
- [POST /queue/pause](https://www.bemmelhor.com.br/docs#api-post-queue-pause): Pausar ramal na fila. Pausa um ramal em uma fila específica, igual à página de monitoramento. O motivo (reason) é obrigatório e fica no histórico de pausas. Não exige Telefonia & WhatsApp — apenas Asterisk configurado. O ramal precisa ser membro da fila. (escopo queues:pause)
- [POST /queue/unpause](https://www.bemmelhor.com.br/docs#api-post-queue-unpause): Despausar ramal na fila. Retira a pausa do ramal na fila informada. Não envia motivo. Fecha o registro de pausa ativo (inclusive pausas feitas pelo painel ou por outro token). (escopo queues:pause)
- [POST /extension/pause](https://www.bemmelhor.com.br/docs#api-post-extension-pause): Ativar DND do ramal. Coloca o ramal inteiro em DND (ocupado para todas as filas e ligações diretas), via Bridge. Use no softphone interno e em integrações. O motivo é obrigatório e fica no histórico. Exige Telefonia & WhatsApp / Bridge — diferente de /queue/pause, que é só por fila no Asterisk. (escopo queues:pause)
- [POST /extension/unpause](https://www.bemmelhor.com.br/docs#api-post-extension-unpause): Remover DND do ramal. Remove o DND do ramal. Não envia motivo. Fecha o registro ativo (inclusive DND feito pelo painel ou por outro token). (escopo queues:pause)
- [GET /extension/pause](https://www.bemmelhor.com.br/docs#api-get-extension-pause): Consultar DND do ramal. Retorna se o ramal está em DND, duração atual, motivo e o log local ativo (se houver). Use no softphone para pintar o botão de pausa. (escopo queues:pause)

## Telefonia & URA

- [Visão geral](https://www.bemmelhor.com.br/docs#telephony-overview): CRUD via Bridge, pré-requisitos e escopos.
- [GET /telephony-bridge/status](https://www.bemmelhor.com.br/docs#telephony-status): Status do tenant. Retorna visão geral do tenant Bridge (ramais, filas, áudios, URAs e DIDs). (escopo telephony_bridge:status:read)
- [GET /telephony-bridge/extensions](https://www.bemmelhor.com.br/docs#telephony-extensions): Listar ramais. Lista ramais configurados no tenant. (escopo telephony_bridge:extensions:read)
- [GET /telephony-bridge/extensions/:ext](https://www.bemmelhor.com.br/docs#telephony-extensions): Obter ramal. Retorna detalhes de um ramal. (escopo telephony_bridge:extensions:read)
- [POST /telephony-bridge/extensions](https://www.bemmelhor.com.br/docs#telephony-extensions): Criar ramal. Cria um novo ramal no tenant. (escopo telephony_bridge:extensions:write)
- [PATCH /telephony-bridge/extensions/:ext](https://www.bemmelhor.com.br/docs#telephony-extensions): Atualizar ramal. Atualiza campos de um ramal existente. (escopo telephony_bridge:extensions:write)
- [DELETE /telephony-bridge/extensions/:ext](https://www.bemmelhor.com.br/docs#telephony-extensions): Excluir ramal. Remove um ramal do tenant. (escopo telephony_bridge:extensions:write)
- [GET /telephony-bridge/extensions/:ext/pause](https://www.bemmelhor.com.br/docs#telephony-extensions): Consultar DND do ramal. Retorna se o ramal está em DND (ocupado globalmente). Mesmo histórico do GET /extension/pause. (escopo telephony_bridge:extensions:read)
- [POST /telephony-bridge/extensions/:ext/pause](https://www.bemmelhor.com.br/docs#telephony-extensions): Ativar DND do ramal. Ativa DND do ramal inteiro via Bridge. Motivo obrigatório. O softphone interno do dashboard deve preferir POST /organizations/:id/extension/pause (sessão JWT). (escopo telephony_bridge:extensions:write)
- [DELETE /telephony-bridge/extensions/:ext/pause](https://www.bemmelhor.com.br/docs#telephony-extensions): Remover DND do ramal. Remove o DND do ramal. Equivale a POST /extension/unpause. (escopo telephony_bridge:extensions:write)
- [GET /telephony-bridge/queues](https://www.bemmelhor.com.br/docs#telephony-queues): Listar filas. Lista filas de atendimento. (escopo telephony_bridge:queues:read)
- [GET /telephony-bridge/queues/:name](https://www.bemmelhor.com.br/docs#telephony-queues): Obter fila. Retorna detalhes de uma fila. (escopo telephony_bridge:queues:read)
- [POST /telephony-bridge/queues](https://www.bemmelhor.com.br/docs#telephony-queues): Criar fila. Cria uma nova fila. `timeout` é quanto cada agente toca por ciclo e `max_wait` é o teto de espera do cliente na fila (0 = sem limite). Os dois são inteiros de 0 a 86400 segundos. (escopo telephony_bridge:queues:write)
- [PATCH /telephony-bridge/queues/:name](https://www.bemmelhor.com.br/docs#telephony-queues): Atualizar fila. Atualiza a configuração de uma fila; só o que for enviado muda. Tempos: `timeout` (segundos que cada agente toca por ciclo) e `max_wait` (teto de espera do cliente na fila, 0 = sem limite), inteiros de 0 a 86400. A central grava, regenera a configuração das filas e recarrega sozinha. (escopo telephony_bridge:queues:write)
- [DELETE /telephony-bridge/queues/:name](https://www.bemmelhor.com.br/docs#telephony-queues): Excluir fila. Remove uma fila. (escopo telephony_bridge:queues:write)
- [POST /telephony-bridge/queues/:name/members](https://www.bemmelhor.com.br/docs#telephony-queues): Membros da fila. Adiciona ou remove ramais de uma fila. (escopo telephony_bridge:queues:write)
- [GET /telephony-bridge/audios](https://www.bemmelhor.com.br/docs#telephony-audios): Listar áudios. Lista áudios (TTS e upload) do tenant. (escopo telephony_bridge:audios:read)
- [GET /telephony-bridge/audios/voices](https://www.bemmelhor.com.br/docs#telephony-audios): Vozes TTS. Lista vozes disponíveis para síntese de áudio. (escopo telephony_bridge:audios:read)
- [GET /telephony-bridge/audios/:audioId](https://www.bemmelhor.com.br/docs#telephony-audios): Obter áudio. Retorna metadados de um áudio. (escopo telephony_bridge:audios:read)
- [GET /telephony-bridge/audios/:audioId/raw](https://www.bemmelhor.com.br/docs#telephony-audios): Download do áudio. Retorna o arquivo de áudio (mp3 ou slin). (escopo telephony_bridge:audios:read)
- [POST /telephony-bridge/audios](https://www.bemmelhor.com.br/docs#telephony-audios): Criar áudio. Cria áudio por TTS (JSON) ou upload (multipart/form-data com file, audio_id e description). MP3/WAV, máx. 10 MB. (escopo telephony_bridge:audios:write)
- [PATCH /telephony-bridge/audios/:audioId](https://www.bemmelhor.com.br/docs#telephony-audios): Atualizar metadados do áudio. Atualiza descrição ou metadados sem substituir o conteúdo. (escopo telephony_bridge:audios:write)
- [PUT /telephony-bridge/audios/:audioId](https://www.bemmelhor.com.br/docs#telephony-audios): Substituir áudio. Substitui conteúdo por novo TTS (JSON) ou upload (multipart/form-data). (escopo telephony_bridge:audios:write)
- [DELETE /telephony-bridge/audios/:audioId](https://www.bemmelhor.com.br/docs#telephony-audios): Excluir áudio. Remove um áudio do tenant. (escopo telephony_bridge:audios:write)
- [GET /telephony-bridge/ivrs](https://www.bemmelhor.com.br/docs#telephony-ivrs): Listar URAs. Lista URAs configuradas. (escopo telephony_bridge:ivrs:read)
- [GET /telephony-bridge/ivrs/:ivrId](https://www.bemmelhor.com.br/docs#telephony-ivrs): Obter URA. Retorna configuração completa de uma URA. (escopo telephony_bridge:ivrs:read)
- [GET /telephony-bridge/ivrs/:ivrId/dids](https://www.bemmelhor.com.br/docs#telephony-ivrs): DIDs da URA. Lista números (DIDs) vinculados à URA. (escopo telephony_bridge:ivrs:read)
- [POST /telephony-bridge/ivrs](https://www.bemmelhor.com.br/docs#telephony-ivrs): Criar URA. Cria uma nova URA de atendimento. (escopo telephony_bridge:ivrs:write)
- [PATCH /telephony-bridge/ivrs/:ivrId](https://www.bemmelhor.com.br/docs#telephony-ivrs): Atualizar URA. Atualiza campos de uma URA existente. (escopo telephony_bridge:ivrs:write)
- [DELETE /telephony-bridge/ivrs/:ivrId](https://www.bemmelhor.com.br/docs#telephony-ivrs): Excluir URA. Remove uma URA. (escopo telephony_bridge:ivrs:write)
- [GET /telephony-bridge/dids](https://www.bemmelhor.com.br/docs#telephony-dids): Listar DIDs. Lista números de entrada (DIDs). (escopo telephony_bridge:dids:read)
- [GET /telephony-bridge/dids/:number](https://www.bemmelhor.com.br/docs#telephony-dids): Obter DID. Retorna detalhes de um número. (escopo telephony_bridge:dids:read)
- [POST /telephony-bridge/dids](https://www.bemmelhor.com.br/docs#telephony-dids): Criar DID. Associa um número a uma URA. (escopo telephony_bridge:dids:write)
- [PATCH /telephony-bridge/dids/:number](https://www.bemmelhor.com.br/docs#telephony-dids): Atualizar DID. Altera a URA vinculada ao número. (escopo telephony_bridge:dids:write)
- [DELETE /telephony-bridge/dids/:number](https://www.bemmelhor.com.br/docs#telephony-dids): Excluir DID. Remove um número do tenant. (escopo telephony_bridge:dids:write)

## Webhooks

- [Entrega e segurança](https://www.bemmelhor.com.br/docs#webhooks-overview): cabeçalhos e assinatura HMAC-SHA256.
- [Verificar assinatura](https://www.bemmelhor.com.br/docs#webhooks-verify): exemplos de verificação em várias linguagens.
- [Início de Discagem (Dial)](https://www.bemmelhor.com.br/docs#webhook-event-1): Representa o momento em que uma tentativa de chamada é iniciada. Aparece em ligações entrantes e sainte. Use para registrar tentativa de chamada, identificar quem liga e o destino.
- [Mudança de Estado (Newstate)](https://www.bemmelhor.com.br/docs#webhook-event-2): Indica alterações no estado de um canal durante a chamada. ChannelStateDesc: Ringing = ramal tocando, Ring = telefone tocando, Up = chamada atendida. Aparece em entrantes e sainte.
- [Chamada Conectada (Bridge Link)](https://www.bemmelhor.com.br/docs#webhook-event-3): Indica que duas partes da chamada foram conectadas e a conversa começou. Use para iniciar contagem de tempo de conversa e considerar a chamada efetivamente conectada.
- [Chamada Desconectada (Bridge Unlink)](https://www.bemmelhor.com.br/docs#webhook-event-4): Indica que a conexão entre os canais foi interrompida. A ligação deixa de estar conectada. Use para calcular duração da conversa (BridgeLink → BridgeUnlink).
- [Fim de Chamada (Hangup)](https://www.bemmelhor.com.br/docs#webhook-event-5): Indica o encerramento definitivo de um canal da chamada. Pode haver dois eventos Hangup para uma única chamada (um por canal). Cause indica o motivo do desligamento.
- [Solicitação de permissão WhatsApp (WhatsAppCallPermissionRequested)](https://www.bemmelhor.com.br/docs#webhook-event-7): Enviado quando o cliente recebe no WhatsApp o pedido para autorizar ligações oficiais. Usa a mesma assinatura HMAC dos demais webhooks. Serve para mapear organização, DID de origem e número de destino.
- [Ligação WhatsApp originada (WhatsAppCallOriginated)](https://www.bemmelhor.com.br/docs#webhook-event-8): Enviado quando a Bridge aceita originar a ligação WhatsApp. Este é o evento confiável para obter o telefone de destino (to_msisdn), porque o Dial AMI da Bridge só mostra o ramal do agente.
- [Transferência iniciada (TransferStarted)](https://www.bemmelhor.com.br/docs#webhook-event-9): Emitido quando uma transferência assistida é iniciada via API/softphone. O ramal destino começa a tocar; o agente permanece na ligação com o cliente até conclusão, cancelamento, falha ou timeout.
- [Transferência concluída / falhou / cancelada / timeout](https://www.bemmelhor.com.br/docs#webhook-event-10): Eventos finais: TransferCompleted (destino atendeu e cliente foi bridged), TransferFailed (recusa/erro), TransferCancelled (agente cancelou) e TransferTimeout (destino não atendeu a tempo). Mesmo shape de TransferStarted, com status/error/transferMethod preenchidos quando aplicável.
- [Ramal Conectado (ExtensionOnline)](https://www.bemmelhor.com.br/docs#webhook-event-11): Disparado quando um ramal registra no Asterisk (REGISTER). Cobre softphone WebRTC, iframe, MicroSIP, PortSIP e demais clientes SIP. Origem AMI: PeerStatus (Registered) ou ContactStatus (Created).
- [Ramal Desconectado (ExtensionOffline)](https://www.bemmelhor.com.br/docs#webhook-event-12): Disparado quando um ramal desregistra no Asterisk (UNREGISTER / contato removido). Logout do softphone, fechamento do cliente ou expiração do registro. Origem AMI: PeerStatus (Unregistered) ou ContactStatus (Removed).
- [Chamada entrante sem ramais online (IncomingCallAllExtensionsOffline)](https://www.bemmelhor.com.br/docs#webhook-event-13): Disparado quando uma ligação entra no PABX e nenhum ramal visível da organização está registrado (online) no Asterisk. Se qualquer ramal estiver online, mesmo ocupado, o evento não é enviado. Online significa registro SIP no PABX, não presença de chat.

## Softphone Web (iframe)

- [Visão geral](https://www.bemmelhor.com.br/docs#softphone-overview): link único por organização, origens permitidas e credenciais.
- [APIs de gestão](https://www.bemmelhor.com.br/docs#softphone-admin): rotas de administração do iframe.
- [Fluxo no iframe](https://www.bemmelhor.com.br/docs#softphone-public): rotas que o iframe chama.
- [Incorporar no CRM](https://www.bemmelhor.com.br/docs#softphone-embed): HTML de incorporação.
- [Pré-discagem](https://www.bemmelhor.com.br/docs#softphone-predial): abrir o iframe já com o número.
- [Modo sessão](https://www.bemmelhor.com.br/docs#softphone-session): softphone com o login do painel.
- [Pausa DND do ramal](https://www.bemmelhor.com.br/docs#softphone-dnd): ocupar o ramal em todas as filas e ligações diretas.
- [Chamadas perdidas](https://www.bemmelhor.com.br/docs#softphone-missed-calls): lista, marcar como vista e evento em tempo real.

## Partner

- [Visão geral](https://www.bemmelhor.com.br/docs#partner-overview): softphone na sua plataforma com token PT.
- [Autenticação](https://www.bemmelhor.com.br/docs#partner-auth): token PT na Partner API e na API de integração.
- [API de integração](https://www.bemmelhor.com.br/docs#partner-integration-api): ligações, gravações e status com token PT.
- [CRUD Telefonia & URA](https://www.bemmelhor.com.br/docs#partner-telephony-bridge): ramais, filas, áudios, URAs e DIDs pelo partner.
- [Canais de discagem](https://www.bemmelhor.com.br/docs#partner-channels): PSTN pelo WSS, WhatsApp pela Bridge, consulta de permissão.
- [Sessão softphone](https://www.bemmelhor.com.br/docs#partner-session): JWT de sessão para qualquer ramal da organização.
- [Proxy SIP (WSS)](https://www.bemmelhor.com.br/docs#partner-wss): REGISTER, INVITE, keepalive e renovação.
- [Endpoints](https://www.bemmelhor.com.br/docs#partner-apis): todas as rotas da Partner API.