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

# Crear conversación

> Crear una nueva conversación programáticamente.

## Endpoint

```
POST /api/v2/conversations
```

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token con tu API key de organización.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Siempre `application/json`
</ParamField>

## Request Body

<ParamField body="channel" type="string" required>
  Canal de origen. Valores: `api`, `dashboard`, `website`, `agent_builder`
</ParamField>

<ParamField body="title" type="string">
  Título descriptivo de la conversación. Si no se proporciona, se genera automáticamente.
</ParamField>

<ParamField body="agentId" type="string">
  ID del agente a vincular con la conversación
</ParamField>

<ParamField body="metadata" type="object">
  Datos personalizados para la conversación
</ParamField>

<ParamField body="initialMessage" type="string">
  Primer mensaje de la conversación (se crea automáticamente como mensaje del usuario)
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://app.horneross.com/api/v2/conversations \
    -H "Authorization: Bearer sk_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Consulta de producto",
      "channel": "api",
      "agentId": "ag_xyz789",
      "metadata": {
        "source": "mi_app",
        "userId": "user_123"
      },
      "initialMessage": "Hola, necesito información sobre precios"
    }'
  ```

  ```javascript JavaScript theme={null}
  async function createConversation(data) {
    const response = await fetch(
      'https://app.horneross.com/api/v2/conversations',
      {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer sk_live_xxx',
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(data),
      }
    );
    return response.json();
  }

  const result = await createConversation({
    channel: 'api',
    agentId: 'ag_xyz789',
    metadata: { source: 'mi_app' },
    initialMessage: 'Hola, necesito ayuda'
  });

  console.log('Conversation created:', result.conversation.id);
  ```

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

  def create_conversation(channel, agent_id=None, title=None, metadata=None, initial_message=None):
      data = {'channel': channel}
      if agent_id:
          data['agentId'] = agent_id
      if title:
          data['title'] = title
      if metadata:
          data['metadata'] = metadata
      if initial_message:
          data['initialMessage'] = initial_message

      response = requests.post(
          'https://app.horneross.com/api/v2/conversations',
          headers={
              'Authorization': 'Bearer sk_live_xxx',
              'Content-Type': 'application/json'
          },
          json=data
      )
      return response.json()

  result = create_conversation(
      channel='api',
      agent_id='ag_xyz789',
      initial_message='Hola, tengo una consulta'
  )
  print(f"Created: {result['conversation']['id']}")
  ```
</RequestExample>

## Response

<ResponseField name="conversation" type="object" required>
  Conversación creada

  <Expandable title="Propiedades de conversation">
    <ResponseField name="conversation.id" type="string" required>
      ID único de la conversación
    </ResponseField>

    <ResponseField name="conversation.title" type="string">
      Título de la conversación
    </ResponseField>

    <ResponseField name="conversation.channel" type="string" required>
      Canal de origen
    </ResponseField>

    <ResponseField name="conversation.status" type="string" required>
      Estado inicial: `UNRESOLVED`
    </ResponseField>

    <ResponseField name="conversation.agentId" type="string">
      ID del agente asociado
    </ResponseField>

    <ResponseField name="conversation.createdAt" type="string">
      Fecha de creación (ISO 8601)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 - Created theme={null}
  {
    "conversation": {
      "id": "conv_new123",
      "title": "Consulta de producto",
      "channel": "api",
      "status": "UNRESOLVED",
      "agentId": "ag_xyz789",
      "createdAt": "2024-01-21T16:00:00Z"
    }
  }
  ```

  ```json 400 - Channel Required theme={null}
  {
    "error": "channel_required"
  }
  ```

  ```json 403 - Limit Exceeded theme={null}
  {
    "error": "conversation_limit_exceeded",
    "message": "Has alcanzado el límite de 10 conversación(es) activa(s) para tu plan. Por favor, resuelve o elimina conversaciones existentes, o actualiza tu plan.",
    "limit": 10,
    "current": 10,
    "plan": "level_1"
  }
  ```
</ResponseExample>