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

# Get First Message

> Retrieve the agent's greeting message to initialize a chat session

## Overview

This endpoint retrieves the agent's first/greeting message that should be displayed when starting a new chat. Use this to initialize your chat UI before the user sends their first message, providing a welcoming experience.

## Authentication

<ParamField header="X-API-Key" type="string" required>
  Your eigi.ai API key. Must be prefixed with `vk_`.
</ParamField>

## Path Parameters

<ParamField path="agent_id" type="string" required>
  The unique identifier of the agent. Example: `68ea2517dbb84c09bae1ba0a`
</ParamField>

## Response

<ResponseField name="session_id" type="string">
  A new session ID created for this chat. Use this for subsequent messages.
</ResponseField>

<ResponseField name="first_message" type="string">
  The agent's greeting/welcome message configured in the agent settings.
</ResponseField>

<ResponseField name="agent_id" type="string">
  The agent ID (same as the request parameter).
</ResponseField>

## Examples

### Get Agent's First Message

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.eigi.ai/v1/public/agents/68ea2517dbb84c09bae1ba0a/first-message" \
    -H "X-API-Key: vk_your_api_key_here"
  ```

  ```python Python theme={null}
  import requests

  agent_id = "68ea2517dbb84c09bae1ba0a"

  response = requests.get(
      f"https://api.eigi.ai/v1/public/agents/{agent_id}/first-message",
      headers={"X-API-Key": "vk_your_api_key_here"}
  )

  data = response.json()
  print(f"Agent says: {data['first_message']}")
  print(f"Session ID: {data['session_id']}")
  ```

  ```javascript JavaScript theme={null}
  const agentId = "68ea2517dbb84c09bae1ba0a";

  const response = await fetch(
    `https://api.eigi.ai/v1/public/agents/${agentId}/first-message`,
    {
      headers: {
        "X-API-Key": "vk_your_api_key_here",
      },
    }
  );

  const data = await response.json();
  console.log(`Agent says: ${data.first_message}`);
  console.log(`Session ID: ${data.session_id}`);
  ```
</CodeGroup>

### Response Example

```json theme={null}
{
  "session_id": "58a6b549-ef07-4a31-86bc-0eb0e026840a",
  "first_message": "Hello! Welcome to Acme Corp support. I'm your AI assistant, ready to help with any questions about our products, services, or your account. How can I assist you today?",
  "agent_id": "68ea2517dbb84c09bae1ba0a"
}
```

## Typical Workflow

Here's how to properly initialize a chat conversation:

<Steps>
  <Step title="Get First Message">
    Call this endpoint when a user opens your chat interface.
  </Step>

  <Step title="Display Greeting">
    Show the `first_message` to the user in your chat UI.
  </Step>

  <Step title="Store Session ID">
    Save the `session_id` for use in subsequent messages.
  </Step>

  <Step title="Continue Chat">
    When the user sends a message, use the stored `session_id` with the chat
    endpoint.
  </Step>
</Steps>

### Complete Chat Flow Example

```javascript JavaScript theme={null}
class ChatClient {
  constructor(apiKey, agentId) {
    this.apiKey = apiKey;
    this.agentId = agentId;
    this.sessionId = null;
    this.messages = [];
  }

  async initialize() {
    // Step 1: Get the agent's greeting
    const response = await fetch(
      `https://api.eigi.ai/v1/public/agents/${this.agentId}/first-message`,
      {
        headers: { "X-API-Key": this.apiKey },
      }
    );

    const data = await response.json();

    // Step 2: Store session and display greeting
    this.sessionId = data.session_id;
    this.messages.push({
      role: "assistant",
      content: data.first_message,
    });

    return data.first_message;
  }

  async sendMessage(userMessage) {
    // Step 3: Send user message with session ID
    this.messages.push({ role: "user", content: userMessage });

    const response = await fetch("https://api.eigi.ai/v1/public/chat", {
      method: "POST",
      headers: {
        "X-API-Key": this.apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        agent_id: this.agentId,
        session_id: this.sessionId,
        message: userMessage,
        streaming: false,
      }),
    });

    const data = await response.json();
    this.messages.push({
      role: "assistant",
      content: data.response,
    });

    return data.response;
  }
}

// Usage
const chat = new ChatClient("vk_your_api_key", "68ea2517dbb84c09bae1ba0a");
const greeting = await chat.initialize();
console.log("Bot:", greeting);

const reply = await chat.sendMessage("I need help with my order");
console.log("Bot:", reply);
```

## Error Responses

| Status Code          | Description                                     |
| -------------------- | ----------------------------------------------- |
| **401 Unauthorized** | Missing, invalid, inactive, or expired API key  |
| **403 Forbidden**    | API key owner doesn't have access to this agent |
| **404 Not Found**    | Agent not found with the given ID               |

```json Example Error Response theme={null}
{
  "detail": "Agent not found"
}
```

## Best Practices

<Tip>
  **Always Initialize First**: Call this endpoint before displaying your chat UI
  to ensure a proper greeting and valid session.
</Tip>

<Tip>
  **Cache When Appropriate**: If you're opening multiple chats to the same
  agent, you can cache the first message content (but not the session ID).
</Tip>

<Tip>
  **Handle Errors Gracefully**: Have a fallback greeting message in case this
  endpoint fails.
</Tip>


## OpenAPI

````yaml GET /v1/public/agents/{agent_id}/first-message
openapi: 3.0.0
info:
  title: eigi.ai API
  description: REST API for managing AI voice agents and conversations
  version: 1.0.0
  contact:
    email: buddy@eigi.ai
    url: https://eigi.ai
servers:
  - url: https://api.eigi.ai
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /v1/public/agents/{agent_id}/first-message:
    get:
      tags:
        - Chat
      summary: Get First Message
      description: Retrieve the agent's greeting message to initialize a chat session
      operationId: getFirstMessage
      parameters:
        - name: agent_id
          in: path
          required: true
          description: The unique agent ID
          schema:
            type: string
          example: 68ea2517dbb84c09bae1ba0a
      responses:
        '200':
          description: Successfully retrieved first message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FirstMessageResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Access denied to agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    FirstMessageResponse:
      type: object
      properties:
        session_id:
          type: string
          description: New session ID for the chat
        first_message:
          type: string
          description: Agent's greeting message
        agent_id:
          type: string
          description: The agent ID
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Error message
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        API key for authentication. Get your API key from the eigi.ai Dashboard
        under Settings → API Keys.

````