Integração via API HTTP

A API REST do SipPulse AI permite que qualquer backend ou sistema externo crie conversas, envie mensagens e receba respostas de um Agente, oferecendo controle total sobre a interação. Esta página apresenta um guia completo para integrar seus sistemas com um Agente.

1. Autenticação

Todas as requisições à API devem incluir uma chave de API no cabeçalho. Você pode gerar e gerenciar suas chaves em Configurações → API Keys.

http

api-key: <SUA_API_KEY>
Content-Type: application/json

2. Conceitos Fundamentais

Termo	Descrição
Agente	A entidade de IA que você cria e configura na plataforma SipPulse AI. Cada Agente possui um `agent_id` único.
Thread	Representa uma sessão de conversa contínua entre um usuário final e um Agente. Ela armazena o histórico de mensagens e o contexto da conversa.

3. Fluxo de Conversa Essencial

O ciclo de vida de uma interação via API geralmente segue estes passos:

Criar uma Thread: Inicia uma nova conversa para um Agente.
Enviar Mensagens: Interage com o Agente dentro da Thread criada.
Consultar Thread: Acessa histórico e dados da conversa.
Encerrar a Thread: Finaliza a conversa de forma controlada.

3.1. Criar uma Conversa (Thread)

Para iniciar uma conversa, envie uma requisição POST para o endpoint /threads. Isso cria um espaço isolado para a interação, que manterá o histórico e o contexto.

Endpoint: POST /threads

bash

curl -X POST https://api.sippulse.ai/threads \
 -H "api-key: <SUA_API_KEY>" \
 -d '{
  "agent_id": "agt_0123456789abcdef",
  "uid": "user-session-xyz-123",
  "vars": {
    "user_name": "Pedro",
    "plan_type": "Premium"
  },
  "additional_instructions": "O usuário está na página de checkout. Seja breve e direto."
}'

Parâmetros do Corpo:

Campo	Obrigatório	Descrição
`agent_id`	Sim	O ID do Agente que irá conduzir a conversa. Você pode copiar este ID na tela de listagem de Agentes na plataforma SipPulse AI.
`uid`	Não	Um identificador único definido por você. Caso: Se você precisa iniciar uma interação sem antes esperar a resposta da criação da thread, pode definir seu próprio ID. Depois, nas chamadas `/run` ou `/stream`, você pode usar este `uid` em vez do `id` gerado pela SipPulse (`thr_...`). Atenção: O `uid` deve ser globalmente único. Tentar criar uma thread com um `uid` que já existe resultará em um erro `409 Conflict`.
`vars`	Não	Um objeto (dicionário) para preencher variáveis dinâmicas nas instruções do seu Agente. Útil para personalizar a interação com dados do usuário.
`additional_instructions`	Não	Instruções de texto que são adicionadas ao prompt do sistema apenas para esta thread específica, sem alterar as instruções globais do Agente.

Resposta:

json

{
  "id": "thr_01HZYB2B9XFT1TD...", // ID gerado pela SipPulse AI
  "agent_id": "agt_0123456789abcdef",
  "uid": "user-session-xyz-123",
  "status": "active",
  // ... outros campos
}

3.2. Enviar Mensagens

Após criar a thread, você pode enviar mensagens usando o id da thread (ou o uid que você definiu).

Modo Síncrono (`/run`)

Ideal para cenários de backend onde você espera a resposta completa do Agente antes de continuar. Neste modo, todos os processos internos (chamadas de ferramentas, RAG, etc.) ficam ocultos, e você recebe apenas a resposta final.

Endpoint: POST /threads/{thread_id}/run

bash

curl -X POST https://api.sippulse.ai/threads/thr_01HZYB2B9XFT1TD.../run \
 -H "api-key: <SUA_API_KEY>" \
 -d '{
   "role": "user",
   "content": "Olá, tudo bem?"
}'

