API Docs

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

Autenticação

Base da API: https://service.bemmelhor.com.br/api/partner/v1. Use o token PT-<SIGLA>-<segredo> em todas as requisições.

curl "https://service.bemmelhor.com.br/api/partner/v1/organizations" \
  -H "Authorization: Bearer PT-ACME-seu_segredo"

API de integração

O mesmo token PT-… autentica a API de integração em https://service.bemmelhor.com.br/api/integrations/v1, apenas nas organizações vinculadas ao partner. Informe a org alvo com X-Organization-Id (obrigatório se houver mais de uma org). Scopes equivalentes a * dentro dessas orgs. Inclui calls, gravações, click-to-call e o CRUD de Telefonia & URA.

curl "https://service.bemmelhor.com.br/api/integrations/v1/calls?page=1&limit=20" \
  -H "Authorization: Bearer PT-ACME-seu_segredo" \
  -H "X-Organization-Id: 25baa84c-5afd-4f32-9417-5de758aaf4cd"

CRUD Telefonia & URA

Com o token PT-… você pode criar, listar, atualizar e excluir ramais, filas, áudios, URAs e DIDs via Bridge: somente nas organizações da allowlist com integração partner / Telefonia & WhatsApp. Use a API de integração, não as rotas /api/organizations/... (retornam 403 para PT). Para status em tempo real dos ramais (sem Bridge), use GET /api/integrations/v1/extensions.

Base: https://service.bemmelhor.com.br/api/integrations/v1/telephony-bridge. Pré-requisito: org com Bridge configurado. Listagens usam envelope { items, total }. DELETE bem-sucedido → 204 sem corpo. Catálogo completo: seção Telefonia & URA.

{
  "extension": "6001",
  "display_name": "Maria Silva",
  "transport": "wss",
  "secret": "auto",
  "default_queue": null
}

{
  "items": [
    {
      "tenant_id": "acme",
      "extension": "6001",
      "display_name": "Maria Silva",
      "transport": "wss",
      "status": "online",
      "default_queue": "vendas",
      "sip_username": "acme-6001"
    }
  ],
  "total": 1
}

{
  "name": "vendas",
  "display_name": "Vendas",
  "strategy": "rrmemory"
}

{
  "add": [
    "6001"
  ],
  "remove": [
    "6002"
  ]
}

{
  "audio_id": "saudacao_entrada",
  "source": "tts",
  "text": "Bem-vindo ao atendimento. Digite a opção desejada.",
  "voice": "francisca",
  "rate": "+0%",
  "pitch": "+0Hz",
  "description": "Saudação da URA"
}

{
  "items": [
    {
      "voice": "francisca",
      "label": "Francisca"
    },
    {
      "voice": "antonio",
      "label": "Antonio"
    },
    {
      "voice": "leila",
      "label": "Leila"
    }
  ]
}

{
  "ivr_id": "ura_principal",
  "display_name": "URA Principal",
  "language": "pt_BR",
  "greeting_audio_id": "saudacao_entrada",
  "menu_audio_id": "menu_opcoes",
  "options": [
    {
      "digit": "1",
      "action": "queue",
      "target": "vendas",
      "voice_keywords": [
        "vendas",
        "comercial"
      ]
    },
    {
      "digit": "2",
      "action": "extension",
      "target": "6001"
    },
    {
      "digit": "9",
      "action": "hangup"
    }
  ],
  "allow_direct_extension_dial": true,
  "extension_dial_patterns": [
    "6XXX"
  ],
  "voice_recognition": {
    "enabled": false,
    "engine": "whisper_local",
    "max_record_seconds": 6
  },
  "timeout_config": {
    "wait_dtmf_seconds": 5,
    "max_tries": 3,
    "on_timeout_action": "hangup"
  },
  "invalid_input_action": "replay"
}

{
  "ivr_id": "ura_principal"
}

{
  "error": "organizationId é obrigatório para token de partner (header x-organization-id, query ou body)"
}

{
  "error": "Informe extensionNumber ou userExtensionId"
}

{
  "error": "Credenciais inválidas ou expiradas"
}

{
  "error": "Partner sem acesso a esta organização"
}

{
  "error": "Softphone WebRTC não está habilitado para esta organização"
}

{
  "error": "Limite de áudios atingido para esta organização"
}

