Referência da API da comunidade

Em que difere da API do widget externo

A API da comunidade e a API do widget externo atendem superfícies diferentes e têm modelos de segurança distintos:

Use esta API quando o chatbot estiver atrás de um login do Salesforce Experience Cloud. Use a API do widget externo quando o chatbot estiver em um site público.

URL Base

Disponibilizada a partir do seu site do Experience Cloud, no caminho /services/apexrest/redaai/chat/community/v1/:

https://<sua-comunidade>.my.site.com/<caminho-do-site>/services/apexrest/redaai/chat/community/v1/

O host exato depende da configuração do seu Experience Cloud. Chamadas feitas de dentro do portal naturalmente usam o cookie de sessão do portal para autenticação.

Autenticação

Não há chave de API. O endpoint confia no cookie de sessão do Experience Cloud para identificar o usuário do portal que está chamando. Duas consequências:

• Chamadas feitas em um contexto convidado (não autenticado) são rejeitadas com AUTH_REQUIRED.
• Chamadas vindas de fora do portal que não carregam o cookie de sessão também são rejeitadas.

É por isso que a API da comunidade é naturalmente de mesma origem: o cookie de sessão padrão do Experience Cloud não acompanha requisições de origem cruzada para o domínio do portal.

Endpoints

Cinco endpoints, todos POST:

POST /chat/community/v1/init

Resolve o agente e retoma a conversa mais recente do usuário do portal com esse agente (quando existe uma dentro do tempo limite de sessão do agente) ou cria uma nova.

Corpo da requisição

{
  "agentName": "support-assistant"
}

Resposta (200 OK)

{
  "conversationId":   "a0Q…",
  "agentName":        "support-assistant",
  "displayName":      "Support Assistant",
  "welcomeMessage":   "Hi! How can I help today?",
  "mascotImage":      "https://…/mascot.png",
  "maxMessageLength": 2000,
  "messages": [
    { "role": "user",      "content": "…", "timestamp": "…" },
    { "role": "assistant", "content": "…", "timestamp": "…" }
  ]
}

Quando a resposta inclui um array messages não vazio, a conversa foi retomada; renderize os turnos anteriores para preservar a continuidade. Caso contrário, a conversa é totalmente nova.

Janela de retomada

A elegibilidade para retomada é regida pelo campo Session Timeout Minutes (Tempo Limite de Sessão em Minutos) da definição do agente (padrão de 30). A plataforma localiza a conversa mais recentemente ativa do usuário do portal com esse agente, verifica se a última atividade está dentro da janela de tempo limite e a retoma, se for o caso.

POST /chat/community/v1/new

Força uma nova conversa mesmo que exista uma recente. Útil para controles de interface do tipo “Começar de novo”.

Corpo da requisição

{
  "agentName": "support-assistant"
}

Resposta (200 OK)

{
  "conversationId":   "a0Q…",
  "agentName":        "support-assistant",
  "displayName":      "Support Assistant",
  "welcomeMessage":   "Hi! How can I help today?",
  "mascotImage":      "…",
  "maxMessageLength": 2000
}

Nenhum array messages é retornado porque a conversa ainda não tem histórico.

POST /chat/community/v1/message

Envia uma única mensagem do usuário para o agente e retorna a resposta.

Corpo da requisição

{
  "conversationId": "<de /init ou /new>",
  "message":        "What's open on my case 00012345?"
}

A plataforma valida que o usuário do portal que está chamando é o proprietário da conversa. O acesso entre usuários diferentes é rejeitado.

Resposta (200 OK)

{
  "response":            "<texto da resposta do agente>",
  "creditsUsed":         1.42,
  "conversationId":      "a0Q…",
  "continuationPending": false,
  "continuationDepth":   0
}

continuationPending é o sinalizador sobre o qual seu cliente precisa agir. Quando o agente executou uma ou mais ações durante este turno, ele retorna true: há um resultado que ainda não foi narrado. Chame /continue para obter essa narração. Ignorar o sinalizador deixa o usuário diante de uma resposta que para antes do resultado do que acabou de acontecer.

POST /chat/community/v1/action

Executa uma ação confirmada. Somente ferramentas de Ação atribuídas ao agente e com escopo no canal Community são aceitas.

Corpo da requisição

{
  "conversationId": "<de /init>",
  "actionTool":     "create_record",
  "params": {
    "object_name":  "Case",
    "field_values": { "Subject": "Issue with login", "…": "…" }
  }
}

Resposta (200 OK)

{
  "success": true,
  "result":  "<resultado da execução da ferramenta, serializado em JSON>"
}

POST /chat/community/v1/continue

Pede ao agente que narre o resultado real das ações que ele executou automaticamente no turno /message anterior. Nenhuma nova mensagem do usuário é enviada. Chame-o sempre que a resposta anterior tiver retornado continuationPending: true.

Corpo da requisição

{
  "conversationId":    "a0Q…",
  "continuationDepth": 0
}

Devolva o continuationDepth que você recebeu na resposta anterior. Omiti-lo é tratado como 0.

Resposta (200 OK)

{
  "response":            "<narração do agente sobre o que aconteceu>",
  "creditsUsed":         0.68,
  "conversationId":      "a0Q…",
  "continuationPending": false,
  "continuationDepth":   1
}

continuationPending continua true se o agente encadeou outra ação enquanto narrava — então isto é um laço, não uma única chamada de acompanhamento. Continue chamando /continue, devolvendo a cada vez o continuationDepth retornado, até que ele volte como false. A configuração Profundidade máxima de continuação do agente limita a cadeia, de modo que o laço sempre termina.

