API Pública — Personally Chat

A API do Personally Chat permite integrar seus agentes de IA diretamente em qualquer sistema — aplicativos mobile, sistemas internos, CRMs, chatbots próprios ou qualquer plataforma que consuma HTTP.

Disponível nos planos Pro e Business. O acesso à API requer uma chave de autenticação gerada automaticamente na criação da sua conta.

Base URL: https://personally.ia.br

Formato: JSON

Autenticação: API Key via header

Autenticação

Todas as requisições autenticadas exigem o header x-api-key com sua chave da organização. Encontre sua chave em Dashboard → Configurações → API Key.

POST https://personally.ia.br/api/chat
Content-Type: application/json
x-api-key: pch_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Formato da chave: começa com pch_ seguido de 48 caracteres hexadecimais. Nunca exponha sua chave em código client-side ou repositórios públicos.

Enviar mensagem

POST/api/chat

Envia uma mensagem para um agente e recebe a resposta gerada pela IA. Gerencia automaticamente o histórico da conversa via conversationId.

Parâmetros do body

Campo	Tipo	Obrigatório	Descrição
`agentId`	string	Sim	UUID do agente. Encontrado em Dashboard → Agentes.
`message`	string	Sim	Mensagem enviada pelo usuário.
`visitorId`	string	Sim	Identificador único do visitante. Gere um UUID e persista por sessão.
`conversationId`	string	Não	ID da conversa ativa. Omita na primeira mensagem; use o retornado nas seguintes.
`channel`	string	Não	Canal de origem: web (padrão), whatsapp, instagram ou custom.

Resposta

Resposta HTTP 200 OK em caso de sucesso:

{
  "response": "Olá! Claro, posso te ajudar com isso...",
  "conversationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "typingDelay": 2300
}

Campo	Tipo	Descrição
`response`	string	Texto da resposta gerada pelo agente IA.
`conversationId`	string	ID da conversa. Envie nas próximas mensagens para manter contexto.
`typingDelay`	number	Tempo sugerido de delay (ms) para simular digitação humana.

Códigos de erro

Código	Significado	Como resolver
400	Parâmetros inválidos	Verifique se agentId, message e visitorId estão presentes.
401	API key inválida	Confirme a chave em Dashboard → Configurações.
403	Agente de outra organização	A API key não pertence à organização do agente.
404	Agente não encontrado	Verifique o agentId e se o agente está ativo.
429	Limite de conversas atingido	Faça upgrade de plano ou aguarde o próximo ciclo mensal.
500	Erro interno	Tente novamente. Se persistir, contate o suporte.

Exemplos de integração

JavaScript / TypeScript

async function chat(message: string, conversationId?: string) {
  const res = await fetch('https://personally.ia.br/api/chat', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'pch_sua_chave_aqui',
    },
    body: JSON.stringify({
      agentId: 'uuid-do-seu-agente',
      message,
      visitorId: 'visitor_id_unico_do_usuario',
      conversationId, // omita na primeira mensagem
      channel: 'custom',
    }),
  })

  const data = await res.json()
  return data // { response, conversationId, typingDelay }
}

Python

import requests

def chat(message: str, conversation_id: str = None):
    payload = {
        "agentId": "uuid-do-seu-agente",
        "message": message,
        "visitorId": "visitor_id_unico_do_usuario",
        "channel": "custom",
    }
    if conversation_id:
        payload["conversationId"] = conversation_id

    response = requests.post(
        "https://personally.ia.br/api/chat",
        json=payload,
        headers={
            "Content-Type": "application/json",
            "x-api-key": "pch_sua_chave_aqui",
        }
    )
    return response.json()  # { response, conversationId, typingDelay }

cURL

curl -X POST https://personally.ia.br/api/chat \
  -H "Content-Type: application/json" \
  -H "x-api-key: pch_sua_chave_aqui" \
  -d '{
    "agentId": "uuid-do-seu-agente",
    "message": "Olá, preciso de ajuda",
    "visitorId": "visitor_abc123",
    "channel": "custom"
  }'

Conversa multi-turno (mantendo contexto)

// Primeira mensagem — sem conversationId
const first = await chat("Qual o prazo de entrega?")
// first.conversationId = "abc-123..."

// Segunda mensagem — passa o conversationId para manter contexto
const second = await chat("E para o interior do Paraná?", first.conversationId)
// O agente lembra da pergunta anterior e responde com contexto

Limites por plano

Plano	API pública	Conversas/mês	Excedente
Starter	Não inclusa	500	R$0,30/conversa
Pro	Incluída	2.500	R$0,30/conversa
Business	Incluída	6.000	R$0,30/conversa
Enterprise	Incluída	Sob consulta	Negociável

Cada conversa é contabilizada uma vez, independente do número de trocas de mensagem dentro dela. O limite reinicia todo mês.

← Voltar ao início

Dúvidas? contato@cavaliniinc.com