{
  "code": "whatsapp_permission_pending",
  "permission_required": true,
  "permission": {
    "from_did": "551140028922",
    "to_msisdn": "5511987654321",
    "status": "pending",
    "permission_type": "temporary",
    "gupshup_message_id": "gupshup-msg-abc123",
    "requested_at": "2026-08-07T18:10:00.000Z",
    "expires_at": null,
    "tenant_id": "acme"
  },
  "message": "Solicitação de permissão enviada ao cliente no WhatsApp. Aguarde a resposta e tente ligar novamente.",
  "error": "Solicitação de permissão enviada ao cliente no WhatsApp. Aguarde a resposta e tente ligar novamente."
}

{
  "error": "Nenhum DID cadastrado para este tenant. Cadastre um DID antes de ligar via WhatsApp."
}

Canais de discagem

O softphone da plataforma escolhe o canal na UI e bifurca o caminho. No partner é o mesmo: PSTN pelo WSS, WhatsApp pelo POST Bridge. Consulte capabilities para saber o que a org tem habilitado.

curl "https://service.bemmelhor.com.br/api/partner/v1/organizations/{organizationId}/telephony-bridge/capabilities" \
  -H "Authorization: Bearer PT-ACME-seu_segredo"

No oficial (Meta), to_msisdn na resposta pode vir sem o 9º dígito. Em 409 com whatsapp_permission_pending, mostre message e não trate como chamada ativa.

Criar sessão softphone

Cria uma sessão curta para um ramal. Informe extensionNumber ou userExtensionId. A resposta traz JWT, metadados SIP e a URL do proxy. A senha SIP nunca é devolvida.

{
  "extensionNumber": "6001"
}

curl -X POST "https://service.bemmelhor.com.br/api/partner/v1/organizations/{organizationId}/softphone-sessions" \
  -H "Authorization: Bearer PT-ACME-seu_segredo" \
  -H "Content-Type: application/json" \
  -d '{"extensionNumber":"6001"}'

Proxy SIP (WSS) e ligações

Conecte o SIP.js no proxy Bemmelhor, nunca no Asterisk. Passe o JWT da sessão na query ?token=. Deixe a senha SIP vazia: o proxy autentica no hop interno.

const ua = new UserAgent({
  uri,
  transportOptions: {
    server: `${session.softphoneProxyUrl}?token=${encodeURIComponent(session.accessToken)}`,
    // Intervalo em SEGUNDOS entre CRLF keep-alive no WebSocket.
    // Default do SIP.js = 0 (desligado) → WSS ocioso cai ~60s com code 1006.
    keepAliveInterval: 30, // use valor < timeout de idle da infra (ex.: 60s)
    keepAliveDebounce: 10,
  },
  authorizationUsername: session.sipAuthUsername,
  authorizationPassword: "",
});

// session.expiresIn === 900 (15 min). Renove ANTES do exp.
const RENEW_MARGIN_MS = 60_000; // 1 min de folga

function scheduleSessionRenewal(session, connectSip) {
  const delay = Math.max(0, session.expiresIn * 1000 - RENEW_MARGIN_MS);
  return setTimeout(() => {
    void (async () => {
      // 1) Nova softphone-session (JWT fresco)
      const next = await createSoftphoneSession(/* org + ramal */);
      // 2) Dispose limpo + reconnect no proxy com o novo token
      await disposeSip();
      await connectSip(next);
    })();
  }, delay);
}

async function disposeSip() {
  const registerer = registererRef.current;
  registererRef.current = null;
  if (registerer) {
    try {
      await registerer.dispose(); // para timers de re-REGISTER
    } catch {
      /* ignore */
    }
  }

  const ua = userAgentRef.current;
  userAgentRef.current = null;
  if (ua) {
    try {
      await ua.stop();
    } catch {
      /* ignore */
    }
  }
}

// No onDisconnect / TransportState.Disconnected:
// NÃO só zere as refs — chame disposeSip(), senão o Registerer
// continua com timer e tenta REGISTER com transporte morto → 503.

import { UserAgent, Registerer, RegistererState } from "sip.js";

// register() resolve quando o pedido é ENVIADO, não quando o 200 chega.
// Espere RegistererState.Registered antes de considerar a linha pronta.
const registerer = new Registerer(ua, {
  expires: 120,
  // % do Expires em que o re-REGISTER é disparado (50–99).
  // Default ~99 com Expires 120 → renova ~aos 119s.
  // Se o 200 demorar alguns segundos, o timer local marca Unregistered
  // por uma janela curta (WSS continua de pé; keepalives/OPTIONS seguem).
  // 80 → renova ~aos 96s e evita essa corrida.
  refreshFrequency: 80,
  logConfiguration: false,
});