A resposta segue o formato padrão de ChatCompletion da OpenAI, incluindo a mensagem do assistente e o uso de tokens.

Modo Stream (`/stream`)

Ideal para UIs em tempo real (como um chat), enviando a resposta do Agente em pedaços (tokens) à medida que são gerados. A conexão usa SSE (Server-Sent Events). Diferentemente do modo /run, o stream permite ver todos os passos internos que o Agente está tomando.

Endpoint: POST /threads/{thread_id}/stream

bash

curl -N -X POST https://api.sippulse.ai/threads/thr_01HZYB2B9XFT1TD.../stream \
 -H "api-key: <SUA_API_KEY>" \
 -d '{"role": "user", "content": "Explique a teoria da relatividade em 20 palavras."}'

Eventos do Stream:

Cada linha do stream contém data: <json> com diferentes tipos de eventos que revelam o processo interno do Agente:

Evento	Descrição	Campos Principais
`tool_call_request`	O Agente solicitou uma chamada de ferramenta.	`id`, `name`
`tool_call_initiated`	Uma ferramenta foi chamada automaticamente.	`id`, `tool_calls`, `name`
`tool_call_complete`	Uma ferramenta terminou de executar.	`tool_call_name`, `tool_call_id`, `result`
`message_chunk`	Fragmento da mensagem sendo gerada em tempo real.	`id`, `content`
`message_complete`	A mensagem foi finalizada.	`id`, `content`
`message_report`	Relatório final com métricas da execução.	`id`, `usage`, `execution_time`
`abort`	Algo interrompeu o processamento.	`reason`

Exemplo de fluxo de eventos:

data: {"id":"msg_123","event":"tool_call_initiated","tool_calls":[...],"name":"buscar_pedido"}
data: {"event":"tool_call_complete","tool_call_name":"buscar_pedido","tool_call_id":"call_456"}
data: {"id":"msg_123","event":"message_chunk","content":"Seu pedido"}
data: {"id":"msg_123","event":"message_chunk","content":" #12345"}
data: {"id":"msg_123","event":"message_complete","content":"Seu pedido #12345 foi enviado hoje."}
data: {"event":"message_report","id":"msg_123","usage":{"total_tokens":45},"execution_time":1250}
data: [DONE]

3.3. Consultar uma Thread

Obtenha informações detalhadas sobre uma thread, incluindo histórico de mensagens, pós-análises (quando disponíveis) e metadados.

Endpoint: GET /threads/{thread_id}

bash

curl -X GET https://api.sippulse.ai/threads/thr_01HZYB2B9XFT1TD... \
 -H "api-key: <SUA_API_KEY>"

Resposta (exemplo):

json

{
  "id": "thr_01HZYB2B9XFT1TD...",
  "agent_id": "agt_0123456789abcdef",
  "status": "closed",
  "created_at": "2024-03-15T10:30:00Z",
  "closed_at": "2024-03-15T10:45:00Z",
  "messages": [
    {
      "id": "msg_001",
      "role": "user",
      "content": "Olá, qual o status do meu pedido?",
      "timestamp": "2024-03-15T10:30:15Z"
    },
    {
      "id": "msg_002", 
      "role": "assistant",
      "content": "Claro! Seu pedido #12345 foi enviado hoje às 09:00.",
      "timestamp": "2024-03-15T10:30:18Z"
    }
  ],
  "post_analysis": {
    "summary": "Cliente consultou status de pedido. Atendimento resolvido.",
    "sentiment": "neutral",
    "tags": ["pedido", "status", "logística"]
  },
  "text_history": "Usuário: Olá, qual o status do meu pedido?\nAssistente: Claro! Seu pedido #12345 foi enviado hoje às 09:00.",
  "vars": {
    "user_name": "Pedro",
    "plan_type": "Premium"  
  }
}

Este endpoint é especialmente útil para:

