Starters

Generate contextual conversation starter prompts for UI widgets and onboarding flows.

Generate contextually appropriate conversation starters for a service. Starters are short prompts that suggest how a user might begin a conversation. They are useful for populating UI widgets, seeding test scenarios, and onboarding flows.

Overview

The conversation starter endpoint uses the service's agent configuration to generate starter prompts targeted at specific facets (topics). Each generated starter is tagged with the facets it relates to.

Prerequisites

• A valid API key with Conversation:CreateConversation permission
• The service_id for the target service
• Your organization ID

Generate conversation starters for a service

post

/v1/{organization}/conversation/conversation_starter

Generate conversation starters for a service.

Permissions

This endpoint requires the following permissions:

• Conversation:CreateConversation for a hypothetical new conversation created using the same setting.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.

Path parameters

organizationstringRequired

Header parameters

x-mongo-cluster-namestring · nullableOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

service_idstringRequired

The identifier of the service to create a conversation starter for.

Pattern: ^[a-f0-9]{24}$

service_version_set_namestringOptional

The version set of the service to use. If not provided, the release version set is used.

Default: release

facetsstring[] · min: 1Required

The facets that the generated conversation starter should be about. Each generated starter is related to some of these facets.

min_countinteger · max: 10Required

The minimum (inclusive) number of conversation starters to generate.

max_countinteger · max: 10Required

The maximum (inclusive) number of conversation starters to generate.

generation_instructionsstring · min: 1Required

The instruction for the conversation starter generation.

Responses

200

Succeeded.

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

Service not found.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 10 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post/v1/{organization}/conversation/conversation_starter

POST /v1/{organization}/conversation/conversation_starter HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 137

{
  "service_id": "text",
  "service_version_set_name": "release",
  "facets": [
    "text"
  ],
  "min_count": 1,
  "max_count": 1,
  "generation_instructions": "text"
}

{
  "prompts": [
    {
      "prompt": "text",
      "facets": [
        "text"
      ]
    }
  ]
}

Basic Usage

Generate starters by providing a service ID, at least one facet, and generation instructions.

cURL

curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/conversation/conversation_starter' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Content-Type: application/json' \
     --data '{
       "service_id": "<SERVICE-ID>",
       "facets": ["scheduling"],
       "min_count": 3,
       "max_count": 5,
       "generation_instructions": "Generate friendly greeting prompts for users calling about appointment scheduling"
     }'

Python SDK

from amigo_sdk import AmigoClient

with AmigoClient() as client:
    starters = client.conversation.generate_conversation_starters(
        body={
            "service_id": "<SERVICE-ID>",
            "facets": ["scheduling"],
            "min_count": 3,
            "max_count": 5,
            "generation_instructions": "Generate friendly greeting prompts for users calling about appointment scheduling",
        }
    )
    for prompt in starters.get("prompts", []):
        print(f"{prompt['prompt']}  (facets: {prompt['facets']})")

TypeScript SDK

import { AmigoClient } from "@amigo-ai/sdk";

const client = new AmigoClient({ /* config */ });
const starters = await client.conversations.generateConversationStarters({
  service_id: "<SERVICE-ID>",
  facets: ["scheduling"],
  min_count: 3,
  max_count: 5,
  generation_instructions:
    "Generate friendly greeting prompts for users calling about appointment scheduling",
});

starters.prompts?.forEach((p) => {
  console.log(`${p.prompt}  (facets: ${p.facets})`);
});

Agent Forge CLI

forge conversation starter -s "Service Name" -e [org] \
  --instructions "Generate friendly greeting prompts" \
  --facet "scheduling"

Multi-Facet Generation

Provide multiple facets to generate starters across different topics. Each starter will be tagged with the facets it relates to.

cURL

curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/conversation/conversation_starter' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Content-Type: application/json' \
     --data '{
       "service_id": "<SERVICE-ID>",
       "facets": ["billing", "technical support", "account management"],
       "min_count": 2,
       "max_count": 3,
       "generation_instructions": "Generate prompts about common customer concerns"
     }'

Python SDK

from amigo_sdk import AmigoClient

with AmigoClient() as client:
    starters = client.conversation.generate_conversation_starters(
        body={
            "service_id": "<SERVICE-ID>",
            "facets": ["billing", "technical support", "account management"],
            "min_count": 2,
            "max_count": 3,
            "generation_instructions": "Generate prompts about common customer concerns",
        }
    )
    for prompt in starters.get("prompts", []):
        print(f"{prompt['prompt']}  (facets: {prompt['facets']})")

TypeScript SDK

const starters = await client.conversations.generateConversationStarters({
  service_id: "<SERVICE-ID>",
  facets: ["billing", "technical support", "account management"],
  min_count: 2,
  max_count: 3,
  generation_instructions: "Generate prompts about common customer concerns",
});

Agent Forge CLI

forge conversation starter -s "Service Name" -e [org] \
  --instructions "Generate prompts about common customer concerns" \
  --facet "billing" --facet "technical support" --facet "account management" \
  --min-count 2 --max-count 3

Example Response

{
  "prompts": [
    {
      "prompt": "Hello, I noticed my billing cycle changed. Can you help me understand my current charges?",
      "facets": ["billing"]
    },
    {
      "prompt": "Hi, I'm having trouble logging into my account. Can you walk me through the steps?",
      "facets": ["technical support", "account management"]
    },
    {
      "prompt": "I'd like to update my payment method. What options do I have?",
      "facets": ["billing", "account management"]
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
service_id	string	Yes	24-character hex service ID
facets	string[]	Yes (min 1)	Topics the starters should relate to
min_count	integer	Yes	Minimum starters to generate (1-10)
max_count	integer	Yes	Maximum starters to generate (1-10)
generation_instructions	string	Yes	Instructions guiding the generation
service_version_set_name	string	No	Version set to use (default: "release")

Tips

Rate Limit: This endpoint is limited to 10 requests per minute. For bulk generation, batch your requests accordingly.

Best Practices

• Use specific, descriptive facets rather than generic ones (for example, "appointment rescheduling" rather than "general").
• Keep generation_instructions focused on tone and context rather than exact wording.
• Use the --json flag in the CLI to pipe starters into other tools or save to files.

Related Documentation

• Create Conversations: use generated starters as initial_message values.
• Conversation History: retrieve past conversations.