Referência da API do widget externo

URL base

A API do widget é servida a partir do seu Salesforce Site, no caminho /services/apexrest/redaai/chat/v1/:

https://<your-org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1/

O host exato depende do domínio do seu Site. Obtenha-o em Setup › Sites; o script de carregamento que você incorpora no seu site usa o mesmo caminho no atributo data-endpoint.

Autenticação

Toda requisição exige uma chave de API. Envie-a como cabeçalho HTTP ou no corpo da requisição — a API verifica ambos:

O Salesforce Sites pode remover cabeçalhos personalizados em algumas configurações, motivo pelo qual existe a alternativa no corpo. Use qualquer uma delas; a forma no corpo é mais confiável em CDNs e proxies, e é a que o carregador do widget incluído usa por padrão.

Após /init, toda requisição subsequente também precisa do token de sessão retornado por /init:

Veja Gestão de chaves de API para gerar, rotacionar e revogar chaves.

CORS

A API reflete Access-Control-Allow-Origin para chamadas feitas pelo navegador. A definição do agente pode restringir os chamadores por meio do campo Origens permitidas (lista de origens separadas por vírgula); deixe em branco para permitir qualquer origem. Quando definido, apenas as origens da lista têm sucesso; as demais recebem um erro ORIGIN_NOT_ALLOWED.

Alterado na V1.13. A origem agora é obtida do cabeçalho Origin da requisição, não do corpo da requisição. Uma requisição sem o cabeçalho Origin — qualquer chamada servidor a servidor — é, portanto, rejeitada quando Origens permitidas está definido. Veja POST /chat/v1/init.

Endpoints

Quatro endpoints, todos POST. Requisições OPTIONS de pré-verificação (pre-flight) são tratadas automaticamente.

POST /chat/v1/init

Valida a chave de API, verifica a origem do chamador e cria uma sessão. Retorna o token de sessão junto com os metadados do agente que o seu widget precisa para renderizar o estado de boas-vindas.

Corpo da requisição

{
  "clientKey": "<sua chave de API>"
}

Alterado na V1.13. A origem do chamador agora é obtida do cabeçalho Origin da requisição — definido pelo navegador e não substituível por scripts da página. Um campo origin no corpo da requisição ainda é aceito por compatibilidade retroativa, mas é ignorado: um valor fornecido pelo chamador não pode ser usado para restringir o próprio chamador. Widgets que ainda o enviam continuam funcionando sem alterações.

Isso é relevante para chamadores que não são navegadores. Uma requisição servidor a servidor não carrega o cabeçalho Origin, portanto é rejeitada com ORIGIN_NOT_ALLOWED quando o agente tem Origens permitidas definido. Se você chamar essa API a partir do seu próprio backend, deixe Origens permitidas em branco e restrinja o acesso de outra forma. Veja Configurando origens permitidas.

Resposta (200 OK)

{
  "sessionToken":     "<token de sessão opaco>",
  "agentName":        "support-assistant",
  "displayName":      "Support Assistant",
  "welcomeMessage":   "Hi! How can I help today?",
  "mascotImage":      "https://…/mascot.png",
  "maxMessageLength": 2000
}

• sessionToken — envie em toda requisição subsequente.
• agentName — o identificador do agente, útil para análises do lado do cliente.
• displayName — o nome legível a ser exibido no cabeçalho do widget e na seção de boas-vindas.
• welcomeMessage — o texto de boas-vindas externo configurado do agente. String vazia quando não configurado.
• mascotImage — a URL do mascote quando houver um configurado. String vazia quando não houver.
• maxMessageLength — o limite de comprimento para mensagens do usuário, em caracteres.

POST /chat/v1/message

Envia uma única mensagem do usuário ao agente. Retorna a resposta do agente assim que o loop agêntico for concluído.

Corpo da requisição

{
  "clientKey":    "<sua chave de API>",
  "sessionToken": "<from /init>",
  "message":      "What's open on the Acme account?"
}

Mensagens que excedem maxMessageLength (retornado por /init) são rejeitadas com INVALID_INPUT.

Resposta (200 OK)

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

• response — a resposta do agente, incluindo quaisquer marcadores SUGGESTIONS ou ACTION incorporados que o renderizador do widget interpreta.
• creditsUsed — créditos consumidos por esse turno.
• conversationId — o ID do Salesforce do registro de conversa. Útil para referência cruzada com a transcrição da Conversa no Salesforce.
• pendingActions — ações aguardando confirmação do cliente. No canal do widget externo isto está sempre vazio, porque os cartões de confirmação existem apenas no canal interno. Veja POST /chat/v1/action abaixo.
• continuationPending — true quando o agente executou uma ou mais ações neste turno e ainda não narrou o resultado. Chame /chat/v1/continue para obter essa narração.
• continuationDepth — quantos turnos de continuação já foram executados. Devolva-o na próxima chamada a /continue.

POST /chat/v1/action

Executa sob demanda uma ferramenta de Ação específica. Somente ferramentas de Ação atribuídas ao agente e com escopo no canal widget externo são aceitas.

Corpo da requisição

