Bemmelhor Telecom · Developers

API Docs

Referência completa para integrar ligações, gravações, Telefonia & URA, webhooks em tempo real e o softphone WebRTC no seu CRM ou portal.

Começar pela autenticação Gerar chave no painel

Ir para seção

Começar

Introdução

A API de integrações da Bemmelhor permite consultar ligações, obter gravações e transcrições, disparar click-to-call, gerenciar Telefonia & URA, receber eventos via webhook e incorporar o softphone Web.

Base URL: https://service.bemmelhor.com.br/api/integrations/v1
Formato: JSON · HTTPS · UTF-8
Autenticação: API Key (Bearer ou x-api-key)
Escopos: Cada endpoint exige o escopo correspondente na chave

Começar

Autenticação

Crie uma chave de API no painel (Organização → Segurança e API). A chave é exibida apenas uma vez. Envie-a em todas as requisições à API de integrações.

Headers aceitos

Authorization: Bearer <sua_chave>
x-api-key: <sua_chave>

Escopos da API de integração

calls:list
Listar ligações
calls:get
Ver ligação
recording:get
Ver gravação
transcription:get
Ver transcrição
summary:get
Ver resumo
click_to_call
Click to call

Escopos Telefonia & URA

Exigem organização com Telefonia & WhatsApp habilitada e setup Bridge concluído.

telephony_bridge:status:read
Telefonia, status
telephony_bridge:extensions:read
Ramais, leitura
telephony_bridge:extensions:write
Ramais, escrita
telephony_bridge:queues:read
Filas, leitura
telephony_bridge:queues:write
Filas, escrita
telephony_bridge:audios:read
Áudios, leitura
telephony_bridge:audios:write
Áudios, escrita
telephony_bridge:ivrs:read
URAs, leitura
telephony_bridge:ivrs:write
URAs, escrita
telephony_bridge:dids:read
DIDs, leitura
telephony_bridge:dids:write
DIDs, escrita

curl "https://service.bemmelhor.com.br/api/integrations/v1/calls?page=1&limit=20" \
  -H "x-api-key: SUA_CHAVE_DE_API"

API de integração

Endpoints

Base URL: https://service.bemmelhor.com.br/api/integrations/v1

GET/callscalls:list

Listar ligações

Retorna lista paginada de ligações da organização.

Parâmetros

Nome	Local	Tipo	Descrição
`page`	query	number	Página (default: 1)
`limit`	query	number	Itens por página (default: 50, máx: 100)
`type`	query	string	ENTRANTE ou SAINTE
`startDate`	query	string	Data inicial (ISO)
`endDate`	query	string	Data final (ISO)
`origin`	query	string	Ramal de origem
`destiny`	query	string	Ramal de destino
`sector`	query	string	Setor
`disposition`	query	string	ANSWER, NO ANSWER, BUSY, FAILED
`queue`	query	string	Nome da fila

Exemplo de requisição

# Listar ligações
# Parâmetros de path/query já preenchidos com exemplos.
curl -X GET "https://service.bemmelhor.com.br/api/integrations/v1/calls?page=1&limit=50" \
  -H "x-api-key: SUA_CHAVE_DE_API"

GET/calls/:callIdcalls:get

Ver ligação

Retorna os detalhes de uma ligação pelo ID.

Parâmetros

Nome	Local	Tipo	Descrição
`callId`obrigatório	path	string	ID da ligação (ou external-{id})

Exemplo de requisição

# Ver ligação
# Parâmetros de path/query já preenchidos com exemplos.
curl -X GET "https://service.bemmelhor.com.br/api/integrations/v1/calls/abc123-external-456" \
  -H "x-api-key: SUA_CHAVE_DE_API"

GET/recordings/:uniqueidrecording:get

Ver gravação

Retorna o stream de áudio da gravação (uniqueid da ligação).

Parâmetros

Nome	Local	Tipo	Descrição
`uniqueid`obrigatório	path	string	Uniqueid da ligação

Exemplo de requisição

# Ver gravação
# Parâmetros de path/query já preenchidos com exemplos.
curl -X GET "https://service.bemmelhor.com.br/api/integrations/v1/recordings/1735123456.123" \
  -H "x-api-key: SUA_CHAVE_DE_API"

