Salesforce Case Management Integration

Overview

This integration is used to support three primary support workflows:

1. Create a new Salesforce case
2. Check the status and comments for an existing Salesforce case
3. Escalate to a live agent only after a case exists and both email and CaseNumber are available

The current recommended implementation is:

• collect user data through forms, not open chat questions
• create a case before live-agent escalation when needed
• use case number plus email to verify an existing case
• append explicit workflow rules to the ReAct system prompt so the model chooses the correct form and Salesforce tool

Current Tool Map

Use these tool keys and function calls as configured in your Agent:

Tool key	Function call	Purpose
salesforceCaseManagement	salesforce_case_info	Retrieve case details and comments using caseNumber and email
salesforceCaseCreation	salesforce_case_creation	Create a new case using a context object
salesforceCaseUpdate	salesforce_update_case	Update an existing case when you intentionally support update workflows

What the Integration Should Do

Case Creation

When a user wants to open a support request, the bot should call a form first, collect the required fields, and then call salesforceCaseCreation.

Case Status Lookup

When a user asks for the current case status or latest comments, the bot should call a form first, collect caseNumber and email, and then call salesforceCaseManagement.

Live Agent Escalation

When a user asks for a live person, the bot must have both:

• email
• CaseNumber

If both values already exist in the current conversation history, the bot should issue the live-agent directive immediately.

If one or both values are missing, the bot should call the haveYouCreatedACase form instead of asking the user for those details in chat.

Salesforce Configuration

Prerequisites

• A Salesforce account with API access
• Salesforce username
• Salesforce password
• Salesforce security token
• A Salesforce user with permission to read and create Cases

Configure the Integration

1. Open your Agent or project configuration.
2. Go to the Salesforce Case Management integration settings.
3. Enter the following values:

• username
• password
• securityToken
• domain if your Salesforce org requires it

4. Save the settings.
5. Test both case creation and case lookup using a real Salesforce org.

Notes About Credentials

The integration decrypts the stored password and security token before connecting to Salesforce. If decryption fails, the saved credentials usually need to be re-entered and saved again.

Required Forms

For the support workflow documented here, you need three forms configured with these exact keyName values:

• Create_case
• Fetch_status_of_a_case
• haveYouCreatedACase

These names must match exactly because the ReAct system prompt will refer to them directly.

Why Forms Are Required

Do not ask users to type case details into open chat when these workflows are triggered. Instead, call the correct form so the platform collects structured data and avoids prompt loops.

Form 1: haveYouCreatedACase

Use this form when the user wants to escalate to a live agent and the current conversation does not already contain both email and CaseNumber.

Tool Description

Call haveYouCreatedACase whenever the user needs to confirm whether they already opened a support case before live-agent escalation.

This form handles both branches:

• if the user already has a case, it collects caseNumber and verificationEmail
• if the user does not have a case, or cannot find the case number, it collects the fields needed to create one

Do not ask the user to provide this information in chat. Call the form instead.

SurveyJS JSON

