Skip to main content
POST
/
user
/
ai
/
generate-reply
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"
    }
  }'

{
  "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
}
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.
Limite de Taxa — Este endpoint é limitado a 5 requisições por minuto por token da API para prevenir abuso.

​
Corpo da Requisição

​
assistant_id
integer
required
O ID do assistente a ser usado para gerar a resposta. Deve pertencer à sua conta.
​
customer_identifier
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.
​
message
string
required
A mensagem do cliente a ser respondida.
​
variables
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.

​
Campos da Resposta

​
success
boolean
Indica se a requisição foi bem-sucedida
​
conversation_id
string
O UUID da conversa. Use para acompanhar ou referenciar a conversa posteriormente.
​
customer_identifier
string
O identificador do cliente fornecido na requisição
​
reply
string
A resposta gerada pela IA para a mensagem do cliente
​
function_calls
array
Array de chamadas de função feitas pelo assistente durante o processamento da mensagem. Array vazio se nenhuma função foi chamada.
​
ai_disabled
boolean
Indica se as respostas da IA estão desabilitadas para esta conversa (p. ex., devido a tomada manual)

​
Respostas de Erro

​
success
boolean
Será false quando um erro ocorrer
​
error
string
Mensagem de erro descrevendo o que deu errado
​
error_code
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
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"
    }
  }'

{
  "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
}

​
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