GET/calls/:callId/transcriptiontranscription:get

Ver transcrição

Retorna a transcrição da ligação. Aceita callId ou uniqueId no path (recomenda-se uniqueId). Se não existir e a integração estiver habilitada, gera e retorna.

Parâmetros

Nome	Local	Tipo	Descrição
`callId`obrigatório	path	string	ID da ligação (callId) ou uniqueId da ligação. Recomenda-se usar uniqueId.

Exemplo de requisição

# Ver transcrição
# Parâmetros de path/query já preenchidos com exemplos.
curl -X GET "https://service.bemmelhor.com.br/api/integrations/v1/calls/1735123456.123/transcription" \
  -H "x-api-key: SUA_CHAVE_DE_API"

GET/calls/:callId/summarysummary:get

Ver resumo

Retorna o resumo da ligação. Aceita callId ou uniqueId no path (recomenda-se uniqueId). Se não existir e a integração estiver habilitada, gera transcrição e resumo.

Parâmetros

Nome	Local	Tipo	Descrição
`callId`obrigatório	path	string	ID da ligação (callId) ou uniqueId da ligação. Recomenda-se usar uniqueId.

Exemplo de requisição

# Ver resumo
# Parâmetros de path/query já preenchidos com exemplos.
curl -X GET "https://service.bemmelhor.com.br/api/integrations/v1/calls/1735123456.123/summary" \
  -H "x-api-key: SUA_CHAVE_DE_API"

POST/click-to-callclick_to_call

Click to call

Inicia uma ligação entre o ramal e o número informado.

Parâmetros

Nome	Local	Tipo	Descrição
`extensionNumber`obrigatório	body	string	Número do ramal
`phoneNumber`obrigatório	body	string	Número de telefone de destino

Corpo de exemplo

{
  "extensionNumber": "100",
  "phoneNumber": "11999999999"
}

Exemplo de requisição

# Click to call
# Parâmetros de path/query já preenchidos com exemplos.
curl -X POST "https://service.bemmelhor.com.br/api/integrations/v1/click-to-call" \
  -H "x-api-key: SUA_CHAVE_DE_API"

Telefonia & URA

API Telefonia & URA

CRUD de ramais, filas, áudios, URAs e DIDs via API. Pré-requisito: organização com Telefonia & WhatsApp habilitada e setup Bridge concluído. Cada endpoint exige o escopo correspondente.

Status

GET/telephony-bridge/statustelephony_bridge:status:read

Status do tenant

Retorna visão geral do tenant Bridge (ramais, filas, áudios, URAs e DIDs).

Exemplo de requisição

# Status do tenant
# Parâmetros de path/query já preenchidos com exemplos.
curl -X GET "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/status" \
  -H "x-api-key: SUA_CHAVE_DE_API"

Ramais

GET/telephony-bridge/extensionstelephony_bridge:extensions:read

Listar ramais

Lista ramais configurados no tenant.

Parâmetros

Nome	Local	Tipo	Descrição
`status`	query	string	Filtrar por online ou offline

Query: marque e preencha para incluir no exemplo

status

Exemplo de requisição

# Listar ramais
# Parâmetros de path/query já preenchidos com exemplos.
curl -X GET "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/extensions" \
  -H "x-api-key: SUA_CHAVE_DE_API"

GET/telephony-bridge/extensions/:exttelephony_bridge:extensions:read

Obter ramal

Retorna detalhes de um ramal.

Parâmetros

Nome	Local	Tipo	Descrição
`ext`obrigatório	path	string	Número do ramal

Exemplo de requisição

# Obter ramal
# Parâmetros de path/query já preenchidos com exemplos.
curl -X GET "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/extensions/1001" \
  -H "x-api-key: SUA_CHAVE_DE_API"

POST/telephony-bridge/extensionstelephony_bridge:extensions:write

Criar ramal

Cria um novo ramal no tenant.

Parâmetros

Nome	Local	Tipo	Descrição
`extension`obrigatório	body	string	Número do ramal (3 a 8 dígitos)
`display_name`obrigatório	body	string	Nome de exibição
`transport`	body	string	wss ou udp
`default_queue`	body	string	Fila padrão (opcional)
`secret`	body	string	Senha SIP ou "auto"

