# 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="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/conversation/conversation\_starter" method="post" %}
<https://api.amigo.ai/v1/openapi.json>
{% 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/<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"
     }'
```

{% endtab %}

{% tab title="Python SDK" %}

```python
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']})")
```

{% 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: "<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/<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"
     }'
```

{% endtab %}

{% tab title="Python SDK" %}

```python
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']})")
```

{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
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",
});
```

{% 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 40 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](https://docs.amigo.ai/developer-guide/classic-api/core-api/conversations/conversations-create): use generated starters as `initial_message` values.
* [Conversation History](https://docs.amigo.ai/developer-guide/classic-api/core-api/conversations/conversation-history): retrieve past conversations.