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

# Criar Conversa

> Criar uma nova sessão de conversa com um assistente de IA

Este endpoint cria uma nova sessão de conversa com um assistente de IA. Use para iniciar uma sessão de chat baseada em texto através do seu widget web ou aplicação.

### Corpo da Requisição

<ParamField body="assistant_id" type="string" required>
  O UUID do assistente para iniciar a conversa. Deve ser um UUID de assistente válido que existe no sistema.
</ParamField>

<ParamField body="type" type="string" default="widget">
  O tipo de conversa. Valores possíveis:

  * `widget` - Conversa de widget web (padrão, cobrada)
  * `test` - Conversa de teste (grátis, para desenvolvimento)
</ParamField>

<ParamField body="variables" type="object">
  Variáveis personalizadas para passar ao assistente. Essas variáveis podem ser usadas no prompt do sistema e mensagem inicial do assistente usando a sintaxe `{{nome_variavel}}`.

  Casos de uso comuns:

  * Pré-preenchimento de informações do cliente de formulários
  * Passagem de contexto da sua aplicação
  * Personalização do comportamento do assistente por sessão
</ParamField>

### Campos de Resposta

<ResponseField name="status" type="boolean">
  Indica se a requisição foi bem-sucedida
</ResponseField>

<ResponseField name="conversation_id" type="string">
  O identificador UUID único para a conversa criada. Use este ID para requisições de mensagem subsequentes.
</ResponseField>

<ResponseField name="history" type="array">
  O histórico inicial da conversa. Se o assistente tem uma mensagem inicial configurada, ela será incluída aqui.

  <Expandable title="Propriedades do objeto de mensagem">
    <ResponseField name="role" type="string">
      O papel da mensagem: `assistant` ou `user`
    </ResponseField>

    <ResponseField name="content" type="string">
      O conteúdo da mensagem
    </ResponseField>
  </Expandable>
</ResponseField>

### Respostas de Erro

<ResponseField name="status" type="boolean">
  Será `false` quando um erro ocorrer
</ResponseField>

<ResponseField name="error" type="string">
  Mensagem de erro descrevendo o que deu errado. Valores possíveis:

  * `Assistant not found` - O assistant\_id fornecido não existe
  * `Insufficient balance. Please top up your account.` - O saldo da conta do proprietário do assistente está muito baixo
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://suasofia.online/api/conversations" \
    -H "Content-Type: application/json" \
    -d '{
      "assistant_id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "widget",
      "variables": {
        "customer_name": "João Silva",
        "company": "Empresa Acme",
        "source": "pricing_page"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://suasofia.online/api/conversations', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      assistant_id: '550e8400-e29b-41d4-a716-446655440000',
      type: 'widget',
      variables: {
        customer_name: 'João Silva',
        company: 'Empresa Acme',
        source: 'pricing_page'
      }
    })
  });

  const data = await response.json();
  console.log(data.conversation_id);
  ```

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

  response = requests.post(
      'https://suasofia.online/api/conversations',
      json={
          'assistant_id': '550e8400-e29b-41d4-a716-446655440000',
          'type': 'widget',
          'variables': {
              'customer_name': 'João Silva',
              'company': 'Empresa Acme',
              'source': 'pricing_page'
          }
      }
  )

  data = response.json()
  print(data['conversation_id'])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Sucesso theme={null}
  {
    "status": true,
    "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "history": [
      {
        "role": "assistant",
        "content": "Olá João Silva! Bem-vindo ao suporte da Empresa Acme. Como posso ajudar você hoje?"
      }
    ]
  }
  ```

  ```json 200 Sucesso (Sem mensagem inicial) theme={null}
  {
    "status": true,
    "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "history": []
  }
  ```

  ```json 404 Assistente Não Encontrado theme={null}
  {
    "status": false,
    "error": "Assistente não encontrado"
  }
  ```

  ```json 400 Saldo Insuficiente theme={null}
  {
    "status": false,
    "error": "Saldo insuficiente. Por favor, recarregue sua conta."
  }
  ```
</ResponseExample>

## Preços

* **Conversas de widget**: \$0.01 por mensagem do usuário
* **Conversas de teste**: Grátis (para desenvolvimento e testes)

## Próximos Passos

Após criar uma conversa, use o endpoint [Send Message](/api-reference/conversations/send-message) para trocar mensagens com o assistente.