Integração de canal de mensagens
O que esta página aborda
Este é um padrão de integração horizontal, não um conector para um produto específico. Ele explica:
- Como um Flow criado pelo cliente transforma mensagens recebidas de qualquer sistema de mensagens em conversas da REDA AI
- Como uma ferramenta Apex de saída personalizada permite que o agente envie respostas de volta por esse mesmo sistema
- Como configurar o agente para que ele entenda que está se comunicando por um canal de mensagens, e não pela interface padrão do Salesforce
Conectores específicos — por exemplo, a REDA Connect para WhatsApp/SMS, ou gateways de terceiros — são fornecidos como pacotes de extensão separados. Cada um é construído sobre o padrão descrito aqui.
A ponte de dois lados
Toda integração de mensagens tem duas metades:
| Direção | O que você constrói | O que a REDA AI fornece |
|---|---|---|
| Entrada — a mensagem do usuário chega ao Salesforce | Um Flow disparado por registro ou por evento de plataforma, acionado quando seu aplicativo de mensagens armazena a mensagem recebida no Salesforce. | O invocável de Flow Send Message to REDA AI Agent. O Flow o chama com o texto do usuário e um contexto de registro; o invocável retorna a resposta do agente de forma síncrona. |
| Saída — a resposta do agente sai do Salesforce | Uma ferramenta de Classe Apex personalizada que sabe como publicar uma mensagem por meio do seu sistema de mensagens (REST, Platform Event, callout, ou DML do Salesforce em um objeto do aplicativo de mensagens). | O framework de ferramentas do agente descobre a ferramenta e a invoca durante a conversa. Você escreve o corpo do executor; a plataforma cuida da invocação, validação e auditoria. |
Entrada: da mensagem ao agente
O invocável
A REDA AI expõe uma ação Apex invocável que qualquer Flow pode chamar. Ela recebe a mensagem do usuário e um registro de contexto, e retorna a resposta do agente.
| Entrada | Obrigatório | Finalidade |
|---|---|---|
agentName | Sim | O Agent Id do agente que deve tratar essa mensagem. |
recordId | Sim | Um registro do Salesforce que fornece contexto (por exemplo, o registro de conversa do aplicativo de mensagens, o Contact correspondente ou o registro de negócio relacionado). |
objectName | Sim | Nome de API do objeto do registro de contexto. |
message | Sim | O texto recebido do usuário. |
conversationId | Opcional | Passe o conversationId da resposta anterior para manter o contexto de múltiplos turnos entre mensagens. |
autoExecuteActions | Opcional | Quando true, as ações pendentes do agente são executadas na mesma chamada, em vez de aguardar um cartão de confirmação. |
automatedSource | Opcional | Rótulo em texto livre (por exemplo, o nome do Flow) registrado na conversa para fins de auditoria. |
fileContentVersionId | Opcional | Um Id de ContentVersion quando a mensagem recebida inclui um anexo a ser processado. |
createIncidentOnError | Opcional | Quando true, os erros geram um registro de Registro de incidentes de IA para monitoramento. |
O invocável retorna a resposta do agente de forma síncrona:
| Saída | Finalidade |
|---|---|
success | Booleano — indica se a chamada foi concluída sem erros. |
response | O texto da resposta do agente. É isso que você envia de volta ao usuário pelo seu sistema de mensagens. |
conversationId | Repasse na próxima mensagem recebida para manter o contexto de múltiplos turnos. |
creditsUsed | Créditos consumidos por esse turno. |
actionResultsJson | Resultados em JSON de quaisquer ações executadas automaticamente nesse turno. |
isAsync / asyncRequestId | Para trabalhos pesados, a plataforma pode encaminhar o processamento para modo assíncrono. Quando isAsync é true, a resposta final é entregue após consultar a solicitação assíncrona. |
errorMessage | Preenchido quando success é false. |
Configurando o Flow de entrada
-
Dispare no evento de entrada
A maioria das integrações de mensagens armazena as mensagens recebidas como registros do Salesforce (ou publica um Platform Event). Um Flow disparado por registro nesse objeto — ou um Flow de evento de plataforma nesse evento — é o ponto de entrada.
-
Resolva o registro de contexto
Decida qual registro do Salesforce representa a conversa: o próprio registro do aplicativo de mensagens, o Contact/Lead correspondente, ou um registro de negócio relacionado (Caso, Oportunidade, etc.). Passe seu Id e o nome do objeto ao invocável.
-
Consulte a conversa
Armazene o
conversationIdretornado pela chamada anterior em um campo do registro de conversa (ou do contato). A cada mensagem recebida, recupere-o e repasse-o para que a REDA AI mantenha o contexto de múltiplos turnos. -
Chame o invocável
O invocável é executado de forma síncrona. O Flow aguarda a resposta do agente.
-
Envie a resposta
Pegue o
responseda saída do invocável e publique-o de volta pelo seu sistema de mensagens — geralmente inserindo um registro de mensagem de saída, disparando um Platform Event de saída, ou fazendo um callout ao seu provedor. -
Persista o novo
conversationIdArmazene o
conversationIdmais recente no registro de conversa para que a próxima mensagem recebida continue a mesma thread.
Saída: do agente ao usuário
Para mensagens iniciadas pelo agente — lembretes, acompanhamentos, transmissões, respostas orientadas por ações — construa uma ferramenta de Classe Apex que publica no seu sistema de mensagens. O agente a usa como qualquer outra ferramenta.
O que a ferramenta precisa
- Uma Description clara — é assim que o agente decide quando usá-la. Declare explicitamente que ela envia uma mensagem pelo seu canal e que tipos de mensagem são adequados.
- Um Input Schema que cubra o identificador de destino (telefone, ID de canal, Id de conversa) e o corpo da mensagem, além de quaisquer opções suportadas pelo seu provedor (nome do template, idioma, ID de anexo).
- Uma Category de
Action. Mensagens de saída têm efeitos colaterais, então o agente exibirá um cartão de confirmação por padrão. - Um campo Channels que inclua o canal em que o agente é executado — uma ferramenta fora do canal da conversa nunca carrega.
Dentro do executor
A classe implementa a interface padrão de executor de ferramentas e faz o que for necessário para despachar a mensagem:
- Callout HTTP diretamente à API do provedor de mensagens, ou
- DML no objeto de mensagem de saída do aplicativo de mensagens, ou
- Publicação de um Platform Event ao qual o aplicativo de mensagens está inscrito.
Retorne um Map<String, Object> com success, message e o Id de mensagem do provedor quando disponível. Veja Ferramentas de Classe Apex para o contrato completo do executor.
Configurando o agente
Duas configurações na Definição de Agente são relevantes para integrações de mensagens:
- Channel — defina como
API. Isso informa à plataforma que o agente está sendo acionado por Flow, e não por uma sessão de interface, e controla quais ferramentas e prompts são carregados para o agente. - Auto Execute Actions — considere ativar. Cartões de confirmação não existem em um canal de mensagens; deixe o agente executar ações não destrutivas por conta própria, ou restrinja o conjunto de ferramentas a ferramentas somente leitura e de mensagens de saída.
As ferramentas — incluindo a ferramenta de mensagem de saída que você construiu — precisam estar atribuídas ao agente e ter API em seu escopo de canal. Veja Configuração do agente para a configuração completa do agente.
Arquivos e anexos
Quando uma mensagem recebida inclui um anexo, armazene-o como um ContentVersion no registro de conversa (ou em qualquer registro que o usuário possa ler) e, em seguida, passe seu Id como fileContentVersionId ao invocável. O agente processará o arquivo usando o mesmo mecanismo de qualquer outro canal — veja Processamento de Documentos.
Anexos de saída dependem do provedor de mensagens. A maioria dos provedores aceita uma URL pública ou um Id de mídia; no executor da ferramenta de saída, gere uma URL de ContentDistribution de curta duração ou faça upload do arquivo ao provedor antes do envio.
Respostas assíncronas
Para a maioria das conversas de mensagens, a resposta síncrona é suficiente — a mensagem do usuário chega, o Flow aguarda, o agente responde em segundos. Para processamento pesado de arquivos ou cadeias agênticas longas, a plataforma pode definir isAsync como true e retornar imediatamente com um asyncRequestId.
Quando isso acontece, a integração tem duas opções:
- Enviar imediatamente uma mensagem de indicador de digitação e, em seguida, acompanhar a solicitação assíncrona e publicar a resposta final quando ela for concluída.
- Tratar o resultado assíncrono como uma mensagem de saída separada: um Flow disparado por registro no objeto de solicitação assíncrona, acionado quando a solicitação atinge seu status final, publica a resposta de volta ao usuário.
Segurança e governança
- Escolha o usuário de execução com cuidado. O Flow é executado em algum contexto de usuário — normalmente o usuário de execução do gatilho de entrada. As permissões desse usuário determinam o que as ferramentas podem fazer e quais dados o agente vê. Use um usuário de integração dedicado com um conjunto de permissões restrito quando o sistema de mensagens atender muitos usuários.
- A saída é código seu. A plataforma não aplica sharing ou FLS dentro da sua ferramenta de saída — declare a classe
with sharinge valide os identificadores de destino (não permita que o modelo envie mensagens para um número de telefone arbitrário sem verificações). - Nenhum limitador de taxa externo se aplica a
API. O limitador de taxa do widget atua sobre o tráfego externo/de comunidade; invocações via Flow dependem dos próprios governor limits do Salesforce e de qualquer limitação que você implemente no seu sistema de mensagens. Planeje-se para tráfego de entrada em volume. - Créditos são consumidos por invocação. Cada chamada ao invocável é descontada dos créditos mensais da organização. Se a organização esgotar os créditos, a chamada retorna um erro e a conversa deve recorrer a uma resposta estática.
- Trilha de auditoria. Cada invocação cria um registro de Conversa de IA e de Mensagem de IA; o
automatedSourcena entrada permite marcar conversas com o nome do Flow de origem para fins de filtragem e relatórios.
Boas práticas
Persista o conversationId. Sem ele, cada mensagem recebida parece o início de uma nova conversa, e o agente perde a memória no meio da thread.
Mapeie um registro real do Salesforce como contexto. O agente funciona muito melhor quando sabe com quem está falando. O registro de conversa do seu aplicativo de mensagens, o Contact correspondente, ou um registro de negócio relacionado funcionam — escolha o que tiver o sinal mais rico.
Use um agente dedicado para o canal. Não reutilize o mesmo agente entre a interface interna do Salesforce e um canal de mensagens. Canais diferentes precisam de tom, prompts e conjuntos de ferramentas diferentes.
Restrinja o conjunto de ferramentas. Um agente de canal de mensagens normalmente precisa de ferramentas de leitura e de uma ferramenta de mensagem de saída. Resista à tentação de dar a ele o conjunto completo de ferramentas de ação — não é possível exibir cartões de confirmação em uma thread de chat.
Trate os erros com elegância. Se success for false, publique uma resposta alternativa amigável (“Estou com dificuldades no momento — tente novamente em alguns minutos”) em vez do errorMessage bruto.
Perguntas frequentes
O pacote principal da REDA AI é agnóstico em relação ao sistema de mensagens — ele fornece o invocável de Flow e o framework de ferramentas, não uma integração específica de provedor. Conectores específicos são entregues como pacotes de extensão separados ou construídos pelos clientes usando o padrão descrito nesta página.
Defina o Channel do agente como API. O invocável de Flow é executado sob esse canal, e qualquer ferramenta que o agente deva usar nesse canal precisa incluir API em seu escopo de canal.
A configuração de Channel faz parte do contexto do agente, e você controla a persona, as instruções e o conjunto de ferramentas. Crie um agente dedicado para o canal com um prompt que especifique claramente o estilo de conversa e as restrições (sem tabelas em markdown, sem respostas longas, sem confirmações de ação).
Não — cartões de confirmação são um recurso de interface. Em um canal de mensagens, ative Auto Execute Actions no agente para que ações não destrutivas sejam executadas diretamente, ou restrinja o conjunto de ferramentas a ferramentas somente leitura e à ferramenta de mensagem de saída. Para ações destrutivas, redirecione o usuário para um link da interface do Salesforce em vez de executar a ação no chat.
Armazene o anexo como um ContentVersion vinculado ao registro da conversa e, em seguida, passe seu Id como fileContentVersionId no invocável. O agente o processa por meio do pipeline padrão de Processamento de Documentos.
A plataforma encaminhou o processamento para um job em segundo plano porque o trabalho era pesado demais para ser concluído de forma síncrona. O Flow recebe um asyncRequestId; envie imediatamente uma mensagem de espera e acompanhe a conclusão, ou configure um Flow separado que publique a resposta final quando a solicitação assíncrona atingir seu status final.
Tecnicamente sim — um agente de canal API pode ser invocado por Flows por trás de vários sistemas de mensagens. Na prática, recomendamos um agente por canal; voz, WhatsApp, e-mail e SMS precisam de tom, extensão e conjuntos de ferramentas diferentes, e um agente focado é mais fácil de governar.
Próximos passos
Leia Ferramentas de Classe Apex para o contrato do executor que você implementará no lado de saída, ou Invocar a REDA AI a partir de Flows para saber mais sobre o invocável de entrada.