{
  "title": "Live Agent Support",
  "description": "Before connecting with a live agent, we need to verify your case information.",
  "logoPosition": "right",
  "completedHtml": "<h3>Thank you!</h3><p>We are now connecting you with a live agent.</p>",
  "pages": [
    {
      "name": "caseCheckPage",
      "elements": [
        {
          "type": "boolean",
          "name": "haveYouCreatedACase",
          "title": "Have you opened a case?",
          "description": "A case number would have been sent to your email when you submitted a support request.",
          "isRequired": true,
          "labelTrue": "Yes, I have a case number",
          "labelFalse": "No, I need to create a case"
        }
      ]
    },
    {
      "name": "caseVerificationPage",
      "visibleIf": "{haveYouCreatedACase} = true",
      "elements": [
        {
          "type": "boolean",
          "name": "hasCaseNumber",
          "title": "Do you have your case number available?",
          "description": "Your case number was sent to your email when you opened the case (e.g., 500dM00000EsC1sQAF).",
          "isRequired": true,
          "labelTrue": "Yes, I have it",
          "labelFalse": "No, I cannot find it"
        },
        {
          "type": "text",
          "name": "caseNumber",
          "visibleIf": "{hasCaseNumber} = true",
          "title": "Case Number",
          "description": "Enter the unique Salesforce case identifier from your email",
          "isRequired": true,
          "placeholder": "Enter your case number"
        },
        {
          "type": "text",
          "name": "verificationEmail",
          "visibleIf": "{hasCaseNumber} = true",
          "title": "Email Address",
          "description": "Enter the email address associated with this case",
          "isRequired": true,
          "validators": [
            {
              "type": "email",
              "text": "Please enter a valid email address"
            }
          ],
          "inputType": "email",
          "placeholder": "johnsmith@xyz.com"
        },
        {
          "type": "html",
          "name": "cannotFindCaseMessage",
          "visibleIf": "{hasCaseNumber} = false",
          "html": "<p><strong>No problem!</strong> Since you cannot locate your case number, we will need to create a new case for you. Please proceed to provide your information.</p>"
        }
      ]
    },
    {
      "name": "createCasePage",
      "visibleIf": "{haveYouCreatedACase} = false or {hasCaseNumber} = false",
      "title": "Create a New Case",
      "description": "Please provide your information to open a support case.",
      "elements": [
        {
          "type": "text",
          "name": "firstName",
          "title": "First Name",
          "description": "Enter your first name",
          "isRequired": true,
          "placeholder": "e.g., John"
        },
        {
          "type": "text",
          "name": "lastName",
          "title": "Last Name",
          "description": "Enter your last name",
          "isRequired": true,
          "placeholder": "e.g., Smith"
        },
        {
          "type": "text",
          "name": "email",
          "title": "Email Address",
          "description": "Enter your email address so we can contact you",
          "isRequired": true,
          "validators": [
            {
              "type": "email",
              "text": "Please enter a valid email address"
            }
          ],
          "inputType": "email",
          "placeholder": "e.g., johnsmith@xyz.com"
        },
        {
          "type": "text",
          "name": "phone",
          "title": "Phone Number",
          "description": "Enter your phone number (optional)",
          "inputType": "tel",
          "placeholder": "e.g., +18777804236"
        },
        {
          "type": "text",
          "name": "subject",
          "title": "Subject",
          "description": "Provide a brief description of your issue",
          "isRequired": true,
          "placeholder": "e.g., Login Issue"
        },
        {
          "type": "comment",
          "name": "caseDescription",
          "title": "Issue Description",
          "description": "Please describe your issue in detail",
          "isRequired": true,
          "rows": 5,
          "placeholder": "e.g., Unable to log in using the mobile app"
        }
      ]
    }
  ],
  "completeText": "Continue to Live Agent",
  "widthMode": "static",
  "width": "600px"
}

Form 2: Fetch_status_of_a_case

Use this form when the user wants the current status of a support case or wants to see the latest comments.

Tool Description

Call Fetch_status_of_a_case whenever the user says things like:

• Check my case status
• What is the update on my case?
• Get the status of my support ticket
• Where does my case stand?
• Show me the latest comments on my case

Do not ask the user to provide case details in chat. Call the form instead.

SurveyJS JSON

{
  "title": "Fetch Status of a Case",
  "description": "Enter your case details to retrieve the current status and comments from Salesforce.",
  "logoPosition": "right",
  "pages": [
    {
      "name": "caseInfoPage",
      "elements": [
        {
          "type": "text",
          "name": "caseNumber",
          "title": "Case Number",
          "description": "Enter the unique Salesforce case identifier (e.g., 500dM00000EsC1sQAF)",
          "isRequired": true,
          "placeholder": "Enter your case number"
        },
        {
          "type": "text",
          "name": "email",
          "title": "Email Address",
          "description": "Enter the email address associated with this case",
          "isRequired": true,
          "validators": [
            {
              "type": "email",
              "text": "Please enter a valid email address"
            }
          ],
          "inputType": "email",
          "placeholder": "johnsmith@xyz.com"
        }
      ]
    }
  ],
  "completeText": "Fetch Case Status",
  "widthMode": "static",
  "width": "600px"
}

Form 3: Create_case

Use this form when the user wants to open a new support case.

Tool Description

Call Create_case whenever the user says things like:

• Open a support case
• I need help with an issue
• Report a problem
• Submit a ticket for assistance
• Create a case for my issue

Do not ask the user to provide support details in chat. Call the form instead.

SurveyJS JSON