Corpo de exemplo

{
  "extension": "1001",
  "display_name": "Atendimento",
  "transport": "wss",
  "secret": "auto"
}

Exemplo de requisição

# Criar ramal
# Parâmetros de path/query já preenchidos com exemplos.
curl -X POST "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/extensions" \
  -H "x-api-key: SUA_CHAVE_DE_API"

PATCH/telephony-bridge/extensions/:exttelephony_bridge:extensions:write

Atualizar ramal

Atualiza campos de um ramal existente.

Parâmetros

Nome	Local	Tipo	Descrição
`ext`obrigatório	path	string	Número do ramal
`display_name`	body	string	Nome de exibição

Corpo de exemplo

{
  "display_name": "Suporte N1"
}

Exemplo de requisição

# Atualizar ramal
# Parâmetros de path/query já preenchidos com exemplos.
curl -X PATCH "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/extensions/1001" \
  -H "x-api-key: SUA_CHAVE_DE_API"

DELETE/telephony-bridge/extensions/:exttelephony_bridge:extensions:write

Excluir ramal

Remove um ramal do tenant.

Parâmetros

Nome	Local	Tipo	Descrição
`ext`obrigatório	path	string	Número do ramal

Exemplo de requisição

# Excluir ramal
# Parâmetros de path/query já preenchidos com exemplos.
curl -X DELETE "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/extensions/1001" \
  -H "x-api-key: SUA_CHAVE_DE_API"

Filas

GET/telephony-bridge/queuestelephony_bridge:queues:read

Listar filas

Lista filas de atendimento.

Exemplo de requisição

# Listar filas
# Parâmetros de path/query já preenchidos com exemplos.
curl -X GET "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/queues" \
  -H "x-api-key: SUA_CHAVE_DE_API"

GET/telephony-bridge/queues/:nametelephony_bridge:queues:read

Obter fila

Retorna detalhes de uma fila.

Parâmetros

Nome	Local	Tipo	Descrição
`name`obrigatório	path	string	Nome da fila

Exemplo de requisição

# Obter fila
# Parâmetros de path/query já preenchidos com exemplos.
curl -X GET "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/queues/suporte" \
  -H "x-api-key: SUA_CHAVE_DE_API"

POST/telephony-bridge/queuestelephony_bridge:queues:write

Criar fila

Cria uma nova fila.

Corpo de exemplo

{
  "name": "suporte",
  "display_name": "Suporte",
  "strategy": "ringall"
}

Exemplo de requisição

# Criar fila
# Parâmetros de path/query já preenchidos com exemplos.
curl -X POST "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/queues" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{"name":"suporte","display_name":"Suporte","strategy":"ringall"}'

PATCH/telephony-bridge/queues/:nametelephony_bridge:queues:write

Atualizar fila

Atualiza configuração de uma fila.

Parâmetros

Nome	Local	Tipo	Descrição
`name`obrigatório	path	string	Nome da fila

Corpo de exemplo

{
  "display_name": "Suporte comercial"
}

Exemplo de requisição

# Atualizar fila
# Parâmetros de path/query já preenchidos com exemplos.
curl -X PATCH "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/queues/suporte" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"Suporte comercial"}'

DELETE/telephony-bridge/queues/:nametelephony_bridge:queues:write

Excluir fila

Remove uma fila.

Parâmetros

Nome	Local	Tipo	Descrição
`name`obrigatório	path	string	Nome da fila

Exemplo de requisição

# Excluir fila
# Parâmetros de path/query já preenchidos com exemplos.
curl -X DELETE "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/queues/suporte" \
  -H "x-api-key: SUA_CHAVE_DE_API"

POST/telephony-bridge/queues/:name/memberstelephony_bridge:queues:write

Membros da fila

Adiciona ou remove ramais de uma fila.

Parâmetros

Nome	Local	Tipo	Descrição
`name`obrigatório	path	string	Nome da fila
`add`	body	string[]	Ramais a adicionar
`remove`	body	string[]	Ramais a remover

Corpo de exemplo

{
  "add": [
    "1001"
  ],
  "remove": [
    "1002"
  ]
}

Exemplo de requisição

