Referencia de la API de Comunidad

En qué se diferencia de la API del widget externo

La API de Comunidad y la API del widget externo atienden superficies distintas y tienen modelos de seguridad diferentes:

Usa esta API cuando el chatbot vive detrás de un inicio de sesión de Salesforce Experience Cloud. Usa la API del widget externo cuando el chatbot está en un sitio web público.

URL base

Se sirve desde tu sitio de Experience Cloud, bajo la ruta /services/apexrest/redaai/chat/community/v1/:

https://<your-community>.my.site.com/<site-path>/services/apexrest/redaai/chat/community/v1/

El host exacto depende de tu configuración de Experience Cloud. Las llamadas hechas desde dentro del portal usan de forma natural la cookie de sesión del portal para la autenticación.

Autenticación

No hay clave de API. El endpoint confía en la cookie de sesión de Experience Cloud para identificar al usuario del portal que hace la llamada. Dos consecuencias:

• Las llamadas desde un contexto de invitado (no autenticado) se rechazan con AUTH_REQUIRED.
• Las llamadas desde fuera del portal que no llevan la cookie de sesión también se rechazan.

Por eso la API de Comunidad es del mismo origen de forma natural: la cookie de sesión estándar de Experience Cloud no acompaña a las solicitudes de origen cruzado hacia el dominio del portal.

Endpoints

Cinco endpoints, todos POST:

POST /chat/community/v1/init

Resuelve el agente y reanuda la conversación más reciente del usuario del portal con ese agente (cuando existe una dentro del tiempo de espera de la sesión del agente) o crea una nueva.

Cuerpo de la solicitud

{
  "agentName": "support-assistant"
}

Respuesta (200 OK)

{
  "conversationId":   "a0Q…",
  "agentName":        "support-assistant",
  "displayName":      "Asistente de soporte",
  "welcomeMessage":   "¡Hola! ¿En qué puedo ayudarte hoy?",
  "mascotImage":      "https://…/mascot.png",
  "maxMessageLength": 2000,
  "messages": [
    { "role": "user",      "content": "…", "timestamp": "…" },
    { "role": "assistant", "content": "…", "timestamp": "…" }
  ]
}

Cuando la respuesta incluye un arreglo messages no vacío, la conversación se reanudó; representa los turnos anteriores para preservar la continuidad. De lo contrario, la conversación es completamente nueva.

Ventana de reanudación

La elegibilidad para reanudar se rige por Minutos de tiempo de espera de la sesión en la definición del agente (predeterminado: 30). La plataforma busca la conversación activa más reciente del usuario del portal con ese agente, comprueba que su última actividad esté dentro de la ventana de tiempo de espera y, de ser así, la reanuda.

POST /chat/community/v1/new

Fuerza una conversación nueva incluso si existe una reciente. Útil para controles de interfaz de tipo “Empezar de nuevo”.

Cuerpo de la solicitud

{
  "agentName": "support-assistant"
}

Respuesta (200 OK)

{
  "conversationId":   "a0Q…",
  "agentName":        "support-assistant",
  "displayName":      "Asistente de soporte",
  "welcomeMessage":   "¡Hola! ¿En qué puedo ayudarte hoy?",
  "mascotImage":      "…",
  "maxMessageLength": 2000
}

No se devuelve ningún arreglo messages porque la conversación aún no tiene historial.

POST /chat/community/v1/message

Envía un único mensaje del usuario al agente y devuelve la respuesta.

Cuerpo de la solicitud

{
  "conversationId": "<de /init o /new>",
  "message":        "¿Qué hay abierto en mi caso 00012345?"
}

La plataforma valida que el usuario del portal que hace la llamada sea el propietario de la conversación. El acceso entre usuarios se rechaza.

Respuesta (200 OK)

{
  "response":            "<texto de respuesta del agente>",
  "creditsUsed":         1.42,
  "conversationId":      "a0Q…",
  "continuationPending": false,
  "continuationDepth":   0
}

continuationPending es el indicador sobre el que tu cliente debe actuar. Cuando el agente ha ejecutado una o más acciones durante este turno, devuelve true: hay un resultado que todavía no ha narrado. Llama a /continue para obtener esa narración. Ignorar el indicador deja al usuario ante una respuesta que se corta antes del resultado de lo que acaba de ocurrir.

POST /chat/community/v1/action

Ejecuta una acción confirmada. Solo se aceptan las herramientas de Acción asignadas al agente y con alcance para el canal de Comunidad.

Cuerpo de la solicitud

{
  "conversationId": "<de /init>",
  "actionTool":     "create_record",
  "params": {
    "object_name":  "Case",
    "field_values": { "Subject": "Problema con el inicio de sesión", "…": "…" }
  }
}

Respuesta (200 OK)

{
  "success": true,
  "result":  "<resultado de la ejecución de la herramienta, serializado en JSON>"
}

POST /chat/community/v1/continue

Pide al agente que narre el resultado real de las acciones que ejecutó automáticamente en el turno /message anterior. No se envía ningún mensaje nuevo del usuario. Llámalo siempre que la respuesta anterior haya devuelto continuationPending: true.

Cuerpo de la solicitud

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

Devuelve el continuationDepth que recibiste en la respuesta anterior. Si lo omites, se trata como 0.

Respuesta (200 OK)

{
  "response":            "<narración del agente sobre lo ocurrido>",
  "creditsUsed":         0.68,
  "conversationId":      "a0Q…",
  "continuationPending": false,
  "continuationDepth":   1
}

