> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/classic-api/core-api/conversations/conversations-starters.md). # Starters 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 {% openapi src="" path="/v1/{organization}/conversation/conversation\_starter" method="post" %} {% endopenapi %} ## Basic Usage Generate starters by providing a service ID, at least one facet, and generation instructions. {% tabs %} {% tab title="cURL" %} ```bash curl --request POST \ --url 'https://api.amigo.ai/v1//conversation/conversation_starter' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "service_id": "", "facets": ["scheduling"], "min_count": 3, "max_count": 5, "generation_instructions": "Generate friendly greeting prompts for users calling about appointment scheduling" }' ``` {% endtab %} {% tab title="Python SDK" %} ```python from amigo_sdk import AmigoClient with AmigoClient() as client: starters = client.conversation.generate_conversation_starters( body={ "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']})") ``` {% endtab %} {% tab title="TypeScript SDK" %} ```typescript import { AmigoClient } from "@amigo-ai/sdk"; const client = new AmigoClient({ /* config */ }); const starters = await client.conversations.generateConversationStarters({ 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})`); }); ``` {% endtab %} {% tab title="Agent Forge CLI" %} ```bash forge conversation starter -s "Service Name" -e [org] \ --instructions "Generate friendly greeting prompts" \ --facet "scheduling" ``` {% endtab %} {% endtabs %} ## Multi-Facet Generation Provide multiple facets to generate starters across different topics. Each starter will be tagged with the facets it relates to. {% tabs %} {% tab title="cURL" %} ```bash curl --request POST \ --url 'https://api.amigo.ai/v1//conversation/conversation_starter' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "service_id": "", "facets": ["billing", "technical support", "account management"], "min_count": 2, "max_count": 3, "generation_instructions": "Generate prompts about common customer concerns" }' ``` {% endtab %} {% tab title="Python SDK" %} ```python from amigo_sdk import AmigoClient with AmigoClient() as client: starters = client.conversation.generate_conversation_starters( body={ "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']})") ``` {% endtab %} {% tab title="TypeScript SDK" %} ```typescript const starters = await client.conversations.generateConversationStarters({ service_id: "", facets: ["billing", "technical support", "account management"], min_count: 2, max_count: 3, generation_instructions: "Generate prompts about common customer concerns", }); ``` {% endtab %} {% tab title="Agent Forge CLI" %} ```bash 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 ``` {% endtab %} {% endtabs %} ## Example Response ```json { "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 {% hint style="info" %} **Rate Limit**: This endpoint is limited to 10 requests per minute. For bulk generation, batch your requests accordingly. {% endhint %} {% hint style="success" %} **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. {% endhint %} ## Related Documentation * [Create Conversations](/developer-guide/classic-api/core-api/conversations/conversations-create.md): use generated starters as `initial_message` values. * [Conversation History](/developer-guide/classic-api/core-api/conversations/conversation-history.md): retrieve past conversations. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.amigo.ai/developer-guide/classic-api/core-api/conversations/conversations-starters.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.