Recuperar o histórico completo de uma conversa
Acessar pós-análises geradas pelo Agente após o encerramento
Sincronizar dados entre diferentes sistemas
Auditorias e relatórios

3.4. Encerrar a Conversa (`/close`)

É a forma recomendada de finalizar uma thread. Esta ação muda o status para closed, dispara webhooks configurados (ex: thread.closed) e executa as Pós-Análises do Agente. A thread ainda pode ser consultada, mas não pode mais receber novas mensagens.

Endpoint: POST /threads/{thread_id}/close

3.5. Excluir a Conversa (`/delete`)

Ação Destrutiva

Use este endpoint com extremo cuidado. Ele remove permanentemente a thread e todo o seu histórico de mensagens. Na maioria dos casos, encerrar (/close) é a melhor opção, pois preserva os dados para análise futura.

Endpoint: DELETE /threads/{thread_id}

4. Formato da Mensagem e Histórico

4.1. Estrutura da Mensagem

O formato do objeto de mensagem segue o padrão de mercado estabelecido por grandes LLMs (OpenAI, Anthropic, Google), garantindo familiaridade e facilidade de integração.

json

{
  "role": "user",
  "content": "Qual é o status do meu pedido #12345?",
  "name": "opcional_nome_da_ferramenta",
  "tool_call_id": "opcional_id_da_chamada_de_ferramenta"
}

`role`	Descrição
`user`	Representa uma mensagem enviada pelo usuário final. Esta é a role que você usará na maioria das vezes para interagir com o Agente.
`assistant`	Representa uma mensagem gerada pelo Agente. Se você enviar uma mensagem com esta role, ela será apenas adicionada ao histórico da conversa, e o Agente não irá gerar uma resposta. Útil para construir um histórico de conversa manualmente.
`tool`	Usada para fornecer o resultado de uma chamada de ferramenta manual. A mensagem deve conter o resultado da execução da ferramenta e o `tool_call_id` correspondente.

4.2. Gerenciamento do Histórico

Você tem duas opções para gerenciar o histórico de mensagens:

Gerenciamento Automático (Recomendado)

Por padrão, a SipPulse AI gerencia todo o histórico da conversa para você. Basta enviar um único objeto de mensagem em cada requisição. O sistema anexa sua mensagem ao histórico existente e gera a resposta do Agente com base em todo o contexto da thread.

Exemplo:

json

// Envie apenas o objeto da nova mensagem
{
  "role": "user",
  "content": "Obrigado pela ajuda!"
}

Gerenciamento Manual (Avançado)

Se você precisa de controle total sobre o contexto, pode gerenciar o histórico por conta própria. Para isso, em vez de um objeto, envie um array de objetos de mensagem.

Sobrescrita de Histórico

Quando você envia um array, o histórico de mensagens da thread é completamente substituído pelo conteúdo que você enviou. A SipPulse AI não usará nenhum histórico anterior da thread para gerar a resposta. Você se torna o único responsável por manter e enviar o contexto completo a cada chamada.

Exemplo:

json

// Envie o histórico completo a cada chamada
[
  { "role": "user", "content": "Olá, qual o status do meu pedido?" },
  { "role": "assistant", "content": "Claro, qual o número do pedido?" },
  { "role": "user", "content": "É o #12345." }
]

5. Exemplos Práticos

5.1. Chat Bot de Atendimento ao Cliente

javascript

// 1. Criar thread com dados do cliente
const thread = await fetch('/threads', {
  method: 'POST',
  headers: { 'api-key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    agent_id: 'agt_atendimento_123',
    uid: `customer-${customerId}-${Date.now()}`,
    vars: {
      customer_name: 'Maria Silva',
      customer_tier: 'Gold',
      last_purchase: '2024-03-10'
    }
  })
}).then(r => r.json());

// 2. Interagir via stream para UI em tempo real
const response = await fetch(`/threads/${thread.id}/stream`, {
  method: 'POST',
  headers: { 'api-key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    role: 'user',
    content: 'Preciso cancelar meu pedido'
  })
});

