Conversational Agent Interface (CAI)

1. Visão geral

A Conversational Agent Interface (CAI) é a interface padrão do OMB Cloud AES para incorporar um fornecedor externo de agente conversacional aos canais digitais de um cliente. Abrange a captação por formulários, chat web e canais de mensagem, e a condução da conversa resultante até um agendamento ou um resultado registrado.

A divisão do trabalho é deliberada e delimitada. O Fornecedor traz a inteligência conversacional. O AES traz o fluxo de contatos, o roteamento e o registro permanente. Tudo o que o cliente vê, mede e opera continua vivendo no AES.

A empresa que implementa esta interface é referida a seguir como o Fornecedor. Cada Fornecedor recebe um provider_code e um conjunto de credenciais na incorporação.

Esta especificação é versionada e comum a todos os Fornecedores. Os valores próprios de cada ambiente — código do fornecedor, catálogo, credenciais, endereços autorizados — são entregues à parte, em anexo privado.

2. Responsabilidades

2.1 Interfaces

Ambos os sentidos são de envio ativo. Nenhuma das partes consulta a outra, e esta interface não expõe endpoints de leitura. Isso mantém a latência baixa, elimina sincronizações periódicas, e faz com que integrar-se tenha exatamente duas peças móveis.

3. Ciclo de vida

  1. Contato      Preenche um formulário ou escreve em um canal digital.

  2. AES          Cria o registro, resolve a unidade de destino e
                  atribui um lead_id que acompanha o relacionamento.

  3. AES → Forn.  [Interface A] Entrega a tarefa de contato com a
                  unidade e o contexto da solicitação.

  4. Fornecedor   Seleciona o número de origem daquela unidade e inicia
                  a conversa.

  5. Forn. → AES  [Interface B] Devolve a conversa conforme acontece,
                  e o resultado: agendamento feito ou motivo de encerramento.

  6. AES          Registra ambos no lead, marcados com o provider_code.
                  O cliente segue com o acompanhamento.

A unidade de destino é resolvida no momento da captação, onde se conhecem a landing page, a campanha e a localidade solicitada. Viaja no campo branch_code de cada tarefa, de modo que um Fornecedor nunca precisa manter nem atualizar lógica de roteamento conforme um cliente abre novas unidades.

4. Interface A — Tarefas de contato

POST {provider_endpoint}/contact-jobs
Content-Type:    application/json
X-CAI-Source:    aes
X-CAI-Signature: sha256=<hmac_hex>
X-CAI-Timestamp: 1787923271

O AES assina o que envia com o mesmo esquema da seção 6, usando o segredo oposto do par. O Fornecedor deve verificá-lo como o AES verifica o dele: mesmo algoritmo, mesma janela de 300 segundos, comparação em tempo constante.

O AES entrega cada contato que o Fornecedor deve atender, no momento da captação.

4.1 Corpo da requisição

{
  "lead_id":        "AES-38-104772",
  "event_id":       "job_9f2c1a8e4b",
  "branch_code":    "ACME-NORTE",
  "city":           "Belo Horizonte",
  "contact": {
    "name":         "Maria Fernanda Rios",
    "phone_e164":   "+5531912345678",
    "email":        "mfrios@example.com",
    "language":     "pt-BR"
  },
  "origin": {
    "channel":      "landing_form",
    "source":       "example.com/norte/servico",
    "campaign":     "primavera-norte",
    "captured_at":  "2026-08-27T14:02:11-03:00"
  },
  "brief": {
    "intent":       "book_appointment",
    "notes":        "Pediu horário no fim da tarde."
  },
  "callback_url":   "https://omb.cloud/app/api/cai_events.php"
}

4.2 Campos

4.3 Resposta esperada

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "provider_job_id":      "prv_77219",
  "assigned_number_e164": "+5531912345678"
}

Informar o número atribuído permite ao AES atribuir corretamente as mensagens recebidas daquele contato, e manter uma única conversa se ele voltar depois por outro canal.

5. Interface B — Eventos de conversa

POST https://omb.cloud/app/api/cai_events.php
Content-Type:    application/json
X-CAI-Provider:  {provider_code}
X-CAI-Signature: sha256=<hmac_hex>
X-CAI-Timestamp: 1787923271

Um único endpoint recebe tudo o que o Fornecedor devolve. É projetado para escrita em tempo real, assinado e idempotente, de modo que o Fornecedor possa enviar e reenviar sem risco de duplicação.

