Skip to main content
POST
/
conversations
curl -X POST "https://suasofia.online/api/conversations" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "widget",
    "variables": {
      "customer_name": "João Silva",
      "company": "Empresa Acme",
      "source": "pricing_page"
    }
  }'

{
  "status": true,
  "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "history": [
    {
      "role": "assistant",
      "content": "Olá João Silva! Bem-vindo ao suporte da Empresa Acme. Como posso ajudar você hoje?"
    }
  ]
}
Este endpoint cria uma nova sessão de conversa com um assistente de IA. Use para iniciar uma sessão de chat baseada em texto através do seu widget web ou aplicação.

​
Corpo da Requisição

​
assistant_id
string
required
O UUID do assistente para iniciar a conversa. Deve ser um UUID de assistente válido que existe no sistema.
​
type
string
default:"widget"
O tipo de conversa. Valores possíveis:
  • widget - Conversa de widget web (padrão, cobrada)
  • test - Conversa de teste (grátis, para desenvolvimento)
​
variables
object
Variáveis personalizadas para passar ao assistente. Essas variáveis podem ser usadas no prompt do sistema e mensagem inicial do assistente usando a sintaxe {{nome_variavel}}.Casos de uso comuns:
  • Pré-preenchimento de informações do cliente de formulários
  • Passagem de contexto da sua aplicação
  • Personalização do comportamento do assistente por sessão

​
Campos de Resposta

​
status
boolean
Indica se a requisição foi bem-sucedida
​
conversation_id
string
O identificador UUID único para a conversa criada. Use este ID para requisições de mensagem subsequentes.
​
history
array
O histórico inicial da conversa. Se o assistente tem uma mensagem inicial configurada, ela será incluída aqui.

​
Respostas de Erro

​
status
boolean
Será false quando um erro ocorrer
​
error
string
Mensagem de erro descrevendo o que deu errado. Valores possíveis:
  • Assistant not found - O assistant_id fornecido não existe
  • Insufficient balance. Please top up your account. - O saldo da conta do proprietário do assistente está muito baixo
curl -X POST "https://suasofia.online/api/conversations" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "widget",
    "variables": {
      "customer_name": "João Silva",
      "company": "Empresa Acme",
      "source": "pricing_page"
    }
  }'

{
  "status": true,
  "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "history": [
    {
      "role": "assistant",
      "content": "Olá João Silva! Bem-vindo ao suporte da Empresa Acme. Como posso ajudar você hoje?"
    }
  ]
}

​
Preços

  • Conversas de widget: $0.01 por mensagem do usuário
  • Conversas de teste: Grátis (para desenvolvimento e testes)

​
Próximos Passos

Após criar uma conversa, use o endpoint Send Message para trocar mensagens com o assistente.