Skip to main content
POST
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

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

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

Respostas de Erro

boolean
Será false quando um erro ocorrer
string
Mensagem de erro descrevendo o que deu errado
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

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