await new Promise((resolve, reject) => {
  const timeout = setTimeout(() => {
    reject(new Error("Timeout aguardando REGISTER"));
  }, 15000);

  registerer.stateChange.addListener((state) => {
    if (state === RegistererState.Registered) {
      clearTimeout(timeout);
      resolve(undefined);
    }
    // Unregistered no meio de um refresh lento: não trate como queda do WSS.
    // Espere o próximo Registered ou só reconecte se persistir.
  });

  void registerer.register().catch((err) => {
    clearTimeout(timeout);
    reject(err);
  });
});

import {
  UserAgent,
  Registerer,
  SessionState,
  Invitation,
} from "sip.js";

// session = resposta do POST softphone-sessions
// remoteAudio = <audio autoPlay playsInline /> no DOM
let activeSession: Invitation | null = null;

const uri = UserAgent.makeURI(
  `sip:${session.sipAuthUsername}@${session.sipDomain}`
);

const ua = new UserAgent({
  uri,
  transportOptions: {
    server: `${session.softphoneProxyUrl}?token=${encodeURIComponent(session.accessToken)}`,
    // Evita close 1006 por idle (~60s) em proxy/LB/Cloudflare
    keepAliveInterval: 30,
    keepAliveDebounce: 10,
    connectionTimeout: 15,
  },
  authorizationUsername: session.sipAuthUsername,
  authorizationPassword: "",
  sessionDescriptionHandlerFactoryOptions: {
    peerConnectionConfiguration: {
      iceServers: session.iceServers,
    },
  },
  delegate: {
    onInvite: (invitation: Invitation) => {
      // Uma chamada por vez: se já houver sessão, recuse
      if (activeSession) {
        void invitation.reject({ statusCode: 486 }); // Busy Here
        return;
      }

      activeSession = invitation;

      // UI: mostrar "Chamando...", callerId, botões Atender / Recusar
      const from = invitation.remoteIdentity.uri.toString();
      console.log("Ligação entrante:", from);

      invitation.stateChange.addListener((state) => {
        if (state === SessionState.Established) {
          const sdh = invitation.sessionDescriptionHandler as {
            remoteMediaStream?: MediaStream;
          } | undefined;
          if (sdh?.remoteMediaStream && remoteAudio) {
            remoteAudio.srcObject = sdh.remoteMediaStream;
            void remoteAudio.play().catch(() => {});
          }
        }

        if (state === SessionState.Terminated) {
          activeSession = null;
          if (remoteAudio) remoteAudio.srcObject = null;
          // UI: voltar para "registrado" / idle
        }
      });
    },
  },
});

await ua.start();
await new Registerer(ua, {
  expires: 120,
  refreshFrequency: 80,
}).register();

// Chamado pelos botões da UI quando houver activeSession (toque)
async function acceptIncomingCall() {
  if (!activeSession) return;
  await activeSession.accept();
}

async function rejectIncomingCall() {
  if (!activeSession) return;
  await activeSession.reject({ statusCode: 486 });
  activeSession = null;
}

async function hangup() {
  if (!activeSession) return;
  await activeSession.bye();
  activeSession = null;
}

Endpoints Partner API

Base https://service.bemmelhor.com.br/api/partner/v1. Todos exigem o token PT e respeitam a allowlist. Abaixo: request e response de exemplo por rota.

• GETListar organizações200
  https://service.bemmelhor.com.br/api/partner/v1/organizations

  Retorna as organizações que o seu token pode acessar, com flags de softphone.

  Response 200

  Copiar

  {
    "organizations": [
      {
        "id": "25baa84c-5afd-4f32-9417-5de758aaf4cd",
        "name": "Acme Telecom",
        "avatarUrl": "https://cdn.exemplo.com/orgs/acme.png",
        "webrtcBrowserSoftphoneEnabled": true,
        "webrtcSoftphoneMode": "pjsip"
      }
    ]
  }

• GETListar ramais (softphone)200
  https://service.bemmelhor.com.br/api/partner/v1/organizations/{organizationId}/extensions

  Lista ramais da organização para softphone. Indica se há senha WebRTC cadastrada, sem expor a senha SIP. Não é o CRUD Bridge.

  • • hasWebrtcSipPassword=false impede criar sessão até um admin cadastrar a senha.
  Response 200

  Copiar

  {
    "softphoneEnabled": true,
    "extensions": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "extensionNumber": "6001",
        "hasWebrtcSipPassword": true,
        "user": {
          "id": "11111111-2222-3333-4444-555555555555",
          "name": "Maria Silva",
          "email": "maria@acme.com"
        }
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "extensionNumber": "6002",
        "hasWebrtcSipPassword": false,
        "user": null
      }
    ]
  }