POST /chat/community/v1/history

Retorna as mensagens da conversa para o usuário do portal ativo. Útil quando a página do portal é recarregada e precisa restaurar o fluxo visível.

Corpo da requisição

{
  "conversationId": "a0Q…"
}

Resposta (200 OK)

{
  "messages": [
    { "role": "user",      "content": "…", "timestamp": "…" },
    { "role": "assistant", "content": "…", "timestamp": "…" }
  ]
}

Respostas de Erro

Mesmo formato da API do widget externo:

{
  "error": "<mensagem localizada voltada ao usuário>",
  "code":  "<código legível por máquina>"
}

Limites de Taxa

Mesmos controles da API do widget externo, com duas diferenças:

• Os limites por sessão são rastreados por usuário do portal, não por token de sessão opaco.
• O limite diário de créditos é a configuração de plataforma Limite Diário de Créditos da Comunidade, não o limite Externo.

Para remover completamente o teto diário de créditos, deixe Community Daily Credit Cap em branco ou defina como 0 — ambos significam ilimitado. Ele é deliberadamente uma configuração separada do teto do widget externo, para que um widget público movimentado nunca esgote o orçamento do qual os membros do seu portal dependem.

Propriedade da Conversa

As conversas pertencem ao usuário do portal que as iniciou. A plataforma valida a propriedade em cada chamada /message, /action e /history — chamar com um conversationId pertencente a outro usuário é rejeitado com INVALID_INPUT.

Esse é o limite de segurança que permite que a API da comunidade funcione sem chaves de API: as próprias permissões e a propriedade do usuário do portal governam o que ele pode ver e fazer.

O Contato do usuário do portal é fornecido ao agente automaticamente. Usuários do Experience Cloud são vinculados a um registro de Contato por meio de User.ContactId. Quando /init ou /new criam uma conversa, a REDA AI resolve esse Contato e o armazena como o registro de contexto da conversa, injetando-o no prompt do sistema em cada turno seguinte. Assim, o agente sabe com quem está falando — nome, conta e quaisquer outros campos de Contato que você tenha configurado como contexto — sem que o cliente envie qualquer dado identificador e sem configuração adicional por agente.

Um usuário do portal sem Contato (raro, mas possível em alguns tipos de licença do Experience Cloud) simplesmente obtém uma conversa sem registro de contexto. Nada falha.

Configuração Necessária no Agente

Postura de Segurança

• A autenticação é a do portal. Nenhuma chave de API para emitir, rotacionar ou vazar. Cada chamada herda a sessão do usuário do portal.
• As permissões são as do usuário do portal. As regras de CRUD, FLS e compartilhamento do perfil do usuário do portal governam o que o agente e quaisquer ferramentas podem ler ou gravar — incluindo quais registros eles podem ver no histórico da conversa.
• A propriedade é aplicada em cada chamada. Um usuário do portal não consegue ler as conversas de outro usuário do portal, mesmo que obtenha o ID da conversa.
• O escopo de canal das ferramentas se aplica. Somente ferramentas de Ação cujos Canais incluem Community podem ser usadas aqui.
• O limite diário de créditos é a rede de segurança. O Limite Diário de Créditos da Comunidade impede que um bot do portal fora de controle esgote o orçamento de créditos da licença.
• Mensagens de erro genéricas. Os detalhes de erros internos nunca são reproduzidos na resposta; as falhas são registradas no Registro de incidentes de IA para investigação do administrador.

Boas práticas

Use o componente de ponte de comunidade já disponibilizado. O componente Lightning para o Experience Cloud cuida das chamadas de API, da retomada de sessão e da renderização da interface. Construir um cliente personalizado só faz sentido para contextos fora do portal.

Retome em vez de reiniciar. Chamar /init no início de cada visualização de página é o padrão correto — a plataforma retomará a conversa recente de forma transparente. Reserve /new para controles de interface do tipo “Começar de novo” acionados explicitamente pelo usuário.

Defina um Session Timeout (Tempo Limite de Sessão) sensato. Muito curto e os usuários perdem contexto entre carregamentos de página; muito longo e conversas obsoletas são retomadas quando os usuários pretendiam um novo começo. O padrão de 30 minutos é um ponto de partida razoável.

Monitore o Limite Diário de Créditos da Comunidade. Ele é independente do limite Externo e ajustável conforme o volume de usuários do portal autenticados que você atende.

Confirme o escopo de canal das ferramentas. Uma ferramenta de Ação atribuída apenas a Internal não será acionada por uma chamada do portal — mesmo que o agente esteja configurado para isso.

Revisar a continuidade das conversas

Janela de conversa (horas) em branco passa a usar o padrão da organização, inicialmente 30 minutos. Um valor positivo define a janela do agente; 0 desativa a retomada automática. A correspondência depende do canal: API usa agente e registro; Interno/MCP autenticado usa agente, usuário e contexto de registro relevante. Comunidade usa o ajuste compartilhado em vez do timeout da sessão externa. O chat na página inicial, páginas de aplicativo e barra de utilitários pode retomar conversas elegíveis. IDs explícitos continuam sujeitos aos controles de acesso da rota. Use 0 quando dependia de branco para iniciar outra conversa. As permissões empacotadas também corrigem acesso à continuidade Interna e Comunidade.

Perguntas frequentes

Próximos passos

Leia Configuração do Agente de Comunidade para o passo a passo de implantação, ou Referência da API do widget externo para a contraparte não autenticada.