Solve API Developer Reference

Overview

The Solve API provides programmatic access to our Solve product functionality, allowing customers to build their own bots, automate workflows, and enhance their help center search capabilities.

Solve API Endpoints

1. POST https://app.forethought.ai/solve/api/v1/conversation
2. PUT https://app.forethought.ai/solve/api/v1/conversation/{conversation_id}
3. POST https://app.forethought.ai/solve/api/v1/conversation/{conversation_id}/csat

What is a Conversation ID?

A conversation is a session in which a user and a chatbot interact to address a specific problem, question, or topic. It consists of multiple exchanges, with each participant taking turns to respond to the other's messages. Each new conversation is assigned a unique Conversation ID. The conversation starts with the initial request and ends when there is no activity from either the chatbot or the user for 1 hour.

What are Context Variables?

Context Variable is a variable that holds end user entered information. Whenever the end user fills out a form or selects an option under a button step, we populate the context variable to store their input. For example: you may see a field called output_variable in the widget_components in the response:

{
   "widget_components": [
       {
         "type": "button",
         "message": "<p style=\"\" dir=\"ltr\">please select one branch</p>",
         "buttons": [
           {
             "display_name": "branch 1",
             "value": "15442886_a721_4a02_9b85_9ff7cf7fc051"
           },
           {
             "display_name": "branch 2",
             "value": "824e5122_2e92_46f4_bfd8_a96e1782295b"
           }
         ],
         "output_variable": "27d5459e_5110_42a7_9ce1_5a844230639c"
      }
    ],
   "conversation_id": "CONVERSATION_ID"
}

In this case, you will need to use context variables to pass your input in, for example, if you want to choose branch 1, your next request would be:

{
   "context_variables": {
     "27d5459e_5110_42a7_9ce1_5a844230639c": "15442886_a721_4a02_9b85_9ff7cf7fc051"
   }
}

Endpoints

POST /solve/api/v1/conversation

Description

Initializes a new conversation with a free-form query.

Request Headers

"Authorization": "Bearer {solve-api token}",
"Content-Type": "application/json"

Request Body

{
  "stream": false, // Controls whether streaming is used
  "query": "hello!", // The initial query to start the conversation
  "context_variables": {} // Optional context variables
}

Response

{
  "conversation_id": "CONVERSATION_ID", // Unique identifier for the conversation
  "widget_components": [  // List of widget components
    {
      "type": "text",
      "format": "markdown",
      "message": "Hi there! How can I assist you today?\n"
    }
  ]
}

PUT /solve/api/v1/conversation/{conversation_id}

Description

Updates an existing conversation with a new query or context variables.

Request Headers

"Authorization": "Bearer {solve-api token}",
"Content-Type": "application/json"

Request Body

Note: query and context_variables cannot be None at the same time.

{
  "stream": false, // Controls whether streaming is used
  "query": "thank you", // The query to continue the conversation
  "context_variables": {}, // Context variables to indicate user input
}

Response

{
  "conversation_id": "CONVERSATION_ID",  // Unique identifier for the conversation
  "widget_components": [  // List of widget components
    {
      "type": "text",
      "format": "markdown",
      "message": "You're welcome! If you have any more questions, feel free to ask. Have a great day!\n"
    }
  ]
}

POST /solve/api/v1/conversation/{conversation_id}/csat

Description

Reports the Customer Satisfaction (CSAT) score for a conversation.

Request Headers

"Authorization": "Bearer {solve-api token}",
"Content-Type": "application/json"

Request Body

{
  "rating": 4, // Rating between 1 and 5
  "feedback": "string" // Optional feedback
}

Response

{
  "success": true // Indicates if the CSAT was successfully reported
}

Conversation Functionality

The Solve API supports various workflows, including classic, autoflow, and knowledge retrieval.

1. Initialize Conversation: Call the POST /solve/api/v1/conversation endpoint to start a conversation with a free-form query.
2. Update Conversation: Use the PUT /solve/api/v1/conversation/{conversation_id} endpoint to continue the conversation with additional queries or context variables.
3. Provide CSAT: Report customer satisfaction using the POST /solve/api/v1/conversation/{conversation_id}/csat endpoint.

Example Workflows

Initializing a Conversation

Request

POST /solve/api/v1/conversation

{
  "stream": false,
  "query": "How can I reset my password?",
  "context_variables": {}
}

Response

{
  "conversation_id": "CONVERSATION_ID",
  "widget_components": [
    {
      "type": "text",
      "format": "markdown",
      "message": "To reset your Forethought password, follow these steps:\n"
    },
    {
      "type": "text",
      "format": "markdown",
      "message": "1. Go to [forethought.ai/login](https://www.forethought.ai/login).\n2. Click on \"Forgot password?\" and enter your email address.\n3. Click \"Send reset link.\"\n4. Check your email for the reset link, click it, and set your new password.\n"
    },
    {
      "type": "text",
      "format": "markdown",
      "message": "Need more help with this?\n"
    },
    {
      "type": "text",
      "format": "markdown",
      "message": "Related Articles:\n1. [Troubleshoot & reset](https://www.forethought.ai/en-us/help/reset-forethought)\n2. [Account settings](https://www.forethought.ai/en-us/help/account-settings)"
    }
  ]
}