// 3. Processar eventos do stream
const reader = response.body.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const lines = new TextDecoder().decode(value).split('\n');
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      if (data.event === 'message_chunk') {
        updateUI(data.content); // Atualiza interface em tempo real
      }
    }
  }
}

5.2. Processamento em Lote (Backend)

python

import requests

# Processar múltiplas consultas de forma síncrona
def process_customer_queries(queries):
    results = []
    
    for query in queries:
        # Criar thread
        thread = requests.post('/threads', 
            headers={'api-key': API_KEY},
            json={
                'agent_id': 'agt_support_456',
                'vars': {'priority': 'high'}
            }).json()
        
        # Enviar mensagem (modo síncrono)
        response = requests.post(f'/threads/{thread["id"]}/run',
            headers={'api-key': API_KEY},
            json={'role': 'user', 'content': query}).json()
        
        # Fechar thread
        requests.post(f'/threads/{thread["id"]}/close',
            headers={'api-key': API_KEY})
        
        results.append(response['choices'][0]['message']['content'])
    
    return results

6. Webhooks Úteis

Para monitorar eventos de threads de forma assíncrona, configure Webhooks em Integrações → Webhooks.

Evento	Quando ocorre	Payload chave
`thread.created`	Após a criação bem-sucedida de uma thread.	`id`, `agent_id`, `uid`, `vars`
`thread.closed`	Após uma thread ser encerrada (via API ou por inatividade em outros canais).	`id`, `post_analysis`, `text_history`

7. Limites e Custos

Rate Limits: A API reflete os limites de requisições por segundo (RPS) do modelo de linguagem escolhido no seu Agente. Exceder o limite retornará um erro 429 Too Many Requests. Os detalhes do limite atual são retornados nos cabeçalhos x-rate-limit-* para ajudar a monitorar se o modelo ainda possui requisições disponíveis.
Custos: Os custos são calculados com base no custo do modelo LLM escolhido + o custo de tokens de saída do Agente. Consulte a página de preços para detalhes.

Implantando Agentes

Integração via API HTTP ​

1. Autenticação ​

2. Conceitos Fundamentais ​

3. Fluxo de Conversa Essencial ​

3.1. Criar uma Conversa (Thread) ​

3.2. Enviar Mensagens ​

Modo Síncrono (/run) ​

Modo Stream (/stream) ​

3.3. Consultar uma Thread ​

3.4. Encerrar a Conversa (/close) ​

3.5. Excluir a Conversa (/delete) ​

4. Formato da Mensagem e Histórico ​

4.1. Estrutura da Mensagem ​

4.2. Gerenciamento do Histórico ​

Gerenciamento Automático (Recomendado) ​

Gerenciamento Manual (Avançado) ​

5. Exemplos Práticos ​

5.1. Chat Bot de Atendimento ao Cliente ​

5.2. Processamento em Lote (Backend) ​

6. Webhooks Úteis ​

7. Limites e Custos ​

Integração via API HTTP

1. Autenticação

2. Conceitos Fundamentais

3. Fluxo de Conversa Essencial

3.1. Criar uma Conversa (Thread)

3.2. Enviar Mensagens

Modo Síncrono (`/run`)

Modo Stream (`/stream`)

3.3. Consultar uma Thread

3.4. Encerrar a Conversa (`/close`)

3.5. Excluir a Conversa (`/delete`)

4. Formato da Mensagem e Histórico

4.1. Estrutura da Mensagem

4.2. Gerenciamento do Histórico

Gerenciamento Automático (Recomendado)

Gerenciamento Manual (Avançado)

5. Exemplos Práticos

5.1. Chat Bot de Atendimento ao Cliente

5.2. Processamento em Lote (Backend)

6. Webhooks Úteis

7. Limites e Custos