> ## Documentation Index
> Fetch the complete documentation index at: https://assemblyai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Greeting

> Set the exact words a voice agent speaks when a conversation starts, or omit it to listen first.

The `greeting` is what the agent says at the start of the conversation, spoken aloud. It lives on the agent, set when you [create](/voice-agents/voice-agent-api/create-agent) or [update](/voice-agents/voice-agent-api/manage-agents) it, or inline over the WebSocket via [`session.update`](/voice-agents/voice-agent-api/session-configuration). If omitted, the agent waits silently for the user to speak first.

## Set a greeting

Pass `greeting` as a top-level field alongside the required `name`, `system_prompt`, and `voice`:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://agents.assemblyai.com/v1/agents \
    -H "Authorization: $ASSEMBLYAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Support Assistant",
      "system_prompt": "You are a friendly support agent. Keep replies under two sentences.",
      "voice": { "voice_id": "ivy" },
      "greeting": "Hey, this is Riley from Acme support. What'\''s going on?"
    }'
  ```

  ```python Python theme={null}
  # pip install requests
  import os
  import requests

  resp = requests.post(
      "https://agents.assemblyai.com/v1/agents",
      headers={"Authorization": os.environ["ASSEMBLYAI_API_KEY"]},
      json={
          "name": "Support Assistant",
          "system_prompt": "You are a friendly support agent. Keep replies under two sentences.",
          "voice": {"voice_id": "ivy"},
          "greeting": "Hey, this is Riley from Acme support. What's going on?",
      },
  )
  resp.raise_for_status()
  print(resp.json())
  ```

  ```javascript Node.js theme={null}
  // Node 18+ has fetch built in
  const res = await fetch("https://agents.assemblyai.com/v1/agents", {
    method: "POST",
    headers: {
      Authorization: process.env.ASSEMBLYAI_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Support Assistant",
      system_prompt: "You are a friendly support agent. Keep replies under two sentences.",
      voice: { voice_id: "ivy" },
      greeting: "Hey, this is Riley from Acme support. What's going on?",
    }),
  });
  const data = await res.json();
  console.log(data);
  ```
</CodeGroup>

| Field      | Type           | Required | Notes                                                          |
| ---------- | -------------- | -------- | -------------------------------------------------------------- |
| `greeting` | string \| null | No       | Spoken on connect; sent straight to TTS. Omit to listen first. |

<Note>
  The greeting is sent **straight to the TTS engine**. It is not run through the LLM first. Whatever string you put here is exactly what the user hears, word for word.
</Note>

This has two consequences:

* Don't write a meta-greeting like *"Greet the user warmly and ask how you can help"*. The TTS will literally speak that sentence. Write the exact words you want spoken.
* The system prompt's tone/persona rules do not get applied to the greeting. Match the tone yourself.

Omit `greeting` entirely to have the agent listen first — for an inbound call where the caller speaks first, or when an out-of-band channel (like an IVR menu) already handled the greeting.

## Change the greeting

On a stored agent, change the greeting by updating the agent:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT https://agents.assemblyai.com/v1/agents/$AGENT_ID \
    -H "Authorization: $ASSEMBLYAI_API_KEY" -H "Content-Type: application/json" \
    -d '{ "greeting": "Thanks for calling Acme. What can I do for you?" }'
  ```

  ```python Python theme={null}
  # pip install requests
  import os
  import requests

  resp = requests.put(
      f"https://agents.assemblyai.com/v1/agents/{os.environ['AGENT_ID']}",
      headers={"Authorization": os.environ["ASSEMBLYAI_API_KEY"]},
      json={"greeting": "Thanks for calling Acme. What can I do for you?"},
  )
  resp.raise_for_status()
  print(resp.json())
  ```

  ```javascript Node.js theme={null}
  // Node 18+ has fetch built in
  const res = await fetch(
    `https://agents.assemblyai.com/v1/agents/${process.env.AGENT_ID}`,
    {
      method: "PUT",
      headers: {
        Authorization: process.env.ASSEMBLYAI_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        greeting: "Thanks for calling Acme. What can I do for you?",
      }),
    },
  );
  const data = await res.json();
  console.log(data);
  ```
</CodeGroup>

<Note>
  When you configure an agent **inline** via [`session.update`](/voice-agents/voice-agent-api/session-configuration#mutability-after-sessionready), the greeting is **immutable** after `session.ready`. Set it on your first `session.update`; trying to change it mid-session returns `immutable_field`. This caveat applies only to the inline path, not to updating a stored agent.
</Note>