{
  "clientKey":    "<sua chave de API>",
  "sessionToken": "<from /init>",
  "actionTool":   "create_record",
  "params": {
    "object_name":  "Case",
    "field_values": { "Subject": "Issue with login", "…": "…" }
  }
}

Resposta (200 OK)

{
  "success": true,
  "result":  "<tool execution result, JSON-serialised>"
}

O formato de result corresponde ao resultado da ferramenta subjacente. Para ferramentas de ação nativas, isso significa um payload estruturado com pelo menos um indicador success, uma message e (quando aplicável) um recordId.

POST /chat/v1/continue

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

Corpo da requisição

{
  "clientKey":         "<sua chave de API>",
  "sessionToken":      "<de /init>",
  "continuationDepth": 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 trate isto como um laço: continue chamando /continue, devolvendo 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 ela sempre termina.

POST /chat/v1/history

Retorna até 100 mensagens da conversa da sessão, da mais antiga para a mais recente. Útil quando o widget se reconecta após uma atualização e precisa restaurar a conversa visível.

Corpo da requisição

{
  "clientKey":    "<sua chave de API>",
  "sessionToken": "<from /init>"
}

Resposta (200 OK)

{
  "messages": [
    { "role": "user",      "content": "…", "timestamp": "2026-04-25T08:55:12.000Z" },
    { "role": "assistant", "content": "…", "timestamp": "2026-04-25T08:55:14.000Z" }
  ]
}

Respostas de erro

Todos os erros compartilham a mesma forma:

{
  "error": "<localised user-facing message>",
  "code":  "<machine-readable code>"
}

Use code para decisões programáticas no seu cliente; exiba error ao usuário final.

Limites de taxa

Cada chamada passa por vários limitadores de taxa em ordem. Os dois primeiros e o limite de mensagens são definidos por agente na Definição de Agente; o teto diário de créditos é de toda a organização, uma Configuração da plataforma compartilhada por todos os agentes externos, de modo que um único bot movimentado pode esgotar o orçamento do dia para todos. Defini-lo como 0 significa ilimitado — não recomendado em um widget público.

Veja Referência de configurações da plataforma para detalhes sobre o limite diário de crédito.

Ciclo de vida da sessão

• Criação: /init cria uma sessão vinculada ao IP do cliente chamador e à origem validada.
• Validade: as sessões permanecem válidas enquanto estiverem em uso. Atividade em /message, /action ou /history renova a sessão.
• Tempo limite: sessões inativas expiram após os Minutos de tempo limite da sessão definidos no agente (padrão de 30). Chamadas com um token de sessão expirado recebem SESSION_EXPIRED; o widget deve chamar /init novamente.
• Limites rígidos: uma sessão termina quando atinge o Máximo de mensagens por sessão. As chamadas seguintes recebem MAX_MESSAGES até que uma nova sessão seja criada.

Configuração necessária no agente

Vários campos da Definição de Agente moldam o comportamento do widget:

Postura de segurança

• Execução como usuário convidado. A API é executada como o Usuário Convidado do Salesforce Site. As permissões CRUD e FLS do perfil desse usuário determinam o que o agente e as ferramentas podem ler ou gravar.
• Chave de API com escopo em um único agente. Cada agente externo tem sua própria chave; revogue e rotacione por agente sem afetar os demais.
• Origens em lista de permissões. Defina Origens permitidas em todo agente de produção. Em branco significa que qualquer origem pode chamar — conveniente para testes, arriscado em produção.
• Mensagens de erro genéricas. A API nunca reflete erros internos para os clientes. Falhas graves são registradas no Registro de incidentes de IA para investigação do administrador.
• Limite diário de crédito. O Limite diário de crédito externo é o teto de toda a organização que evita que um bot público descontrolado esgote o orçamento de créditos da licença.

Boas práticas

Use o carregador incluído, a menos que tenha um motivo para não fazer isso. O carregador cuida da invalidação de cache, das alternativas de cabeçalho, da renderização de erros e dos atributos de dados de Personalização da interface do widget. Criar seu próprio cliente só faz sentido para chamadores que não são navegadores (aplicativos mobile, integrações de servidor).

Trate code como a fonte da verdade. A string error é localizada para usuários finais e pode mudar entre versões. O code é estável.

Reinicie sessões em SESSION_EXPIRED, não a cada erro. O carregador do widget faz isso; clientes personalizados também deveriam. Não trate RATE_LIMITED ou CREDIT_LIMIT como problemas de sessão — eles exigem recuperações diferentes (espera com recuo e atenção do administrador, respectivamente).

Defina Origens permitidas para todo agente voltado ao público. Deixar em branco em produção remove uma camada de defesa em profundidade.

Acompanhe o limite diário de crédito. É a rede de segurança para bots voltados ao público; ajuste-o após observar o tráfego real.

Mudanças incluídas em 1.16000

O limite horário por agente também é aplicado na última hora UTC do dia. APIs externa e de Comunidade usam um código estável de limite de créditos, para que a resposta HTTP 429 não dependa da mensagem traduzida.

Checklist de atualização do cliente

Perguntas frequentes

Próximos passos

Leia Gestão de chaves de API para a emissão de chaves, ou Referência da API da comunidade para o equivalente no portal autenticado.