• GETListar contatos200
  https://service.bemmelhor.com.br/api/partner/v1/organizations/{organizationId}/contacts

  Busca paginada. Query: search, page, limit.

  Response 200

  Copiar

  {
    "contacts": [
      {
        "id": "c0ffee00-0000-4000-8000-000000000001",
        "name": "João Cliente",
        "phones": [
          {
            "id": "p1111111-1111-4111-8111-111111111111",
            "phoneNumber": "5511987654321"
          }
        ]
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }

• POSTCriar sessão softphone201
  https://service.bemmelhor.com.br/api/partner/v1/organizations/{organizationId}/softphone-sessions

  Emite JWT de sessão (~15 min). Informe extensionNumber ou userExtensionId. Não devolve senha SIP.

  RequestResponse 201

  Copiar

  {
    "extensionNumber": "6001"
  }

• GETCapabilities (canais)200
  https://service.bemmelhor.com.br/api/partner/v1/organizations/{organizationId}/telephony-bridge/capabilities

  Lista canais habilitados (pstn, whatsapp_official, whatsapp_unofficial) e DIDs da org.

  Response 200

  Copiar

  {
    "tenant_id": "acme",
    "call_types": [
      {
        "code": 0,
        "name": "pstn",
        "label": "Telefone (PSTN)",
        "enabled": true,
        "reason": null
      },
      {
        "code": 1,
        "name": "whatsapp_official",
        "label": "WhatsApp Oficial",
        "enabled": true,
        "reason": null
      },
      {
        "code": 2,
        "name": "whatsapp_unofficial",
        "label": "WhatsApp Não Oficial",
        "enabled": false,
        "reason": "Canal não configurado para este tenant"
      }
    ],
    "dids": [
      "551140028922",
      "5514981927913"
    ]
  }

• POSTLigação WhatsApp202
  https://service.bemmelhor.com.br/api/partner/v1/organizations/{organizationId}/telephony-bridge/calls

  Origina ligação WhatsApp oficial (call_type=1) ou não oficial (call_type=2). PSTN usa WSS INVITE. Sucesso típico: HTTP 202.

  • • No oficial (Meta), o 9º dígito do celular pode ser normalizado na resposta (to_msisdn).
  • • HTTP 409 com code=whatsapp_permission_pending: mostre message e não retente em loop.
  RequestResponse 202

  Copiar

  {
    "extensionNumber": "6001",
    "to_msisdn": "5511987654321",
    "call_type": 1,
    "from_did": "551140028922"
  }

• POSTTransferência assistida202
  https://service.bemmelhor.com.br/api/partner/v1/organizations/{organizationId}/softphone/supervised-transfer

  Com o ramal em ligação, inicia transferência assistida: o destino toca; só após atender o cliente é bridged. Emite TransferStarted (webhook + /ws/telephony-events).

  • • Cancelar: POST .../softphone/supervised-transfer/cancel com { transferId }.
  • • Status: GET .../softphone/supervised-transfer/{transferId} (ringing, completed, failed, cancelled, timeout).
  • • Eventos: TransferStarted, TransferCompleted, TransferFailed, TransferCancelled, TransferTimeout.
  • • Erros: 400 ramal sem ligação / ramais iguais / canal do cliente; 404 ramal ou Asterisk; 409 já existe assistida em andamento; 401/403 autenticação e escopo.
  RequestResponse 202

  Copiar

  {
    "extensionNumber": "6001",
    "targetExtension": "6002"
  }

• POSTCancelar transferência assistida200
  https://service.bemmelhor.com.br/api/partner/v1/organizations/{organizationId}/softphone/supervised-transfer/cancel

  Encerra a consulta ao destino; a ligação permanece com o agente. Emite TransferCancelled.

  • • 200 também se a transferência já finalizou: message indica o status final (completed, failed, cancelled, timeout).
  • • Erros: 400 transferId inválido; 403 transferência não pertence a este ramal; 404 não encontrada.
  RequestResponse 200

  Copiar

  {
    "transferId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "extensionNumber": "6001"
  }

• GETStatus da transferência assistida200
  https://service.bemmelhor.com.br/api/partner/v1/organizations/{organizationId}/softphone/supervised-transfer/{transferId}

  Consulta o status (ringing, completed, failed, cancelled, timeout).

  • • status: ringing | completed | failed | cancelled | timeout.
  • • Em failed/timeout o campo error pode vir preenchido.
  • • Erros: 400 transferId obrigatório; 404 transferência não encontrada.
  Response 200

  Copiar

  {
    "transferId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "completed",
    "extensionNumber": "6001",
    "targetExtension": "6002",
    "transferMethod": "bridge_customer_target",
    "message": "Transferência assistida concluída"
  }