# Membros da fila
# Parâmetros de path/query já preenchidos com exemplos.
curl -X POST "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/queues/suporte/members" \
  -H "x-api-key: SUA_CHAVE_DE_API"

Áudios

GET/telephony-bridge/audiostelephony_bridge:audios:read

Listar áudios

Lista áudios (TTS e upload) do tenant.

Exemplo de requisição

# Listar áudios
# Parâmetros de path/query já preenchidos com exemplos.
curl -X GET "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/audios" \
  -H "x-api-key: SUA_CHAVE_DE_API"

GET/telephony-bridge/audios/voicestelephony_bridge:audios:read

Vozes TTS

Lista vozes disponíveis para síntese de áudio.

Exemplo de requisição

# Vozes TTS
# Parâmetros de path/query já preenchidos com exemplos.
curl -X GET "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/audios/voices" \
  -H "x-api-key: SUA_CHAVE_DE_API"

GET/telephony-bridge/audios/:audioIdtelephony_bridge:audios:read

Obter áudio

Retorna metadados de um áudio.

Parâmetros

Nome	Local	Tipo	Descrição
`audioId`obrigatório	path	string	Identificador do áudio

Exemplo de requisição

# Obter áudio
# Parâmetros de path/query já preenchidos com exemplos.
curl -X GET "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/audios/boas_vindas" \
  -H "x-api-key: SUA_CHAVE_DE_API"

GET/telephony-bridge/audios/:audioId/rawtelephony_bridge:audios:read

Download do áudio

Retorna o arquivo de áudio (mp3 ou slin).

Parâmetros

Nome	Local	Tipo	Descrição
`audioId`obrigatório	path	string	Identificador do áudio
`format`	query	string	mp3 (padrão) ou slin

Query: marque e preencha para incluir no exemplo

format

Exemplo de requisição

# Download do áudio
# Parâmetros de path/query já preenchidos com exemplos.
curl -X GET "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/audios/boas_vindas/raw" \
  -H "x-api-key: SUA_CHAVE_DE_API"

POST/telephony-bridge/audiostelephony_bridge:audios:write

Criar áudio

Cria áudio por TTS (JSON) ou upload (multipart/form-data com file, audio_id e description). MP3/WAV, máx. 10 MB.

Parâmetros

Nome	Local	Tipo	Descrição
`audio_id`obrigatório	body	string	Slug do áudio (upload ou TTS)
`source`	body	string	tts para síntese
`text`	body	string	Texto para TTS
`voice`	body	string	Voz TTS

Corpo de exemplo

{
  "audio_id": "boas_vindas",
  "source": "tts",
  "text": "Bem-vindo à nossa central.",
  "voice": "pt-br-female"
}

Exemplo de requisição

# Criar áudio
# Parâmetros de path/query já preenchidos com exemplos.
curl -X POST "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/audios" \
  -H "x-api-key: SUA_CHAVE_DE_API"

PATCH/telephony-bridge/audios/:audioIdtelephony_bridge:audios:write

Atualizar metadados do áudio

Atualiza descrição ou metadados sem substituir o conteúdo.

Parâmetros

Nome	Local	Tipo	Descrição
`audioId`obrigatório	path	string	Identificador do áudio
`description`	body	string	Nova descrição

Corpo de exemplo

{
  "description": "Saudação inicial"
}

Exemplo de requisição

# Atualizar metadados do áudio
# Parâmetros de path/query já preenchidos com exemplos.
curl -X PATCH "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/audios/boas_vindas" \
  -H "x-api-key: SUA_CHAVE_DE_API"

PUT/telephony-bridge/audios/:audioIdtelephony_bridge:audios:write

Substituir áudio

Substitui conteúdo por novo TTS (JSON) ou upload (multipart/form-data).

Parâmetros

Nome	Local	Tipo	Descrição
`audioId`obrigatório	path	string	Identificador do áudio

Corpo de exemplo

{
  "source": "tts",
  "text": "Texto atualizado.",
  "voice": "pt-br-female"
}

Exemplo de requisição

# Substituir áudio
# Parâmetros de path/query já preenchidos com exemplos.
curl -X PUT "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/audios/boas_vindas" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{"source":"tts","text":"Texto atualizado.","voice":"pt-br-female"}'

