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, eu gostaria de agendar um horário",
"variables": {
"customer_name": "John Smith",
"source": "whatsapp"
}
}'
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, eu gostaria de agendar um horário',
variables: {
customer_name: 'John Smith',
source: 'whatsapp'
}
})
});
const data = await response.json();
console.log(data.reply);
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, eu gostaria de agendar um horário',
'variables': {
'customer_name': 'John Smith',
'source': 'whatsapp'
}
}
)
data = response.json()
print(data['reply'])
$response = Http::withToken('YOUR_API_TOKEN')
->post('https://suasofia.online/api/user/ai/generate-reply', [
'assistant_id' => 123,
'customer_identifier' => '+14155551234',
'message' => 'Oi, eu gostaria de agendar um horário',
'variables' => [
'customer_name' => 'John Smith',
'source' => 'whatsapp'
]
]);
$reply = $response->json()['reply'];
{
"success": true,
"conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"customer_identifier": "+14155551234",
"reply": "Oi John! Ficarei feliz em ajudá-lo a agendar um horário. Que dia e hora funcionam melhor para você?",
"function_calls": [],
"ai_disabled": false
}
{
"success": true,
"conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"customer_identifier": "+14155551234",
"reply": "Verifiquei nosso calendário e temos disponibilidade amanhã às 14h e na 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
}
{
"success": false,
"error": "Assistente não encontrado ou não pertence a você",
"error_code": "ASSISTANT_NOT_FOUND"
}
{
"success": false,
"error": "Saldo insuficiente. Por favor, recarregue sua conta.",
"error_code": "INSUFFICIENT_BALANCE"
}
{
"message": "O campo ID do assistente é obrigatório.",
"errors": {
"assistant_id": ["O campo ID do assistente é obrigatório."]
}
}
{
"message": "Muitas Tentativas.",
"retry_after": 60
}
AI
Gerar Resposta de IA
Gere uma resposta de IA usando um assistente, identificado por um identificador de cliente externo
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, eu gostaria de agendar um horário",
"variables": {
"customer_name": "John Smith",
"source": "whatsapp"
}
}'
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, eu gostaria de agendar um horário',
variables: {
customer_name: 'John Smith',
source: 'whatsapp'
}
})
});
const data = await response.json();
console.log(data.reply);
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, eu gostaria de agendar um horário',
'variables': {
'customer_name': 'John Smith',
'source': 'whatsapp'
}
}
)
data = response.json()
print(data['reply'])
$response = Http::withToken('YOUR_API_TOKEN')
->post('https://suasofia.online/api/user/ai/generate-reply', [
'assistant_id' => 123,
'customer_identifier' => '+14155551234',
'message' => 'Oi, eu gostaria de agendar um horário',
'variables' => [
'customer_name' => 'John Smith',
'source' => 'whatsapp'
]
]);
$reply = $response->json()['reply'];
{
"success": true,
"conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"customer_identifier": "+14155551234",
"reply": "Oi John! Ficarei feliz em ajudá-lo a agendar um horário. Que dia e hora funcionam melhor para você?",
"function_calls": [],
"ai_disabled": false
}
{
"success": true,
"conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"customer_identifier": "+14155551234",
"reply": "Verifiquei nosso calendário e temos disponibilidade amanhã às 14h e na 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
}
{
"success": false,
"error": "Assistente não encontrado ou não pertence a você",
"error_code": "ASSISTANT_NOT_FOUND"
}
{
"success": false,
"error": "Saldo insuficiente. Por favor, recarregue sua conta.",
"error_code": "INSUFFICIENT_BALANCE"
}
{
"message": "O campo ID do assistente é obrigatório.",
"errors": {
"assistant_id": ["O campo ID do assistente é obrigatório."]
}
}
{
"message": "Muitas Tentativas.",
"retry_after": 60
}
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
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 ocorrerstring
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 contaINSUFFICIENT_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, eu gostaria de agendar um horário",
"variables": {
"customer_name": "John Smith",
"source": "whatsapp"
}
}'
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, eu gostaria de agendar um horário',
variables: {
customer_name: 'John Smith',
source: 'whatsapp'
}
})
});
const data = await response.json();
console.log(data.reply);
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, eu gostaria de agendar um horário',
'variables': {
'customer_name': 'John Smith',
'source': 'whatsapp'
}
}
)
data = response.json()
print(data['reply'])
$response = Http::withToken('YOUR_API_TOKEN')
->post('https://suasofia.online/api/user/ai/generate-reply', [
'assistant_id' => 123,
'customer_identifier' => '+14155551234',
'message' => 'Oi, eu gostaria de agendar um horário',
'variables' => [
'customer_name' => 'John Smith',
'source' => 'whatsapp'
]
]);
$reply = $response->json()['reply'];
{
"success": true,
"conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"customer_identifier": "+14155551234",
"reply": "Oi John! Ficarei feliz em ajudá-lo a agendar um horário. Que dia e hora funcionam melhor para você?",
"function_calls": [],
"ai_disabled": false
}
{
"success": true,
"conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"customer_identifier": "+14155551234",
"reply": "Verifiquei nosso calendário e temos disponibilidade amanhã às 14h e na 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
}
{
"success": false,
"error": "Assistente não encontrado ou não pertence a você",
"error_code": "ASSISTANT_NOT_FOUND"
}
{
"success": false,
"error": "Saldo insuficiente. Por favor, recarregue sua conta.",
"error_code": "INSUFFICIENT_BALANCE"
}
{
"message": "O campo ID do assistente é obrigatório.",
"errors": {
"assistant_id": ["O campo ID do assistente é obrigatório."]
}
}
{
"message": "Muitas Tentativas.",
"retry_after": 60
}
Casos de Uso
Respostas de IA Multicanal
Use este endpoint para adicionar respostas de IA a qualquer plataforma de mensagens:- Receba uma mensagem do WhatsApp, Facebook, SMS ou qualquer outro canal
- Chame este endpoint com a mensagem e o identificador do cliente
- Envie a resposta de IA de volta pelo canal original
Integração com CRM
Integre respostas de IA em seu CRM ou helpdesk:- Use o ID de contato do CRM como o
customer_identifier - Passe dados do cliente como
variablespara respostas personalizadas - 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:- Gere um identificador único para cada sessão de usuário
- Envie mensagens através deste endpoint
- Exiba as respostas de IA em sua interface
Persistência da Conversa
As conversas são automaticamente persistidas com base na combinação deassistant_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
- Use identificadores consistentes: Sempre use o mesmo formato para identificadores de clientes (por exemplo, sempre E.164 para números de telefone)
- Passe contexto relevante: Use o campo
variablespara fornecer dados do cliente que ajudem a IA a personalizar respostas - Gerencie limites de taxa: Implemente lógica de repetição com retrocesso exponencial para solicitações limitadas por taxa
- Armazene IDs de conversa: Salve o
conversation_idretornado para referência ou depuração posterior - Monitore custos: Acompanhe o uso para gerenciar custos, especialmente para integrações de alto volume