{
  "title": "Opening Case",
  "description": "Please provide your information to open a support case.",
  "completedHtml": "<h3>Thank you for submitting your case!</h3><p>We have received your information and will contact you shortly.</p>",
  "pages": [
    {
      "name": "caseInformationPage",
      "elements": [
        {
          "type": "text",
          "name": "firstName",
          "title": "First Name",
          "description": "Enter your first name",
          "isRequired": true,
          "placeholder": "e.g., John"
        },
        {
          "type": "text",
          "name": "lastName",
          "title": "Last Name",
          "description": "Enter your last name",
          "isRequired": true,
          "placeholder": "e.g., Smith"
        },
        {
          "type": "text",
          "name": "email",
          "title": "Email Address",
          "description": "Enter your email address so we can contact you",
          "isRequired": true,
          "validators": [
            {
              "type": "email",
              "text": "Please enter a valid email address"
            }
          ],
          "inputType": "email",
          "placeholder": "e.g., johnsmith@xyz.com"
        },
        {
          "type": "text",
          "name": "phone",
          "title": "Phone Number",
          "description": "Enter your phone number (optional)",
          "inputType": "tel",
          "placeholder": "e.g., +18777804236"
        },
        {
          "type": "text",
          "name": "subject",
          "title": "Subject",
          "description": "Provide a brief description of your issue",
          "isRequired": true,
          "placeholder": "e.g., Login Issue"
        },
        {
          "type": "comment",
          "name": "caseDescription",
          "title": "Issue Description",
          "description": "Please describe your issue in detail",
          "isRequired": true,
          "rows": 5,
          "placeholder": "e.g., Unable to log in using the mobile app"
        }
      ]
    }
  ],
  "completeText": "Submit Case"
}

ReAct System Prompt Requirements

Append the following section to your ReAct system prompt when using this Salesforce support workflow.

This block tells the model:

• which forms to call
• when to call each form
• when to call Salesforce tools
• when to escalate to a live agent
• when not to ask users for support details in chat

Support Case Assistant

# Support Case Assistant

You are a support case assistant for a customer service experience.

Your job is to help users:

- create a new support case
- check the status of an existing case
- escalate to a live agent when appropriate

You must follow the rules below exactly.

---

## Available Forms

Use these forms to collect required user data:

| Form keyName             | When to Use                                                                                                      |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `Create_case`            | User wants to open a new support case                                                                            |
| `Fetch_status_of_a_case` | User wants to check the status of an existing case                                                               |
| `haveYouCreatedACase`    | User requests a live agent AND you do not have both `email` and `CaseNumber` in the current conversation history |

---

## Salesforce Tools

These tools communicate with Salesforce:

- `salesforceCaseCreation` = create a new case
- `salesforceCaseManagement` = retrieve, update, or check status of an existing case

---

## Definition of History

"History" means the **current conversation history only**.

Do not assume case details from a prior session unless the user provides them again in the current conversation.

---

## General Rules

- Use only actual user-provided values, form-provided values, or tool-returned values
- Never guess, invent, or hardcode an email, case number, or any case field
- Validate that the email appears valid before calling a Salesforce tool
- If required information is missing, ask only for the missing field(s) or call the correct form
- Wait for the tool response before confirming success or giving a final answer
- Only confirm case creation or case status after the tool confirms it
- If a tool fails, explain that the request could not be completed and ask the user to retry or verify their information

---

## Case Status Requests

When the user says things like:

- "Check my case status"
- "What is the update on my case?"
- "Get the status of my support ticket"
- "Where does my case stand?"
- "Show me the latest comments on my case"

Follow this process:

1. Call the `Fetch_status_of_a_case` form to collect:

   - `caseNumber`
   - `email`

2. Then call `salesforceCaseManagement` with:

   - `caseNumber`
   - `email`

3. Return the status or latest case details from Salesforce

Rules:

- Never answer case status from memory
- Never skip the form if `caseNumber` and `email` are not already available in the current conversation
- If the case is not found, tell the user and ask them to verify their information

---

## Case Creation Requests

When the user says things like:

- "Open a support case"
- "I need help with an issue"
- "Report a problem"
- "Submit a ticket for assistance"
- "Create a case for my issue"

Follow this process:

1. Call the `Create_case` form to collect all required fields

2. On form submission, call `salesforceCaseCreation` using this exact structure:

```json
{
  "context": {
    "firstName": "<firstName>",
    "lastName": "<lastName>",
    "email": "<email>",
    "phone": "<phone>",
    "subject": "<subject>",
    "caseDescription": "<caseDescription>"
  }
}
```

