User Suggestions

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.

Required fields

Each profile requires:

id — your identifier for the profile.
gender — one of MAN, WOMAN, TRANS_MAN, TRANSMASCULINE, TRANS_WOMAN, TRANSFEMININE.
firstName or nickname — at least one of the two.

Each message in the history requires:

id — your identifier for the message. We use it to deduplicate.
sender — either USER or PERSONA.
date — the message timestamp, in ISO-8601 format.

Unrecognized field names are ignored silently rather than rejected. If you send birthDate instead of birthdate, or content instead of text, the request may still succeed — but the data you sent is discarded, and the suggestions are generated from an incomplete context. Match the field names exactly.

Example Request (Follow-Up Mode)

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

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.

Getting Started

Platform Features

Best Practices

User Suggestions

How It Works

Modes

Usage

Required fields

Example Request (Follow-Up Mode)

Example Response

​How It Works

​Modes

​Usage

​Required fields

​Example Request (Follow-Up Mode)

​Example Response

How It Works

Modes

Usage

Required fields

Example Request (Follow-Up Mode)

Example Response