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

# Gerar Resposta da IA

> Gerar uma resposta da IA usando um assistente, identificado por um identificador externo do cliente

Este endpoint gera uma resposta de IA para uma determinada mensagem usando seu assistente configurado. Automaticamente cria ou reutiliza conversas com base no identificador do cliente, tornando-o ideal para integrar respostas de IA em plataformas externas, CRMs ou interfaces de chat personalizadas.

<Info>
  **Limite de Taxa** — Este endpoint é limitado a 5 requisições por minuto por token da API para prevenir abuso.
</Info>

### Corpo da Requisição

<ParamField body="assistant_id" type="integer" required>
  O ID do assistente a ser usado para gerar a resposta. Deve pertencer à sua conta.
</ParamField>

<ParamField body="customer_identifier" type="string" required>
  Um identificador único para o cliente. Usado para manter o contexto da conversa através de múltiplas mensagens.

  Exemplos: número de telefone, endereço de email, ID de contato do CRM, ID de usuário do Facebook.

  Comprimento máximo: 255 caracteres.
</ParamField>

<ParamField body="message" type="string" required>
  A mensagem do cliente a ser respondida.
</ParamField>

<ParamField body="variables" type="object">
  Variáveis de contexto opcionais a serem passadas para o assistente. São mescladas com quaisquer variáveis de conversa existentes.

  Útil para passar dados do cliente, contexto da sessão ou outros metadados.
</ParamField>

### Campos da Resposta

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

<ResponseField name="conversation_id" type="string">
  O UUID da conversa. Use para acompanhar ou referenciar a conversa posteriormente.
</ResponseField>

<ResponseField name="customer_identifier" type="string">
  O identificador do cliente fornecido na requisição
</ResponseField>

<ResponseField name="reply" type="string">
  A resposta gerada pela IA para a mensagem do cliente
</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="Propriedades do objeto de chamada de função">
    <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>

<ResponseField name="ai_disabled" type="boolean">
  Indica se as respostas da IA estão desabilitadas para esta conversa (p. ex., devido a tomada manual)
</ResponseField>

### Respostas de Erro

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

<ResponseField name="error" type="string">
  Mensagem de erro descrevendo o que deu errado
</ResponseField>

