Desenvolvimento de um aplicativo de módulo de telefonia

Este documento descreve o que um desenvolvedor externo precisa implementar para criar seu próprio aplicativo de telefonia para o Marketplace do Flowlu.

Para desenvolver um aplicativo, consulte o Flowlu JS SDK.

Arquitetura geral da integração

Seu aplicativo atua como um middleware entre o Flowlu e o servidor de telefonia externo:

Responsabilidades do seu aplicativo:

1. IU de Configurações — uma página de conexão aberta dentro do Flowlu em um iframe.
2. Backend — armazena a integração (mapeamento de usuário do CRM ↔ conta do CRM ↔ conta do canal externo) e os tokens OAuth.
3. Canal de Saída — recebe webhooks do Flowlu e entrega eventos ao servidor externo.
4. Canal de Entrada — recebe notificações do servidor externo, transforma os dados para o formato exigido e os transmite para o Flowlu.

O que precisa ser implementado

Campos para registro do canal (telephony/create):

• name — o nome da integração específica
• ref_id — o ID do seu MiniApp
• code — deve ser o valor mini_app
• webhook_url — a URL para onde o CRM enviará as solicitações
• icon_url — uma URL para o ícone da integração
• can_redirect (true/false) — a capacidade de redirecionar uma chamada para outro funcionário
• manifest_id — ID do ponto de integração

Registro do aplicativo no marketplace e ponto de integração

Passos:

1. Crie um aplicativo em https:///module/miniapps/cabinet.
2. No manifesto do aplicativo, adicione o ponto de integração "telephony service connection".
3. Preencha os campos do ponto de integração:

Após salvar o manifesto do aplicativo, seu aplicativo aparecerá na lista de serviços de telefonia.

Dados de contexto do iframe

O Flowlu enviará uma solicitação POST com o seguinte corpo para a URL especificada em iframe (src):

código JavaScript

{
  "domain": ".flowlu.com",
  "language": "en",
  "placement": {
    "id": "my_channel_wizard",
    "code": "contactcenter.service.wizard"
  },
  "https": "1",
  "account": { "id": "123456" },
  "app": {
    "id": "",
    "version": "1.0.0"
  },
  "auth": {
    "expires_at": "2026-03-27 17:29:33",
    "access_token": "",
    "refresh_token": ""
  },
  "ratelimit": { "limit": "16" }
}

Seu endpoint deve:

1. Validar o payload e extrair domain, app.id, app.version, account.id, auth.*.
2. Construir a URL base do CRM: https://{domain} (ou http se https=0 — relevante apenas para ambientes de desenv.).
3. Identificar o usuário do CRM. Padrão recomendado — "busca em duas vias" (two-way lookup):
   • Caminho rápido: pesquise em seu banco de dados o cliente OAuth pelo hash de access_token + domain + app.version. Se encontrado, o usuário já é conhecido; não há necessidade de chamar a API do CRM.
   • Caminho lento: se não encontrado, execute GET https://{domain}/api/v1/module/core/user/get com o cabeçalho Authorization: Bearer {access_token} e crie um registro para o usuário do CRM com base na resposta.
4. Salvar/atualizar tokens OAuth. A chave de unicidade é (user_id, domain, app_version). É aconselhável limpar os tokens de versões antigas do aplicativo durante as atualizações para evitar o inchaço do banco de dados.
5. Renderizar o formulário de configurações e retornar o HTML para o cliente.

Fluxo de dados bidirecional

Após conectar a integração, a troca de dados ocorre em duas direções:

Flowlu -> seu webhook_url — o CRM envia solicitações POST para o seu servidor:

• iniciação de uma chamada de saída;
• solicitação de listas de chamadas e dados de chamadas específicas;
• solicitação da lista de funcionários SIP;
• verificação de integridade da integração.

Seu aplicativo -> Flowlu — você envia solicitações POST com eventos do webhook de chamada para o endpoint do CRM (POST /external/telephony/hook/mini_app/{account_id}/{telephony_uuid}):

• inicialização da chamada (para chamadas recebidas, o CRM retorna uma decisão de roteamento);
• chamada conectada;
• chamada concluída;
• informações de gravação da chamada;
• atualização do estado da chamada.

Contratos detalhados (formatos de solicitação/resposta, códigos de erro) são descritos nas especificações OpenAPI:

• outgoing_hooks.yaml — solicitações do Flowlu para o seu webhook (arquivo anexo ao artigo)
• incoming_events.yaml — eventos do seu aplicativo para o Flowlu (arquivo anexo ao artigo)

Fluxo de trabalho da integração

Usuário CRM                   Flowlu                 Seu Aplicativo
       │                         │                            │
       │  Clica em "Conectar"    │                            │
       │────────────────────────>│                            │
       │                         │                            │
       │                         │  Abre iframe (POST         │
       │                         │  com dados de auth)        │
       │                         │───────────────────────────>│
       │                         │                            │
       │                         │  Recebe tokens OAuth       │
       │                         │<───────────────────────────│
       │                         │                            │
       │                         │  GET /api/v1/module/       │
       │                         │  core/user/get             │
       │                         │<───────────────────────────│
       │                         │                            │
       │                         │  {id, name, email}         │
       │                         │───────────────────────────>│
       │                         │                            │
       │                         │  POST /api/v1/module/      │
       │                         │  telephony/telephony/create│
       │                         │<───────────────────────────│
       │                         │                            │
       │                         │  {uuid: telephony_uuid}    │
       │                         │───────────────────────────>│
       │                         │                            │
       │   Conexão pronta        │                            │
       │<────────────────────────│                            │
       │                         │                            │

Após isso, o CRM começa a enviar solicitações para o webhook_url, e seu aplicativo pode enviar eventos de chamada para o Flowlu.