> ## 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.

# Enviar Mensagem

> Enviar uma mensagem em uma conversa existente e receber a resposta do assistente

Este endpoint envia uma mensagem do usuário para uma conversa existente e retorna a resposta do assistente. O assistente processa a mensagem usando o modelo de IA configurado e quaisquer ferramentas disponíveis.

### Parâmetros de Caminho

<ParamField path="uuid" type="string" required>
  O identificador UUID único da conversa
</ParamField>

### Corpo da Requisição

<ParamField body="message" type="string" required>
  A mensagem do usuário para enviar ao assistente. Comprimento máximo: 2000 caracteres.
</ParamField>

### Campos da Resposta

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

<ResponseField name="message" type="string">
  A resposta do assistente à mensagem do usuário
</ResponseField>

<ResponseField name="function_calls" type="array">
  Array de chamadas de função feitas pelo assistente durante o processamento da mensagem. Array vazio se nenhuma função foi chamada.

  <Expandable title="Function call object properties">
    <ResponseField name="name" type="string">
      O nome da função que foi chamada
    </ResponseField>

    <ResponseField name="arguments" type="object">
      Os argumentos passados para a função
    </ResponseField>

    <ResponseField name="result" type="object">
      O resultado retornado pela função
    </ResponseField>
  </Expandable>
</ResponseField>

### Respostas de Erro

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

<ResponseField name="error" type="string">
  Mensagem de erro. Valores possíveis:

  * `Conversation not found` - O UUID fornecido não corresponde a nenhuma conversa
  * `Insufficient balance. Please top up your account.` - O saldo da conta do proprietário do assistente está muito baixo
  * `Failed to process message: [details]` - Ocorreu um erro durante o processamento da mensagem
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://suasofia.online/api/conversations/7c9e6679-7425-40de-944b-e07fc1f90ae7/messages" \
    -H "Content-Type: application/json" \
    -d '{
      "message": "Gostaria de agendar uma demonstração para a próxima semana"
    }'
  ```

  ```javascript JavaScript theme={null}
  const conversationId = '7c9e6679-7425-40de-944b-e07fc1f90ae7';

  const response = await fetch(
    `https://suasofia.online/api/conversations/${conversationId}/messages`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        message: 'Gostaria de agendar uma demonstração para a próxima semana'
      })
    }
  );

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

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

  conversation_id = '7c9e6679-7425-40de-944b-e07fc1f90ae7'

  response = requests.post(
      f'https://suasofia.online/api/conversations/{conversation_id}/messages',
      json={
          'message': 'Gostaria de agendar uma demonstração para a próxima semana'
      }
  )

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

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "status": true,
    "message": "Ficarei feliz em ajudar você a agendar uma demonstração! Tenho disponibilidade na segunda-feira às 14h, quarta-feira às 10h ou sexta-feira às 15h. Qual horário funciona melhor para você?",
    "function_calls": []
  }
  ```

  ```json 200 Success (With Function Calls) theme={null}
  {
    "status": true,
    "message": "Verifiquei nossa agenda e encontrei vários horários disponíveis para a próxima semana. Posso oferecer segunda-feira às 14h, quarta-feira às 10h ou sexta-feira às 15h. Qual você prefere?",
    "function_calls": [
      {
        "name": "check_calendar_availability",
        "arguments": {
          "start_date": "2025-01-13",
          "end_date": "2025-01-17"
        },
        "result": {
          "available_slots": [
            "2025-01-13 14:00",
            "2025-01-15 10:00",
            "2025-01-17 15:00"
          ]
        }
      }
    ]
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "status": false,
    "error": "Conversation not found"
  }
  ```

  ```json 400 Insufficient Balance theme={null}
  {
    "status": false,
    "error": "Insufficient balance. Please top up your account."
  }
  ```

  ```json 400 Processing Error theme={null}
  {
    "status": false,
    "error": "Failed to process message: Connection timeout"
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The message field is required.",
    "errors": {
      "message": ["The message field is required."]
    }
  }
  ```
</ResponseExample>

## Preços

Cada mensagem do usuário em uma conversa de **widget** custa **\$0.01**. Conversas de teste são gratuitas.

## Chamadas de Função

O assistente pode executar funções durante o processamento de mensagens, tais como:

* **Operações de calendário**: Verificar disponibilidade, agendar compromissos
* **Consultas à base de conhecimento**: Pesquisar documentação ou FAQs
* **Integrações personalizadas**: Chamar seus endpoints de webhook configurados

Os resultados das chamadas de função são incluídos na resposta para que você possa exibir informações relevantes ao usuário ou rastrear ações realizadas.

## Melhores Práticas

1. **Lidar com erros de forma elegante**: Exibir mensagens amigáveis quando ocorrerem erros
2. **Mostrar estados de carregamento**: O assistente pode levar alguns segundos para responder, especialmente ao executar funções
3. **Preservar ID da conversa**: Armazenar o UUID da conversa para permitir que usuários retomem conversas
4. **Respeitar limites de taxa**: Implementar atrasos apropriados entre mensagens se necessário