DELETE/telephony-bridge/audios/:audioIdtelephony_bridge:audios:write

Excluir áudio

Remove um áudio do tenant.

Parâmetros

Nome	Local	Tipo	Descrição
`audioId`obrigatório	path	string	Identificador do áudio

Exemplo de requisição

# Excluir áudio
# Parâmetros de path/query já preenchidos com exemplos.
curl -X DELETE "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/audios/boas_vindas" \
  -H "x-api-key: SUA_CHAVE_DE_API"

URAs

GET/telephony-bridge/ivrstelephony_bridge:ivrs:read

Listar URAs

Lista URAs configuradas.

Exemplo de requisição

# Listar URAs
# Parâmetros de path/query já preenchidos com exemplos.
curl -X GET "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/ivrs" \
  -H "x-api-key: SUA_CHAVE_DE_API"

GET/telephony-bridge/ivrs/:ivrIdtelephony_bridge:ivrs:read

Obter URA

Retorna configuração completa de uma URA.

Parâmetros

Nome	Local	Tipo	Descrição
`ivrId`obrigatório	path	string	Identificador da URA

Exemplo de requisição

# Obter URA
# Parâmetros de path/query já preenchidos com exemplos.
curl -X GET "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/ivrs/principal" \
  -H "x-api-key: SUA_CHAVE_DE_API"

GET/telephony-bridge/ivrs/:ivrId/didstelephony_bridge:ivrs:read

DIDs da URA

Lista números (DIDs) vinculados à URA.

Parâmetros

Nome	Local	Tipo	Descrição
`ivrId`obrigatório	path	string	Identificador da URA

Exemplo de requisição

# DIDs da URA
# Parâmetros de path/query já preenchidos com exemplos.
curl -X GET "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/ivrs/principal/dids" \
  -H "x-api-key: SUA_CHAVE_DE_API"

POST/telephony-bridge/ivrstelephony_bridge:ivrs:write

Criar URA

Cria uma nova URA de atendimento.

Parâmetros

Nome	Local	Tipo	Descrição
`ivr_id`obrigatório	body	string	Identificador da URA
`display_name`obrigatório	body	string	Nome de exibição

Corpo de exemplo

{
  "ivr_id": "principal",
  "display_name": "URA Principal",
  "greeting_audio_id": "boas_vindas",
  "options": [
    {
      "digit": "1",
      "action": "queue",
      "target": "suporte"
    }
  ]
}

Exemplo de requisição

# Criar URA
# Parâmetros de path/query já preenchidos com exemplos.
curl -X POST "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/ivrs" \
  -H "x-api-key: SUA_CHAVE_DE_API"

PATCH/telephony-bridge/ivrs/:ivrIdtelephony_bridge:ivrs:write

Atualizar URA

Atualiza campos de uma URA existente.

Parâmetros

Nome	Local	Tipo	Descrição
`ivrId`obrigatório	path	string	Identificador da URA

Corpo de exemplo

{
  "display_name": "URA Atualizada",
  "menu_audio_id": "menu_opcoes"
}

Exemplo de requisição

# Atualizar URA
# Parâmetros de path/query já preenchidos com exemplos.
curl -X PATCH "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/ivrs/principal" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"URA Atualizada","menu_audio_id":"menu_opcoes"}'

DELETE/telephony-bridge/ivrs/:ivrIdtelephony_bridge:ivrs:write

Excluir URA

Remove uma URA.

Parâmetros

Nome	Local	Tipo	Descrição
`ivrId`obrigatório	path	string	Identificador da URA

Exemplo de requisição

# Excluir URA
# Parâmetros de path/query já preenchidos com exemplos.
curl -X DELETE "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/ivrs/principal" \
  -H "x-api-key: SUA_CHAVE_DE_API"

DIDs

GET/telephony-bridge/didstelephony_bridge:dids:read

Listar DIDs

Lista números de entrada (DIDs).

Exemplo de requisição

# Listar DIDs
# Parâmetros de path/query já preenchidos com exemplos.
curl -X GET "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/dids" \
  -H "x-api-key: SUA_CHAVE_DE_API"