continuationPending sigue siendo true si el agente encadenó otra acción mientras narraba, así que esto es un bucle, no una única llamada de seguimiento. Sigue llamando a /continue, devolviendo cada vez el continuationDepth recibido, hasta que vuelva como false. El ajuste Profundidad máxima de continuación del agente acota la cadena, de modo que el bucle siempre termina.

POST /chat/community/v1/history

Devuelve los mensajes de la conversación para el usuario del portal activo. Útil cuando la página del portal se recarga y necesita restaurar el hilo visible.

Cuerpo de la solicitud

{
  "conversationId": "a0Q…"
}

Respuesta (200 OK)

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

Respuestas de error

Con la misma estructura que la API del widget externo:

{
  "error": "<mensaje localizado para el usuario>",
  "code":  "<código legible por máquina>"
}

Límites de tasa

Los mismos controles que la API del widget externo, con dos diferencias:

• Los límites por sesión se registran por cada usuario del portal, no por un token de sesión opaco.
• El límite diario de créditos es la Configuración de la plataforma Límite diario de créditos de la comunidad, no el límite externo.

Para eliminar por completo el tope diario de créditos, deja Community Daily Credit Cap en blanco o ponlo en 0: ambos significan ilimitado. Es deliberadamente un ajuste distinto del tope del widget externo, de modo que un widget público con mucho tráfico nunca pueda agotar el presupuesto del que dependen los miembros de tu portal.

Propiedad de la conversación

Las conversaciones pertenecen al usuario del portal que las inició. La plataforma valida la propiedad en cada llamada a /message, /action e /history: llamar con un conversationId que pertenece a otro usuario se rechaza con INVALID_INPUT.

Este es el límite de seguridad que permite que la API de Comunidad funcione sin claves de API: los propios permisos y la propiedad del usuario del portal rigen lo que puede ver y hacer.

El Contacto del usuario del portal se entrega al agente automáticamente. Los usuarios de Experience Cloud están vinculados a un registro de Contacto mediante User.ContactId. Cuando /init o /new crean una conversación, REDA AI resuelve ese Contacto y lo guarda como el registro de contexto de la conversación, para luego inyectarlo en el prompt del sistema en cada turno posterior. Así, el agente sabe con quién está hablando — nombre, cuenta y cualquier otro campo de Contacto que hayas configurado como contexto — sin que el cliente envíe ningún dato identificativo y sin configuración adicional por agente.

Un usuario del portal sin Contacto (poco frecuente, pero posible en algunos tipos de licencia de Experience Cloud) simplemente obtiene una conversación sin registro de contexto. No falla nada.

Configuración necesaria en el agente

Postura de seguridad

• La autenticación es la del portal. No hay claves de API que emitir, rotar ni filtrar. Cada llamada hereda la sesión del usuario del portal.
• Los permisos son los del usuario del portal. Las reglas de CRUD, FLS y colaboración del perfil del usuario del portal rigen lo que el agente y cualquier herramienta pueden leer o escribir, incluidos los registros que pueden ver en el historial de la conversación.
• La propiedad se aplica en cada llamada. Un usuario del portal no puede leer las conversaciones de otro usuario del portal aunque obtenga el ID de la conversación.
• Se aplica el alcance de canal de las herramientas. Aquí solo se pueden usar las herramientas de Acción cuyos canales incluyan Community.
• El límite diario de créditos es la red de seguridad. El Límite diario de créditos de la comunidad evita que un bot del portal fuera de control agote el presupuesto de la licencia.
• Mensajes de error genéricos. Los detalles internos de los errores nunca se devuelven; las fallas se registran en el Registro de incidentes para que el administrador las investigue.

Prácticas recomendadas

Usa el componente puente de comunidad incluido. El componente Lightning para Experience Cloud se encarga de las llamadas a la API, la reanudación de la sesión y la representación de la interfaz. Crear un cliente personalizado solo tiene sentido para contextos que no son del portal.

Reanuda en lugar de reiniciar. Llamar a /init al comienzo de cada vista de página es el valor predeterminado correcto: la plataforma reanudará la conversación reciente de forma transparente. Reserva /new para los controles explícitos de tipo “Empezar de nuevo” impulsados por el usuario.

Establece un tiempo de espera de la sesión razonable. Si es demasiado corto, los usuarios pierden el contexto entre cargas de página; si es demasiado largo, se reanudan conversaciones obsoletas cuando los usuarios querían empezar de nuevo. El valor predeterminado de 30 minutos es un buen punto de partida.

Vigila el Límite diario de créditos de la comunidad. Es independiente del límite externo y ajustable según el volumen de usuarios autenticados del portal que atiendas.

Confirma el alcance de canal de las herramientas. Una herramienta de Acción que solo está asignada a Internal no se activará desde una llamada del portal, aunque el agente esté configurado para ella.

Revisar la continuidad de conversaciones

Ventana de conversación (horas) vacía utiliza ahora el valor de la organización, inicialmente 30 minutos. Un valor positivo define la ventana del agente; 0 desactiva la reanudación automática. La coincidencia depende del canal: API usa agente y registro; Interno/MCP autenticado usa agente, usuario y contexto de registro pertinente. Comunidad utiliza el ajuste compartido en lugar del tiempo de espera de sesión externa. El chat en inicio, páginas de aplicación y barra de utilidades puede retomar conversaciones válidas. Los identificadores explícitos siguen sujetos al acceso de su ruta. Si dependía de que vacío iniciara una conversación, use 0. También se corrigen permisos empaquetados de continuidad Interna y Comunidad.

Preguntas frecuentes

Próximos pasos

Lee Configuración del agente de Comunidad para conocer el recorrido de implementación, o Referencia de la API del widget externo para la contraparte sin autenticación.