API Docs

Webhook por número (WhatsApp provisionado)

Em organização com números de WhatsApp oficial provisionados, cada número costuma ser uma conexão separada no seu sistema. Os eventos de ligação desses números trazem de qual número são, e cada webhook pode escutar só alguns números.

• OrganizationNumber: Número da empresa na ligação (E.164 sem +). Vai em todos os eventos da ligação, do começo ao fim, inclusive depois da URA, e em IncomingCallAllExtensionsOffline, WhatsAppCallOriginated e WhatsAppCallPermissionRequested.
• GupshupAppId: App Gupshup do número. Só vai quando a ligação passa pelo WhatsApp oficial; se o mesmo número for usado numa linha comum, a ligação por essa linha traz só o OrganizationNumber.

• Organização sem número provisionado (PSTN, WhatsApp não oficial) não recebe esses campos, e presença de ramal e ligação interna também não.
• Filtro por número: no painel (Segurança → Webhooks) ou na API, em phoneNumbers ao criar ou editar o webhook. Ausente ou [] = todos os números, que é o padrão; todo webhook existente continua assim.
• Com números escolhidos, o webhook só recebe os eventos cujo OrganizationNumber está na lista. Eventos sem número (presença de ramal, ligação interna, ligação por outro número) não chegam a ele: mantenha também um webhook com todos os números se precisar deles.
• Só números provisionados da organização são aceitos (com ou sem +). A listagem de webhooks devolve os números disponíveis em provisionedNumbers (API da organização) ou availablePhoneNumbers (API de parceiro).

POST /api/organizations/{organizationId}/webhooks
{
  "name": "Digisac — Loja",
  "url": "https://seu-sistema.com/webhooks/loja",
  "events": ["Dial", "BridgeLink", "BridgeUnlink", "Hangup"],
  "phoneNumbers": ["5514981927913"]
}

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, rememberDeviceEnabled), organization e eligibility.

• PATCHhttps://service.bemmelhor.com.br/api/organizations/{organizationId}/webrtc-softphone/organization-link

  Corpo JSON opcional: allowedOrigins[], showDialpad?, isActive?, rememberDeviceEnabled?. Desligar rememberDeviceEnabled esquece todos os navegadores lembrados na hora.

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. Com rememberDeviceEnabled ligado, também devolve rememberToken e rememberExpiresAt.

• POSThttps://service.bemmelhor.com.br/api/webrtc-softphone/organizations/{organizationId}/webrtc-softphone/embed-remember-login

  Entrada sem senha do navegador já lembrado. Corpo: { "publicId", "rememberToken", "parentOrigin" }. Mesma resposta do embed-login, com rememberToken girado a cada uso: guarde sempre o valor novo. Qualquer recusa volta 401, e aí é só apagar o que estava guardado e pedir a senha.

• 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

Pausa DND do ramal (softphone interno)

O softphone flutuante do dashboard deve usar DND do ramal inteiro, não a pausa por fila. O ramal fica ocupado para filas e ligações diretas. Exige Telefonia & WhatsApp / Bridge na organização.

POST /queue/pause exige fila e só tira o ramal daquela fila (AMI). POST /extension/pause não envia fila: é DND global via Bridge e grava histórico em extension_pause_logs.

Autenticação: Cookie de sessão do painel (mesmo api client do dashboard). Papel mínimo: member. O usuário só pausa ramais vinculados a ele (UserExtension).

• POSThttps://service.bemmelhor.com.br/api/organizations/{organizationId}/extension/pause

  Ativa DND. Body: { extensionNumber, reason }. Motivo obrigatório (máx. 500). Resposta 201.

• POSThttps://service.bemmelhor.com.br/api/organizations/{organizationId}/extension/unpause

  Remove DND. Body: { extensionNumber }. Sem motivo. Resposta 200.

• GEThttps://service.bemmelhor.com.br/api/organizations/{organizationId}/extension/pause?extensionNumber=6001

  Status atual (Bridge + log local). Query extensionNumber obrigatória. Papel viewer+.

• GEThttps://service.bemmelhor.com.br/api/organizations/{organizationId}/extension/pause-logs

  Histórico paginado. Query opcional: extensionNumber, userId, startDate, endDate, page, limit.

• GEThttps://service.bemmelhor.com.br/api/organizations/{organizationId}/extension/pause-stats

  Estatísticas de DND (ativas, finalizadas, duração).

POST https://service.bemmelhor.com.br/api/organizations/{organizationId}/extension/pause
Content-Type: application/json

{
  "extensionNumber": "6001",
  "reason": "Almoço"
}

Softphone interno (dashboard)

• Use o ramal selecionado no FloatingSoftphonePanel (selectedExtension).
• Peça o motivo num modal, igual à página de ramais/monitoramento.
• Ao abrir o painel, chame GET .../extension/pause?extensionNumber= para pintar o botão (pausado / disponível).
• Não use /queue/pause aqui: o softphone não tem contexto de fila e o DND precisa ocupar o ramal inteiro.
• Partner/embed continuam usando /api/integrations/v1/extension/pause (scope queues:pause).

GET /organizations/:id/asterisk/call-monitoring passa a incluir members[].isDnd, members[].dndReason e dndPauses[] (ramais em DND, mesmo fora de fila).

Helpers em lib/asterisk.ts: pauseExtensionDnd(organizationId, { extensionNumber, reason }), unpauseExtensionDnd(organizationId, { extensionNumber }), getExtensionDnd(organizationId, extensionNumber), getExtensionPauseLogs(organizationId, params?).

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, pausa de ramal em fila, DND do ramal 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": "Ramal não encontrado nesta organização"
}

{
  "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.

curl "https://service.bemmelhor.com.br/api/partner/v1/organizations/{organizationId}/telephony-bridge/calls/permission?to_msisdn=5511987654321&from_did=551140028922" \
  -H "Authorization: Bearer PT-ACME-seu_segredo"

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) para qualquer ramal da organização, vinculado ou não a um usuário. Informe extensionNumber ou userExtensionId. Não devolve senha SIP.

  • • O ramal não precisa estar vinculado a um usuário no painel: o vínculo é para uso interno (painel e embed).
  • • extensionNumber aceita o número curto (6001) ou o nome com o tenant (cliente_acme-6001).
  • • Ramal que não existe no tenant da organização responde 404.
  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"
  }

• GETConsultar permissão WhatsApp200
  https://service.bemmelhor.com.br/api/partner/v1/organizations/{organizationId}/telephony-bridge/calls/permission?to_msisdn=5511987654321

  Diz se o número pode receber ligação WhatsApp oficial (call_type=1) antes de discar. Só leitura: não envia pedido de permissão ao cliente.

  • • allowed=true só com status=accepted dentro da validade (expires_at).
  • • status: accepted, pending, rejected, expired ou not_requested.
  • • Query from_did opcional: sem ela, usa o primeiro DID da org.
  • • Consulta o número com e sem o 9º dígito do celular.
  Response 200

  Copiar

  {
    "allowed": true,
    "status": "accepted",
    "from_did": "551140028922",
    "to_msisdn": "5511987654321",
    "expires_at": "2026-12-28T14:02:11.000Z",
    "requested_at": "2026-09-28T14:01:03.000Z",
    "message": "O cliente autorizou receber ligações pelo WhatsApp."
  }

• 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"
  }