GET/telephony-bridge/dids/:numbertelephony_bridge:dids:read

Obter DID

Retorna detalhes de um número.

Parâmetros

Nome	Local	Tipo	Descrição
`number`obrigatório	path	string	Número (somente dígitos)

Exemplo de requisição

# Obter DID
# Parâmetros de path/query já preenchidos com exemplos.
curl -X GET "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/dids/5514981927913" \
  -H "x-api-key: SUA_CHAVE_DE_API"

POST/telephony-bridge/didstelephony_bridge:dids:write

Criar DID

Associa um número a uma URA.

Parâmetros

Nome	Local	Tipo	Descrição
`number`obrigatório	body	string	Número (10 a 15 dígitos)
`ivr_id`	body	string	URA de destino (null para nenhuma)

Corpo de exemplo

{
  "number": "5514981927913",
  "ivr_id": "principal"
}

Exemplo de requisição

# Criar DID
# Parâmetros de path/query já preenchidos com exemplos.
curl -X POST "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/dids" \
  -H "x-api-key: SUA_CHAVE_DE_API"

PATCH/telephony-bridge/dids/:numbertelephony_bridge:dids:write

Atualizar DID

Altera a URA vinculada ao número.

Parâmetros

Nome	Local	Tipo	Descrição
`number`obrigatório	path	string	Número
`ivr_id`obrigatório	body	string	Nova URA ou null

Corpo de exemplo

{
  "ivr_id": "principal"
}

Exemplo de requisição

# Atualizar DID
# Parâmetros de path/query já preenchidos com exemplos.
curl -X PATCH "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/dids/5514981927913" \
  -H "x-api-key: SUA_CHAVE_DE_API"

DELETE/telephony-bridge/dids/:numbertelephony_bridge:dids:write

Excluir DID

Remove um número do tenant.

Parâmetros

Nome	Local	Tipo	Descrição
`number`obrigatório	path	string	Número

Exemplo de requisição

# Excluir DID
# Parâmetros de path/query já preenchidos com exemplos.
curl -X DELETE "https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge/dids/5514981927913" \
  -H "x-api-key: SUA_CHAVE_DE_API"

Webhooks

Eventos em tempo real

Configure um endpoint HTTPS no painel (Segurança → Webhooks) para receber o ciclo de vida completo das chamadas. Apenas os 6 eventos abaixo devem ser considerados; qualquer outro evento da API deve ser ignorado.

Entrega e segurança

Método

POST

Content-Type

application/json

Assinatura

HMAC-SHA256

Headers de segurança

X-Webhook-Id: Identificador único do webhook configurado.
X-Webhook-Timestamp: Timestamp Unix em milissegundos usado na assinatura.
X-Webhook-Signature: Assinatura HMAC-SHA256 no formato v1=hash.

Payload assinado: webhookId.timestamp.bodyJson

Verificar assinatura

Valide que a requisição veio da Bemmelhor recriando a assinatura com o secret do webhook.

const crypto = require('crypto');

function verifyWebhookSignature(req, secret) {
  const webhookId = req.headers['x-webhook-id'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const receivedSignature = req.headers['x-webhook-signature'];
  const bodyJson = JSON.stringify(req.body);
  const payload = `${webhookId}.${timestamp}.${bodyJson}`;
  const expectedSignature = 'v1=' + crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(receivedSignature)
  );
}

app.post('/webhook', (req, res) => {
  if (!verifyWebhookSignature(req, 'SEU_SECRET_AQUI')) {
    return res.status(401).json({ error: 'Assinatura inválida' });
  }
  res.status(200).send('OK');
});

Início de Discagem (Dial)

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.

{
  "Event": "Dial",
  "SubEvent": "Begin",
  "Channel": "SIP/9001-000006da",
  "Destination": "SIP/bina-000006db",
  "CallerIDNum": "9001",
  "UniqueID": "1773334415.1773",
  "DestUniqueID": "1773334415.1774",
  "Dialstring": "bina/5532984184189"
}

Campos importantes

CallerIDNum: Quem está ligando (ramal ou número externo).
Destination: Canal de destino da chamada.
Dialstring: Número discado ou ramal de destino.
UniqueID / DestUniqueID: Identificadores únicos para correlacionar eventos.

