Skip to main content
POST
Este endpoint gera uma resposta de IA para uma mensagem dada usando seu assistente configurado. Ele cria ou reutiliza automaticamente 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 tem um limite de taxa de 5 solicitações por minuto por token de API para prevenir abusos.

Corpo da Solicitaçã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. Isso é usado para manter o contexto da conversa em várias mensagens.Exemplos: número de telefone, endereço de e-mail, ID de contato do CRM, ID de usuário do Facebook.Comprimento máximo: 255 caracteres.
string
required
A mensagem do cliente para a qual responder.
object
Variáveis de contexto opcionais a serem passadas para o assistente. Estas são mescladas com quaisquer variáveis de conversa existentes.Útil para passar dados do cliente, contexto de sessão ou outros metadados.

Campos de Resposta

boolean
Indica se a solicitação foi bem-sucedida
string
O UUID da conversa. Use isso para rastrear ou referenciar a conversa mais tarde.
string
O identificador do cliente fornecido na solicitação
string
A resposta gerada pela IA para a mensagem do cliente
array
Array de chamadas de função feitas pelo assistente ao processar a mensagem. Array vazio se nenhuma função foi chamada.
boolean
Indica se as respostas de IA estão desativadas para esta conversa (por exemplo, devido a uma intervenção 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 o identificador do cliente
  3. Envie a resposta de IA de volta pelo canal original

Integração com CRM

Integre respostas de IA em seu CRM ou helpdesk:
  1. Use o ID de contato do CRM como o customer_identifier
  2. Passe dados do cliente como variables para respostas personalizadas
  3. A conversa persiste entre sessões usando o mesmo identificador

Interfaces de Chat Personalizadas

Construa sua própria interface de chat alimentada pelo seu assistente da 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 de 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 todo o contexto
  • 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 (por exemplo, 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 respostas
  3. Gerencie limites de taxa: Implemente lógica de repetição com retrocesso exponencial para solicitações limitadas por taxa
  4. Armazene IDs de conversa: Salve o conversation_id retornado para referência ou depuração posterior
  5. Monitore custos: Acompanhe o uso para gerenciar custos, especialmente para integrações de alto volume