API Docs

Integre os agentes da Riventa.Dev nos seus sistemas via REST API.

API ativav1.0

Início Rápido

Crie uma API Key

Acesse Dashboard → Configurações → API Keys e crie uma nova chave.

Copie o Agent ID

Em Dashboard → Agentes, copie o ID do agente que deseja integrar.

Faça sua primeira chamada

Use o endpoint abaixo com sua chave e o ID do agente.

Autenticação

Todas as chamadas à API requerem autenticação via API key no header Authorization.

Authorization: Bearer creat_sua_chave_aqui

A API key vincula suas chamadas à sua organização. O agente acessado deve pertencer à mesma organização da chave.

Enviar Mensagem

POST/api/chat/sdk

Envia uma mensagem para um agente e recebe a resposta. Suporta conversas contínuas via conversationId.

Parâmetros do Request

Campo	Tipo	Obrigatório	Descrição
agentId	string	sim	ID do agente que receberá a mensagem
message	string	sim	Mensagem do usuário (máx 5000 caracteres)
conversationId	string	não	ID da conversa para continuar um diálogo existente
contact	object	não	Dados do contato para identificação
contact.externalId	string	não	ID do usuário no seu sistema (usado para vincular conversas)
contact.name	string	não	Nome do contato
contact.email	string	não	Email do contato
contact.phone	string	não	Telefone do contato
contact.metadata	object	não	Dados extras em formato chave-valor

Resposta

Campo	Tipo	Descrição
response	string	Resposta gerada pelo agente
conversationId	string	ID da conversa (use para continuar o diálogo)
contactId	string \| null	ID do contato criado ou encontrado

Códigos de Erro

Código	Descrição
400	Parâmetros inválidos (agentId ou message ausentes)
401	API key ausente, inválida ou expirada
403	Agent inativo ou API key sem permissão para este agent
404	Agent não encontrado
429	Limite de requisições atingido (30/min por chave)
500	Erro interno do servidor

Exemplos

JavaScript / TypeScript

const response = await fetch('https://creat.app/api/chat/sdk', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer creat_sua_chave_aqui'
  },
  body: JSON.stringify({
    agentId: 'SEU_AGENT_ID',
    message: 'Olá, preciso de ajuda',
    contact: {
      externalId: 'user-123',
      name: 'João Silva',
      email: 'joao@email.com'
    }
  })
});

const data = await response.json();
console.log(data.response);        // Resposta do agente
console.log(data.conversationId);   // ID para continuar a conversa

Python

import requests

response = requests.post('https://creat.app/api/chat/sdk',
    headers={
        'Authorization': 'Bearer creat_sua_chave_aqui'
    },
    json={
        'agentId': 'SEU_AGENT_ID',
        'message': 'Olá, preciso de ajuda',
        'contact': {
            'externalId': 'user-123',
            'name': 'João Silva'
        }
    }
)

data = response.json()
print(data['response'])

cURL

curl -X POST https://creat.app/api/chat/sdk \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer creat_sua_chave_aqui" \
  -d '{
    "agentId": "SEU_AGENT_ID",
    "message": "Olá, preciso de ajuda"
  }'

Gestão de Contatos

Ao enviar o campo contact.externalId, a API automaticamente vincula as mensagens ao mesmo contato. Isso permite que o agente mantenha contexto e memória entre conversas.

Dica: Use o externalId para mapear seus usuários aos contatos do Riventa.Dev. O agente lembrará das conversas anteriores e personalizará as respostas.

Pronto para integrar?

Crie sua API key e comece a usar em minutos.

Criar API Key JSON Reference