<ResponseField name="error_code" type="string">
  Código de erro legível por máquina. Valores possíveis:

  * `ASSISTANT_NOT_FOUND` - O ID do assistente é inválido ou não pertence à sua conta
  * `INSUFFICIENT_BALANCE` - O saldo da sua conta é muito baixo para processar a mensagem
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://suasofia.online/api/user/ai/generate-reply" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "assistant_id": 123,
      "customer_identifier": "+14155551234",
      "message": "Oi, gostaria de agendar um compromisso",
      "variables": {
        "customer_name": "João Silva",
        "source": "whatsapp"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://suasofia.online/api/user/ai/generate-reply', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      assistant_id: 123,
      customer_identifier: '+14155551234',
      message: 'Oi, gostaria de agendar um compromisso',
      variables: {
        customer_name: 'João Silva',
        source: 'whatsapp'
      }
    })
  });

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

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

  response = requests.post(
      'https://suasofia.online/api/user/ai/generate-reply',
      headers={
          'Authorization': 'Bearer YOUR_API_TOKEN',
          'Content-Type': 'application/json'
      },
      json={
          'assistant_id': 123,
          'customer_identifier': '+14155551234',
          'message': 'Oi, gostaria de agendar um compromisso',
          'variables': {
              'customer_name': 'João Silva',
              'source': 'whatsapp'
          }
      }
  )

  data = response.json()
  print(data['reply'])
  ```

  ```php PHP theme={null}
  $response = Http::withToken('YOUR_API_TOKEN')
      ->post('https://suasofia.online/api/user/ai/generate-reply', [
          'assistant_id' => 123,
          'customer_identifier' => '+14155551234',
          'message' => 'Oi, gostaria de agendar um compromisso',
          'variables' => [
              'customer_name' => 'João Silva',
              'source' => 'whatsapp'
          ]
      ]);

  $reply = $response->json()['reply'];
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Sucesso theme={null}
  {
    "success": true,
    "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "customer_identifier": "+14155551234",
    "reply": "Oi João! Ficaria feliz em ajudar você a agendar um compromisso. Qual dia e horário funcionam melhor para você?",
    "function_calls": [],
    "ai_disabled": false
  }
  ```

  ```json 200 Sucesso (Com Chamadas de Função) theme={null}
  {
    "success": true,
    "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "customer_identifier": "+14155551234",
    "reply": "Verifiquei nossa agenda e temos disponibilidade amanhã às 14h e sexta-feira às 10h. Qual funciona melhor para você?",
    "function_calls": [
      {
        "name": "check_availability",
        "arguments": {
          "start_date": "2025-01-08",
          "days": 7
        },
        "result": {
          "slots": ["2025-01-08 14:00", "2025-01-10 10:00"]
        }
      }
    ],
    "ai_disabled": false
  }
  ```

  ```json 404 Assistente Não Encontrado theme={null}
  {
    "success": false,
    "error": "Assistente não encontrado ou não pertence a você",
    "error_code": "ASSISTANT_NOT_FOUND"
  }
  ```

  ```json 402 Saldo Insuficiente theme={null}
  {
    "success": false,
    "error": "Saldo insuficiente. Por favor, recarregue sua conta.",
    "error_code": "INSUFFICIENT_BALANCE"
  }
  ```

  ```json 422 Erro de Validação theme={null}
  {
    "message": "O campo assistant id é obrigatório.",
    "errors": {
      "assistant_id": ["O campo assistant id é obrigatório."]
    }
  }
  ```

  ```json 429 Limite de Taxa Atingido theme={null}
  {
    "message": "Muitas tentativas.",
    "retry_after": 60
  }
  ```
</ResponseExample>

## Casos de Uso

### Respostas de IA Multicanal

Use este endpoint para adicionar respostas de IA a qualquer plataforma de mensagens:

1. Receba uma mensagem do WhatsApp, Facebook, SMS ou qualquer outro canal
2. Chame este endpoint com a mensagem e identificador do cliente
3. Envie a resposta da IA de volta através do canal original

### Integração com CRM

Integre respostas de IA em seu CRM ou helpdesk:

1. Use o ID de contato do CRM como `customer_identifier`
2. Passe dados do cliente como `variables` para respostas personalizadas
3. A conversa persiste através das sessões usando o mesmo identificador

### Interfaces de Chat Personalizadas

Construa sua própria interface de chat alimentada pelo seu assistente Sua SofIA:

1. Gere um identificador único para cada sessão de usuário
2. Envie mensagens através deste endpoint
3. Exiba as respostas da IA em sua interface

## Persistência da Conversa

As conversas são automaticamente persistidas com base na combinação de `assistant_id` e `customer_identifier`:

* **Mesmo identificador**: Mensagens são adicionadas à conversa existente, mantendo o contexto completo
* **Novo identificador**: Uma nova conversa é criada para o cliente
* **Mesclagem de variáveis**: Quando variáveis são fornecidas, elas são mescladas com as variáveis de conversa existentes

## Melhores Práticas

1. **Use identificadores consistentes**: Sempre use o mesmo formato para identificadores de clientes (p. ex., sempre E.164 para números de telefone)
2. **Passe contexto relevante**: Use o campo `variables` para fornecer dados do cliente que ajudem a IA a personalizar as respostas
3. **Trate limites de taxa**: Implemente lógica de retry com backoff exponencial para requisições com limite de taxa
4. **Armazene IDs de conversa**: Salve o `conversation_id` retornado para referência posterior ou debugging
5. **Monitore custos**: Acompanhe o uso para gerenciar custos, especialmente para integrações de alto volume