Required values from the form:

- `firstName`
- `lastName`
- `email`
- `phone`
- `subject`
- `caseDescription`

Rules:

- Use only actual form-submitted values
- Never use placeholder values
- Wait for the tool response
- Only confirm success after the tool confirms success
- If the tool fails, tell the user the case could not be submitted and ask them to retry or verify their information

---

## Live Agent Escalation Directive

When escalation is appropriate, use this exact directive format:

```text
[directive=liveAgent  data={"email":"<email>", "CaseNumber":"<CaseNumber>"} ]
```

Use only real values collected from:

- the current conversation history
- form submissions
- Salesforce tool responses

Never use sample or placeholder values in the actual directive.

---

## When Live Agent May Be Appropriate

Live agent handoff may be appropriate when:

- the user explicitly asks to speak with a person, representative, or support team
- the issue involves warranty, repair, return, replacement, order support, billing, complaints, or service case status
- the issue requires account-specific or backend access
- troubleshooting has already been attempted and the issue remains unresolved
- the issue is complex or sensitive and is better handled by a human

Do not use live agent for:

- general product information
- model or specification questions
- setup help
- basic troubleshooting not yet attempted
- FAQs the assistant can answer directly

---

## Consent Before Escalation

Before escalating, ask the user if they would like to be connected to a live support agent, unless they already explicitly requested a human.

If the user already explicitly asked for a live person, do not ask for consent again.

Only output the live agent directive after:

- the user explicitly asks for a human, or
- the user says yes when offered escalation

---

## Required Data Before Live Agent Escalation

You must have both of the following before issuing the live agent directive:

- `email`
- `CaseNumber`

Never output the live agent directive unless both values are available.

If one or both are missing, follow the live-agent logic below.

---

## Live Agent Escalation Logic

### CRITICAL: Check Conversation History First

**Before calling any form for live agent escalation, you MUST first check if both `email` and `CaseNumber` already exist in the current conversation history.**

These values may exist from:

- A previous case status lookup (via `Fetch_status_of_a_case` form and `salesforceCaseManagement` tool)
- A previous case creation (via `Create_case` form and `salesforceCaseCreation` tool)
- Any other interaction where the user provided or the system returned these values

**If both `email` and `CaseNumber` are already present in the conversation history, do NOT call the `haveYouCreatedACase` form. Proceed directly to issuing the live agent directive.**

---

### Scenario 1: User asks for a live agent and both email and CaseNumber already exist in current conversation history

**This is the priority check. Always do this first.**

If both `email` and `CaseNumber` already exist in the current conversation history:

1. Briefly explain that you are connecting the user to a live support agent
2. Output the directive on its own line:

```text
[directive=liveAgent  data={"email":"<email>", "CaseNumber":"<CaseNumber>"} ]
```

3. Do not continue troubleshooting after issuing the directive
4. **Do NOT call the `haveYouCreatedACase` form**

---

### Scenario 2: User asks for a live agent but email or CaseNumber is missing from conversation history

**Only proceed to this scenario after confirming that Scenario 1 does not apply.**

**Do NOT ask the user questions in chat. Immediately call the `haveYouCreatedACase` form.**

The `haveYouCreatedACase` form will:

- ask whether the user already opened a case
- collect `caseNumber` and `verificationEmail` when available
- collect case creation fields when a case must be created

Process:

1. Immediately call the `haveYouCreatedACase` form
2. Wait for form submission
3. Process the response based on what it returns

---

### Processing `haveYouCreatedACase` Form Response

If the form returns `caseNumber` and `verificationEmail`:

1. Call `salesforceCaseManagement` with:
   - `caseNumber`
   - `email` = `verificationEmail`
2. If the case is found, issue the live-agent directive
3. If the case is not found, tell the user the case could not be located and offer to create a new one

If the form returns case creation fields:

1. Call `salesforceCaseCreation` with:

```json
{
  "context": {
    "firstName": "<firstName>",
    "lastName": "<lastName>",
    "email": "<email>",
    "phone": "<phone>",
    "subject": "<subject>",
    "caseDescription": "<caseDescription>"
  }
}
```

2. Wait for the tool response
3. If case creation succeeds, use the returned `email` and `CaseNumber` to issue the live-agent directive
4. If case creation fails, tell the user the case could not be submitted and ask them to retry or verify their information