Mudança de Estado (Newstate)

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.

{
  "Event": "Newstate",
  "ChannelStateDesc": "Up",
  "CallerIDNum": "9001",
  "ConnectedLineNum": "32984184189"
}

Campos importantes

ChannelStateDesc: Ringing = ramal tocando, Ring = telefone tocando, Up = chamada atendida.
CallerIDNum: Número de quem está chamando.
ConnectedLineNum: Número da linha conectada (quem atendeu).

Chamada Conectada (Bridge Link)

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.

{
  "Event": "Bridge",
  "Bridgestate": "Link",
  "Channel1": "SIP/9001-000006f3",
  "Channel2": "SIP/bina-000006f4",
  "Uniqueid1": "1773335384.1802",
  "Uniqueid2": "1773335384.1803",
  "CallerID1": "9001",
  "CallerID2": "032984184189"
}

Campos importantes

Channel1 / Channel2: Os dois canais conectados.
CallerID1 / CallerID2: Identificação de quem atendeu em cada lado.
Uniqueid1 / Uniqueid2: IDs para correlacionar com outros eventos.

Chamada Desconectada (Bridge Unlink)

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

{
  "Event": "Bridge",
  "Bridgestate": "Unlink",
  "Channel1": "SIP/9001-000006fb",
  "Channel2": "SIP/bina-000006fc"
}

Campos importantes

Channel1 / Channel2: Os canais que foram desconectados.
Bridgestate: Sempre 'Unlink' neste evento.

Fim de Chamada (Hangup)

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.

{
  "Event": "Hangup",
  "Channel": "SIP/9001-00000709",
  "Uniqueid": "1773336018.1824",
  "CallerIDNum": "9001",
  "ConnectedLineNum": "32984184189",
  "Cause": "16",
  "Cause-txt": "Normal Clearing"
}

Campos importantes

Cause: Código do motivo (16 = Normal Clearing, etc.).
Cause-txt: Descrição textual do motivo.
CallerIDNum / ConnectedLineNum: Identificam quem desligou.

Registro de Chamada (CDR)

Disparado somente ao final da chamada, com resumo consolidado. Contém duração, origem, destino, billsec (tempo tarifado), disposition e demais dados do registro. Use para faturamento, relatórios e integrações que precisam de um único evento com resumo da chamada.

{
  "Event": "Cdr",
  "Privilege": "cdr,all",
  "AccountCode": "",
  "Source": "6010",
  "Destination": "0311999887766",
  "DestinationContext": "from-internal",
  "CallerID": "\"6010\" <6010>",
  "Channel": "SIP/6010-00000090",
  "DestinationChannel": "SIP/trunk-00000091",
  "LastApplication": "Dial",
  "LastData": "SIP/trunk/0311999887766,120,TtrM(atenddial^6010)",
  "StartTime": "2026-03-16 15:45:29",
  "AnswerTime": "2026-03-16 15:45:32",
  "EndTime": "2026-03-16 15:45:40",
  "Duration": "11",
  "BillableSeconds": "8",
  "Disposition": "ANSWERED",
  "AMAFlags": "DOCUMENTATION",
  "UniqueID": "1739123456.100",
  "UserField": "6010",
  "Queue": "",
  "CallType": "OUTCOMING",
  "DstOperator": "11",
  "DstPhoneNumber": "999887766",
  "DstDDD": "",
  "DstType": "MOVEL",
  "DstDistance": "LDN",
  "ItemCampaignId": ""
}

Campos importantes

Source / Destination: Origem e destino da chamada.
Duration / BillableSeconds: Duração total e tempo tarifado em segundos.
Disposition: Resultado: ANSWERED, NO ANSWER, BUSY, FAILED, etc.
StartTime / AnswerTime / EndTime: Timestamps de início, atendimento e fim.

Softphone

Iframe do softphone Web

Incorpore o softphone da Bemmelhor no seu CRM com um link único por organização. O administrador define origens permitidas, teclado numérico e credenciais. No iframe, o usuário digita a senha, recebe um JWT e o softphone conecta ao ramal.

Visão geral do fluxo