5.1 conversation.message

Um evento por mensagem, nos dois sentidos, conforme acontece. O registro completo é o que permite ao cliente ver o trabalho do agente tal como ocorreu e atribuir com precisão os agendamentos gerados.

{
  "event":            "conversation.message",
  "event_id":         "evt_4b81c07f",
  "lead_id":          "AES-38-104772",
  "provider_job_id":  "prv_77219",
  "channel":          "whatsapp",
  "from_number_e164": "+5531912345678",
  "direction":        "outbound",
  "author":           "agent",
  "text":             "Boa tarde Maria Fernanda, escrevo da...",
  "occurred_at":      "2026-08-27T14:04:39-03:00"
}

Campos do evento. event e event_id são obrigatórios em todos os eventos; o restante depende do tipo:

5.2 Eventos de agendamento

Enviados ao agendar, remarcar ou cancelar. O AES registra o agendamento e o reflete no painel da unidade correspondente.

{
  "event":        "appointment.booked",
  "event_id":     "evt_4b93a112",
  "lead_id":      "AES-38-104772",
  "branch_code":  "ACME-NORTE",
  "scheduled_at": "2026-08-29T11:30:00-03:00",
  "service":      "primeira_consulta",
  "notes":        "Prefere manhã.",
  "occurred_at":  "2026-08-27T14:11:02-03:00"
}

Valores aceitos para event: appointment.booked, appointment.rescheduled, appointment.cancelled.

5.3 job.closed

Enviado quando o atendimento termina sem agendamento. Permite ao cliente retomar por outros meios e evita contato duplicado com a mesma pessoa.

{
  "event":       "job.closed",
  "event_id":    "evt_4ba7d290",
  "lead_id":     "AES-38-104772",
  "outcome":     "no_answer",
  "attempts":    4,
  "occurred_at": "2026-08-29T18:00:00-03:00"
}

5.4 Idempotência e reenvios

Cada evento leva um event_id único (até 120 caracteres). O AES descarta os repetidos e responde 202 com {"ok": true, "duplicate": true}, de modo que um reenvio nunca produz registro duplicado. Na prática, qualquer 2xx significa aceito.

Um lead_id que o AES não reconhece não gera erro: o evento é aceito com 202 e registrado para conciliação entre as duas equipes.

6. Autenticação

Ambos os sentidos são assinados com HMAC-SHA256 sobre o corpo da requisição, com segredo compartilhado independente por sentido. É o mesmo mecanismo que o AES opera com suas integrações de mensagem e pagamento.

signature = HMAC_SHA256(secret, timestamp + "." + raw_body)
header    = "sha256=" + hex(signature)

6.1 Exemplo resolvido

Verifique a sua implementação com estes valores exatos antes de escrever o resto da integração.

secret     cai_test_5f3a9c21b7e04d8a
timestamp  1787923271
body       {"event":"conversation.message","event_id":"evt_4b81c07f","lead_id":"AES-38-104772"}

signature = HMAC_SHA256(secret, timestamp + "." + body)

X-CAI-Signature: sha256=a893b6460bbb5063910f16ed0b8bbaa44204ea83d9a0ceaa6ac539e0d7bd9f1a

O que se assina é o timestamp, um ponto literal, e o corpo cru tal como viaja: sem reserializar, sem mudar espaços, sem reordenar chaves. É aí que a maioria das implementações perde tempo.

7. Ambientes e catálogo de unidades

Cada implantação tem seu próprio ambiente: um provider_code, um par de credenciais, e um catálogo de valores branch_code com seu nome legível. O AES mantém o catálogo e o atualiza conforme o cliente abre unidades. O Fornecedor associa cada código ao seu número de origem.

Como o roteamento viaja com a tarefa, uma unidade nova não exige mudança de integração de nenhum dos lados. O Fornecedor acrescenta uma linha à sua tabela de correspondência; nada mais se move.

O catálogo, as credenciais e os endereços autorizados são entregues no anexo privado que acompanha esta especificação em cada implantação.

Junto com as credenciais de produção é entregue um par de credenciais de ensaio: apontam para as mesmas URLs e usam o mesmo esquema de assinatura, mas seus dados caem em um espaço de testes isolado. Tudo o que este documento descreve pode ser exercitado de ponta a ponta com elas antes de tocar um dado real, inclusive o recebimento de uma atribuição de exemplo emitida pelo AES.

