Skip to main content
The User Suggestions endpoint allows you to generate a set of three text suggestions for a User based on the current conversation context. This feature is particularly useful for helping Users break the ice or continue a conversation when they are unsure what to say.

​
How It Works

Unlike the main content generation flow which is asynchronous and uses webhooks, the Suggestions endpoint is synchronous. You send the conversation history and profile information, and you receive the suggestions immediately in the response.

​
Modes

The suggestions generation can operate in two different modes depending on the conversation history:
  • Icebreaker: Triggered when the conversation history is empty. It helps the User start a new conversation with the Persona.
  • Follow-Up: Triggered when there are already messages in the history. It helps the User continue an ongoing discussion.

​
Usage

To generate suggestions, you need to provide:
  • The User Profile: The profile of the User who will receive the suggestions.
  • The Persona Profile: The profile of the Persona the User is interacting with.
  • The Conversation History: The list of recent messages in the conversation.
  • The Language: The language in which the suggestions should be generated.
Check out the Profile Data Type to see all the available fields for the User and Persona profiles.

​
Example Request (Follow-Up Mode)

{
  "userProfile": {
    "id": "user_123",
    "firstName": "John",
    "birthDate": "1990-01-01",
    "gender": "MALE"
  },
  "personaProfile": {
    "id": "persona_456",
    "firstName": "Jane",
    "birthDate": "1992-05-15",
    "gender": "FEMALE"
  },
  "language": "EN",
  "messages": [
    {
      "role": "USER",
      "content": "Hi! I saw your profile and noticed you like hiking.",
      "createdAt": "2023-10-27T10:00:00Z"
    },
    {
      "role": "PERSONA",
      "content": "Hey John! Yes, I love being outdoors. Do you have any favorite trails around here?",
      "createdAt": "2023-10-27T10:05:00Z"
    },
    {
      "role": "USER",
      "content": "I really like the Blue Mountain trail, it has a great view.",
      "createdAt": "2023-10-27T10:07:00Z"
    },
    {
      "role": "PERSONA",
      "content": "Oh I've heard about it! Is it a difficult hike?",
      "createdAt": "2023-10-27T10:10:00Z"
    }
  ]
}

​
Example Response

The API returns an array of three suggestions for the User to send next. 
{
  "suggestions": [
    "It's a bit steep at the beginning, but totally worth it!",
    "Not really, it's quite accessible for beginners.",
    "It's moderate, takes about 3 hours to complete. Do you hike often?"
  ]
}
For a complete list of parameters and data structures, please refer to the Suggestions API Reference.