Skip to main content
Use este guia quando precisar mostrar que o mesmo usuário final pode interagir em dois canais e que ambos os canais produzem logs unificados e auditáveis. O padrão abaixo usa um webhook do WhatsApp como canal um e um aplicativo web como canal dois. Ambos os harnesses enviam o mesmo ID de usuário final X-On-Behalf-Of e ambos gravam eventos de auditoria JSONL indexados pelo mesmo response_id e conversation_id.
Use a mesma chave de API MKA1 em ambos os harnesses. Duas chaves de API diferentes representam dois usuários de API MKA1 diferentes. Usar o mesmo valor de X-On-Behalf-Of não é suficiente se o harness do WhatsApp e o harness web autenticarem com chaves de API diferentes. Para este fluxo de evidência, ambos os canais devem compartilhar a mesma chave de API MKA1 e o mesmo ID de usuário final X-On-Behalf-Of.
Para o padrão de solicitação básico, consulte gerar uma resposta. Se precisar criar ou gerenciar um ID de conversa reutilizável por usuário final, consulte gerenciar conversas.

Arquitetura

Mensagem do usuário final no WhatsApp -> O webhook do WhatsApp recebe a mensagem -> Seu servidor chama mka1.llm.responses.create com store: true -> Seu servidor registra o objeto de resposta armazenada completo e o response_id -> Seu servidor envia a resposta de volta ao WhatsApp -> Seu aplicativo web solicita o mesmo response_id do seu backend -> Seu backend chama mka1.llm.responses.get -> Seu backend registra a recuperação web usando o mesmo response_id e conversation_id
Mantenha sua chave de API no servidor. O navegador deve chamar sua rota de backend, e não a API MKA1 diretamente.

Use um ID de usuário final em ambos os canais

O valor de X-On-Behalf-Of é a chave que vincula os canais no nível do usuário final. Use o mesmo ID estável de usuário final em ambos os harnesses. Você também deve usar a mesma chave de API MKA1 compartilhada em ambos os harnesses. Exemplos:
  • O webhook do WhatsApp mapeia um número de telefone para user_123.
  • A sessão do aplicativo web da mesma pessoa também é resolvida como user_123.
  • Ambos os harnesses autenticam com a mesma chave de API MKA1.
Se o valor de X-On-Behalf-Of mudar entre os canais, os logs deixarão de ser auditáveis como uma única conversa de usuário final. Se a chave de API mudar entre os canais, as solicitações pertencerão a usuários de API MKA1 diferentes, mesmo quando X-On-Behalf-Of corresponder.

Harness do WhatsApp: armazene a resposta e registre-a

Comece com um wrapper de SDK compartilhado que ambos os harnesses usam. Isso mantém a autenticação, a criação de conversas, a recuperação de respostas e a criação de respostas consistentes entre os canais.
Em seguida, use esse wrapper no seu webhook do WhatsApp. Crie a conversa uma vez para o usuário final, reutilize-a entre os turnos e capture o evento de auditoria da resposta armazenada.
Este é o ponto de evidência crítico para o canal um:
  • O WhatsApp é o canal de entrada.
  • A solicitação é armazenada com store: true.
  • O objeto de resposta completo é registrado em um formato aberto.
  • O log inclui response_id, conversation_id e end_user_id.

Harness web: recupere a mesma resposta armazenada

O aplicativo web deve chamar seu próprio backend. Esse backend pode recuperar a mesma resposta com mka1.llm.responses.get e registrar a recuperação como um evento do segundo canal.
Chamada mínima do navegador:
Este é o ponto de evidência crítico para o canal dois:
  • O aplicativo web é um canal separado do WhatsApp.
  • Ele recupera a mesma resposta MKA1 armazenada por response_id.
  • Ele registra essa recuperação no mesmo fluxo de auditoria JSONL.
  • O objeto recuperado ainda carrega a mesma vinculação de usuário final e conversa.

Exportação de auditoria unificada em um formato aberto

Exemplo de exportação:

Requisito de autenticação para logs compartilhados

Para esta demonstração multicanal, todos os itens a seguir devem corresponder entre os harnesses do WhatsApp e web:
  • a mesma chave de API MKA1
  • o mesmo ID de usuário final X-On-Behalf-Of
  • o mesmo response_id armazenado
  • o mesmo conversation_id quando você usar conversas
Se qualquer harness usar uma chave de API diferente, você não estará mais mostrando um contexto compartilhado de usuário de API MKA1 entre os canais.