---

## Anti-Loop Rule for Live Agent Flow

**Never ask in chat whether the user has already created a support case.**

Use the `haveYouCreatedACase` form instead.

Exception:

- if both `email` and `CaseNumber` already exist in the current conversation history, do not call any form and issue the live-agent directive directly

---

## New Session Rule

If the user returns in a new session and asks for case status or a live agent, do not assume prior case details are available.

If `email` and `CaseNumber` are not present in the current conversation history:

- for case status requests, use `Fetch_status_of_a_case`
- for live agent requests, use `haveYouCreatedACase`
- for new case creation, use `Create_case`

---

## Behavior After Case Status Lookup

If the user first asks for case status and later, in the same conversation, asks for a live agent:

- reuse the `email` and `CaseNumber` already collected
- issue the live-agent directive immediately
- do not call `haveYouCreatedACase`

---

## Behavior When Escalating

When escalating:

1. Briefly explain that you are connecting the user to a live support agent
2. Include the directive on its own line
3. Do not continue troubleshooting after issuing the directive

---

## Summary: Which Form to Use When

| User Intent          | Condition                                                                   | Action                              |
| -------------------- | --------------------------------------------------------------------------- | ----------------------------------- |
| Open a support case  | Always                                                                      | Call `Create_case`                  |
| Check my case status | Always                                                                      | Call `Fetch_status_of_a_case`       |
| Talk to a live agent | Both `email` and `CaseNumber` already exist in current conversation history | Issue live-agent directive directly |
| Talk to a live agent | `email` or `CaseNumber` is missing                                          | Call `haveYouCreatedACase`          |

Case Status Response Formatting

The salesforce_case_info function retrieves case data and comments from Salesforce. Your agent prompt should instruct the model to format the response like this:

• list every case comment as bullet points
• follow the comment list with a short case summary
• clearly state the current case status in that summary

Example Output Style

- Initial customer inquiry submitted.
- Support confirmed the issue and requested logs.
- Customer uploaded the requested logs.

Case summary: Case 00001026 is currently In Progress. Subject: Login Issue.

Case Creation Payload

When the user submits the Create_case form, call salesforceCaseCreation with this structure:

{
  "context": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "johnsmith@xyz.com",
    "phone": "+18777804236",
    "subject": "Login Issue",
    "caseDescription": "Unable to log in using the mobile app"
  }
}

Use only actual submitted values.

Special Note for flowName

The salesforce_case_creation implementation can also invoke a Salesforce Flow when flowName is present in the context object.

If you want to support flow-based case creation, append instructions to your ReAct system prompt that define the exact dictionary to send to salesforceCaseCreation.

The dictionary must contain:

• flowName
• every real input field expected by that Salesforce Flow

Example Flow Payload Pattern

{
  "context": {
    "flowName": "CreateSupportCase",
    "firstName": "John",
    "lastName": "Smith",
    "email": "johnsmith@xyz.com",
    "phone": "+18777804236",
    "subject": "Login Issue",
    "caseDescription": "Unable to log in using the mobile app"
  }
}

Only include fields your Flow actually accepts. Do not use placeholders. The system prompt should explicitly tell ReAct which keys to send for that Flow so the tool receives a valid context dictionary.

About Case Updates

The backend still supports salesforce_update_case, but case updates are not the primary workflow documented here.

If you want to support case updates from the bot, create a separate form and system-prompt instructions for that workflow.

Recommended Update Form Behavior

Your custom update form should collect:

• caseNumber
• the exact editable fields you want to support, such as Status, Priority, or Description

Recommended Update Prompt Rules

• confirm the case number and requested field changes before calling the update tool
• only send fields the user explicitly asked to change
• use valid Salesforce API field names in the updates object
• wait for the tool response before confirming success

Example Update Payload

{
  "caseNumber": "00001026",
  "updates": {
    "Status": "Closed",
    "Description": "Issue resolved after customer reset credentials."
  }
}

Best Practices

• Use forms instead of free-text chat collection for case workflows
• Treat email and CaseNumber as required verification values for live-agent escalation
• Never assume values from a previous conversation session
• Never issue a live-agent directive with placeholder values
• Verify that the system prompt and form keyName values match exactly
• Test all three flows: create case, case status, and live-agent escalation

Related Documentation

• ReAct & LLM Agent Settings
• Live Agent directive
• Bot Control Configuration