Updating a Conversation

Request

PUT /solve/api/v1/conversation/{conversation_id

{
  "stream": false,
  "query": "I clicked on the send reset link, but I did not receive any email",
  "context_variables": {}
} 

Response

{
  "conversation_id": "CONVERSATION_ID",
  "widget_components": [
    {
      "type": "text",
      "format": "markdown",
      "message": "If you didn't receive the password reset email from Forethought, here are a few steps to check:\n"
    },
    {
      "type": "text",
      "format": "markdown",
      "message": "- Verify that the email address entered is correct.\n- Check your spam or junk mail folder.\n- Wait a few minutes, as sometimes there can be a delay.\n"
    },
    {
      "type": "text",
      "format": "markdown",
      "message": "If you still don't receive it, try requesting the reset link again.\n"
    },
    {
      "type": "text",
      "format": "markdown",
      "message": "Related Articles:\n1. [Troubleshoot & reset](https://www.forethought.ai/en-us/help/reset-forethought)\n2. [Account settings](https://www.forethought.ai/en-us/help/account-settings)"
    }
  ]
}

Widget Components for Different Step Types

Text step:

{
  "type": "text",
  "format": "html",
  "message": "<p style=\"\" dir=\"ltr\">hi hello</p>"
}

• format: can be html or markdown, indicates the format of the message
• Only Text step has this field, because all other steps by default use html

Button step:

{
  type: 'button',
  message: '<p style="" dir="ltr">button step</p>',
  buttons: [
   {
    display_name: 'branch 1',
    value: '15442886_a721_4a02_9b85_9ff7cf7fc051',
   },
   {
    display_name: 'branch 2',
    value: '824e5122_2e92_46f4_bfd8_a96e1782295b',
  },
 ],
 output_variable: '27d5459e_5110_42a7_9ce1_5a844230639c',
}

• Buttons: an array that contains the branches of the button step
  • display_name: name of the branch
  • value: id of the branch
• We can pass the output_varaible and the value of a branch into the context_variables to indicate which branch is selected. For example, below request indicates that the user selects branch 1.

{
  "context_variables": {
   "27d5459e_5110_42a7_9ce1_5a844230639c": "15442886_a721_4a02_9b85_9ff7cf7fc05
  }
}

Form step:

{
  type: 'form',
  message: '<p style="" dir="ltr">form</p>',
  form_fields: [
   {
    placeholder: 'Age',
    input_type: 'NUMBER',
    output_variable: 'dd387bcf_457b_4a79_9ba8_259b9519be9c',
    list_options: [],
   },
   {
    placeholder: 'Email',
    input_type: 'EMAIL',
    output_variable: '3ea8468a-0721-4c7a-9d96-0bbb0c2f45d3',
    list_options: [],
   },
 ],
};

• One form can collect more than one field from the end user. So
• form_fields: an array of the fields that the form step wants to collect
  • placeholder: name of the form
  • Input_type: type accepted by the form step, can be

"SHORT_TEXT"
"LONG_TEXT"
"EMAIL"
"PHONE_NUMBER"
"NUMBER"
"MULTI_SELECT_LIST"

• List_options: when field is of type MULTI_SELECT_LIST, this field indicates the available options to select from for the context variable
• We can pass the output_variable and the user entered info into the context_variables to store the info entered by the user into the conversation context. Below request indicates the age and the email that the user entered.

{
 "context_variables": {
  "dd387bcf_457b_4a79_9ba8_259b9519be9c": 12,
  "3ea8468a-0721-4c7a-9d96-0bbb0c2f45d3": "test@gamil.com",
 },
}

Image step:

{
  type: 'image',
  images: [
    {
      url: 'URL_TO_THE_IMAGE',
      description: 'DESCRIPTION_OF_THE_IMAGE',
    },
  ],
};

Embed Video step:

{
 "type": "embed",
 "embed_url": "EMBED_URL_OF_THE_VIDEO"
}

Article step:

{
  type: 'article',
  articles: [
    {
      document_id: 'DOCUMENT_ID',
      title: 'TITLE_OF_THE_ARTICLE',
      preview: 'PREVIEW_OF_THE_ARTICLE',
      link: 'LINK_TO_SOURCE_OF_ARTICLE',
      source_type: 'knowledge',
      date_created: '2023-07-24T23:57:40Z',
      date_updated: '2023-07-24T23:57:40Z',
      full_html: 'ARITCLE_CONTENT',
    },
  ],
}

Reporting CSAT

Request

POST /solve/api/v1/conversation/12345/csat

{
 "rating": 5,
 "feedback": "Great service!"
}

Response

{
 "success": true
}

Using Streaming Responses

Solve API supports streaming mode, which can reduce the latency and improve the user experience. Enabling streaming mode is easy, just set stream to True in your request body. API consumer will need to handle streaming responses, refer to these guidelines on how to use the Stream API:

• https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream

Zendesk Ticket Creation

Admins can now use the 'Zendesk Ticket Creation' action in the API channel. Executing this action during a conversation will return a response similar to the following:

{
    "conversation_id": "6b81b9ca-0c18-46d5-8a9e-ad6fa021a80b",
    "widget_components": [
        {
            "type": "zendesk_ticket_creation",
            "ticket_id": "802"
        }
    ]
}