O administrador configura o link credenciado (origens permitidas, teclado de discagem) na aba Softphone (embed) do painel.
O administrador cadastra credenciais; cada uma associa um usuário/ramal a uma senha que o operador digitará no iframe.
O CRM incorpora o iframe com organizationId + embedId. Não é necessário passar JWT na URL.
O usuário abre o iframe, informa a senha e o front-end chama embed-login. O JWT fica no sessionStorage da aba do iframe.
Com o JWT válido, o softphone obtém credenciais SIP via embed-bootstrap e registra o ramal na rede.

Requisitos

Asterisk em modo PJSIP (stack nova) ou gateway legado com softphone WebRTC habilitado para a organização.
Ramal com senha SIP WebRTC configurada. Cada credencial de embed aponta para um ramal específico.
HTML do iframe com allow="microphone; autoplay" e referrerpolicy="strict-origin-when-cross-origin" para validar a origem do site pai quando houver allowedOrigins.

APIs de gestão (sessão administrador)

Autenticação por cookie de sessão Bemmelhor, papel de administrador da organização.

Link credenciado

GEThttps://service.bemmelhor.com.br/api/organizations/{organizationId}/webrtc-softphone/organization-link
Retorna link (iframeSrc, html, publicId, allowedOrigins, showDialpad), organization e eligibility.
PATCHhttps://service.bemmelhor.com.br/api/organizations/{organizationId}/webrtc-softphone/organization-link
Corpo JSON opcional: allowedOrigins[], showDialpad?, isActive?.

Credenciais

GEThttps://service.bemmelhor.com.br/api/organizations/{organizationId}/webrtc-softphone/credentials
Lista credenciais com ramal e usuário vinculados.
POSThttps://service.bemmelhor.com.br/api/organizations/{organizationId}/webrtc-softphone/credentials
Corpo JSON: userExtensionId (UUID do ramal), password (senha do iframe), label?, isActive?.
PATCHhttps://service.bemmelhor.com.br/api/organizations/{organizationId}/webrtc-softphone/credentials/{credentialId}
Atualiza password, label ou isActive.
DELETEhttps://service.bemmelhor.com.br/api/organizations/{organizationId}/webrtc-softphone/credentials/{credentialId}
Remove a credencial; o usuário deixa de acessar o softphone com aquela senha.

Fluxo no iframe (usuário final)

Rotas públicas, sem cookie de sessão. O JWT fica no sessionStorage da aba do iframe.

GEThttps://service.bemmelhor.com.br/api/webrtc-softphone/organizations/{organizationId}/webrtc-softphone/embed-public-config?publicId={embedId}
Carrega nome/logo da organização, elegibilidade do softphone e se o teclado está habilitado. Chamado antes do login.
POSThttps://service.bemmelhor.com.br/api/webrtc-softphone/organizations/{organizationId}/webrtc-softphone/embed-login
Corpo: { "publicId", "password", "parentOrigin" }. Resposta: accessToken (JWT), expiresIn, extensionNumber, showDialpad e dados do usuário.
GEThttps://service.bemmelhor.com.br/api/webrtc-softphone/organizations/{organizationId}/webrtc-softphone/embed-bootstrap
Cabeçalho Authorization: Bearer <accessToken>. Retorna URL WSS, credenciais SIP WebRTC, ICE servers e ramal.

Incorporar no CRM

Substitua {organizationId} e {embedId} pelos valores do painel (Segurança → Softphone embed).

https://app.bemmelhor.com.br/embed/webrtc-softphone?organizationId={organizationId}&embedId={embedId}

Pré-discagem a partir do CRM

Acrescente na query string tel, to ou number. O usuário ainda precisa estar autenticado no iframe.

https://app.bemmelhor.com.br/embed/webrtc-softphone?organizationId={organizationId}&embedId={embedId}&tel=5511999998888

Modo alternativo: sessão Bemmelhor

Reutiliza o login da Bemmelhor (cookie). Útil em intranet; em iframe de terceiros o navegador pode bloquear cookies — prefira o fluxo credenciado com senha.

https://app.bemmelhor.com.br/embed/organizations/{organizationId}/softphone

Pronto para integrar?

Acesse o painel para gerar chaves de API, configurar webhooks e copiar o link do softphone da sua organização.

Entrar no painel Downloads