8. Escopo da versão 1.0

A primeira versão concentra-se no que produz resultado desde o primeiro dia: alcançar o contato, sustentar a conversa e fechar o agendamento. Mantê-la delimitada permite que ambas as partes cheguem à produção rápido e com baixo risco.

8.1 Incluído

• Entrega em tempo real de contatos de todos os canais digitais.
• Roteamento por unidade, resolvido pelo AES e entregue com cada tarefa.
• Registro da conversa completa, nos dois sentidos.
• Agendamentos feitos, remarcados e cancelados.
• Desfechos com motivo, para coordenar o acompanhamento.
• Atribuição de cada resultado ao código do Fornecedor.

8.2 Previsto para versões posteriores

• Canais adicionais, conforme os resultados sejam validados nos já ativos.
• Disponibilidade por unidade, para que o agente ofereça horários já confirmados.
• Eventos posteriores ao agendamento, comparecimento e acompanhamento, para fechar o ciclo de medição.
• Relatórios ampliados, conforme o que ambas as equipes identifiquem como útil na operação.

8.3 Fora do escopo desta interface

A CAI é uma interface de envio ativo nos dois sentidos e não expõe endpoints de leitura. Os números de operação que um Fornecedor precisa para o próprio relatório são entregues pelo AES na periodicidade acordada, conforme a seção 9.

Em setores regulados, os registros que vivem no sistema de operação do cliente — prontuários clínicos, históricos financeiros, documentos de processo — ficam fora desta interface, pois não participam do agendamento. Quando algum dado pontual for genuinamente necessário para uma conversa, ele é avaliado caso a caso com o cliente.

9. Relatórios e dados pessoais

9.1 Relatórios

O AES entrega ao Fornecedor um relatório periódico da sua própria operação: tarefas recebidas, tempo até o primeiro contato, conversas sustentadas, agendamentos gerados e desfechos. A periodicidade e os campos são acordados entre as duas equipes.

Como é o AES que o constrói, o relatório é calculado sobre a mesma base que o cliente vê. A medição do serviço e a do cliente sempre coincidem, e não há conciliação de números entre plataformas.

9.2 Dados pessoais

O Fornecedor atua como operador de dados por conta do cliente: usa as informações para a finalidade desta interface, não as transfere a terceiros, não as emprega para qualquer outro fim incluindo treinamento de modelos, e as elimina ao término da relação contratual.

O AES conserva o registro íntegro de cada conversa como parte das suas obrigações de guarda perante o cliente. Isso também garante continuidade de serviço diante de qualquer incidente em qualquer das duas plataformas.

10. Níveis de serviço

Metas de referência. Ajustadas por implantação conforme o modelo de operação real do Fornecedor.

11. Tornar-se Fornecedor

1. Confirmar o esquema desta especificação.
2. Entregar a documentação do endpoint de tarefas e os IPs de saída.
3. Entregar os números ou identidades de origem disponíveis por região.
4. Trocar segredos no ambiente de testes.
5. Executar testes de ponta a ponta contra um ambiente de testes emitido pelo AES.
6. Piloto em uma única unidade, por duas semanas.
7. Liberação das demais unidades.

Pilotar em uma unidade permite às duas equipes ajustar roteiro, tempos e qualidade de dados com volume controlado antes de abrir o restante.

12. Controle de versões

Este documento descreve a versão 1.0. Campos novos podem ser acrescentados sem aviso prévio e campos não reconhecidos devem ser ignorados. Nenhum campo é removido nem muda de significado dentro da mesma versão maior. Ampliações de escopo são acordadas entre as duas equipes e dão origem a uma nova versão.

Anexo A — Enumerações

A.1 origin.channel

landing_form | contact_form | webchat | whatsapp_button | phone | referral

A.2 brief.intent

book_appointment | pricing_information | service_information |
reschedule | follow_up | other

A.3 author

agent    Agente conversacional do Fornecedor
contact  A pessoa contatada
human    Operador humano do Fornecedor

A.4 outcome

A.5 Formatos

A.6 channel e direction (Interface B)

channel:    whatsapp | webchat | sms | phone | email
direction:  inbound | outbound

Contato

Para incorporar-se como Fornecedor, ou para dúvidas sobre esta especificação, escrever para developers@omb.cloud.