O guia definitivo da API do desenvolvedor

Todos os endpoints de API exigem uma chave de API Chirps no cabeçalho Authorization. Você pode gerar uma chave de API no API Manager na seção Desenvolvedor do seu painel.

Authorization: Bearer <YOUR_CHIRPS_API_KEY>

Exemplo de solicitação:

curl -X GET https://chirps.cc/api/billing/usage \
  -H "Authorization: Bearer <YOUR_CHIRPS_API_KEY>" \
  -H "Content-Type: application/json"

Tratamento de erros padrão

Listar assistentes

Busca uma lista de todos os assistentes associados ao espaço de trabalho da chave de API.

Crie um assistente

POST /api/assistentes

Cria um novo assistente com todas as configurações básicas.

{

  "businessName": "Acme Corp",
  "businessUrl": "https://acme.com",
  "knowledgeBaseType": "both",
  "knowledgeBaseUrl": "https://acme.com/help",
  "knowledgeBaseText": "Raw text content of a document...",
  "knowledgeBaseFileName": "company_handbook.pdf",
  "language": "en",
  "isMultiLanguage": false,
  "tonePersonality": "professional",
  "isCustomPersonality": false,
  "supportEmail": "[email protected]",
  "maxPages": 5,
  "maxDepth": 2,
  "welcomeMessageDelay": 2
}

Excluir assistente

DELETE /api/assistants/:id

Exclui permanentemente o assistente e exclui em cascata todos os seus nós de conhecimento e histórico. Nenhuma carga útil necessária.

GET /api/analytics/overview?assistantId=uuid&range=30

Obtenha estatísticas de uso, total de mensagens, leads capturados e métricas gerais de engajamento para o assistente especificado. O parâmetro range é opcional (número de dias, mínimo 7, máximo 365, padrão 30).

Resposta Esperada

{

  "totalConversations": 1245,
  "totalMessages": 8420,
  "totalLeads": 156,
  "totalBookings": 42,
  "satisfactionRate": 94,
  "avgMessagesPerSession": 6.7,
  "avgSessionsPerDay": 41.5,
  "liveNow": 3,
  "onlineNow": 12,
  "dailySeries": [
    {
      "date": "2026-07-15",
      "conversations": 45,
      "messages": 310,
      "leads": 5,
      "bookings": 2
    }
  ],
  "agentStats": [
    {
      "name": "Jane Doe",
      "messagesSent": 120,
      "csat": 98
    }
  ]
}

Gerenciando nós de conhecimento

GET /api/assistants/:id/nodes - Lista todos os nós de conhecimento deste assistente.

POST /api/assistants/:id/nodes - Injete manualmente um novo bloco de conhecimento.

{

  "title": "Return Policy",
  "refined_content": "We offer a 30-day return policy for all unused items...",
  "type": "text",
  "metadata": {}
}

PATCH /api/assistants/:id/nodes/:nodeId - Modifique o conteúdo de um nó existente ou alterne seu estado ativo.

{

  "title": "Updated Return Policy",
  "refined_content": "We offer a 60-day return policy now...",
  "is_active": true
}

DELETE /api/assistants/:id/nodes/:nodeId - Exclua totalmente um bloco de conhecimento.

POST /api/assistants/:id/nodes/:nodeId/re-crawl - Força o scraper a rastrear novamente o URL associado a este nó e atualizar seu conteúdo. Carga útil: {}.

Treinamento de IA

POST /api/assistants/:id/train - Compile todos os nós de conhecimento is_active e use um orquestrador de IA para sintetizar dinamicamente um novo prompt do Master System. Carga útil: {}.

Atualizar a aparência do widget

PATCH /api/assistants/:id/widget-config

{

  "primaryColor": "#000000",
  "position": "bottom-right",
  "language": "en",
  "welcomeMessage": "Hi! How can I help you today?",
  "title": "Acme Support",
  "theme": "light",
  "fontFamily": "default",
  "bubbleStyle": "circle",
  "bubbleText": "Chat with us",
  "headerSubtitle": "We typically reply instantly",
  "inputPlaceholder": "Type your message...",
  "privacyPolicyUrl": "https://acme.com/privacy",
  "voiceEnabled": true,
  "voiceName": "Fenrir",
  "welcomeMessageDelay": 2,
  "fileUploadEnabled": true,
  "dictationEnabled": true,
  "copilotEnabled": true,
  "welcomeSuggestions": ["Pricing plans", "Contact sales"],
  "pageVisibility": {
    "mode": "all",
    "paths": []
  }
}

Nomes de voz disponíveis

• Fêmea: Zephyr, Aoede, Core, Leda, Callirrhoe, Despina, Erinome, Laomedeia, Achernar, Pulcherrima, Gacrux, Algenib, Sulfat
• Masculino: Puck, Charon, Fenrir, Orus, Enceladus, Iapetus, Umbriel, Algieba, Autonoe, Rasalgethi, Alnilam

Logotipo personalizado

POST /api/assistants/:id/widget-logo

Formato: multipart/form-data com campo file.

Opção A: incorporação na Web (frontend)

A maneira mais fácil de integrar o assistente em um site padrão (WordPress, Shopify, React, etc.). O código incorporado é puramente determinístico. Você não precisa de um endpoint para buscá-lo. Basta colocar isso no <head> do seu site:

<script src="https://chirps.cc/widget.js" data-assistant-id="YOUR_ASSISTANT_ID_HERE"></script>

Opção B: Integrações Headless (Backend/CRMs/Bots)

Se você estiver construindo um cliente personalizado (como um bot Discord, uma integração Telegram ou um aplicativo iOS nativo), você NÃO usará o Web Embed. Em vez disso, você interagirá diretamente com o endpoint /api/chat.

POST /api/chat ou /api/chat?stream=true

Observação: Este endpoint é público e *não* requer o cabeçalho da chave de API Authorization: Bearer. A autenticação é tratada implicitamente por meio do assistantId.

{

  "assistantId": "123e4567-e89b-12d3-a456-426614174000",
  "sessionId": "unique-session-id-for-user",
  "conversationId": "optional-uuid",
  "message": "Hello, I need help with my billing."
}

*(Também suporta multipart/form-data com um campo file para anexos se fileUploadEnabled for verdadeiro).*

Modo 1: resposta JSON padrão (padrão)

Ao enviar uma solicitação POST para /api/chat (sem o parâmetro stream), você aguarda a resposta completa da IA ​​e recebe um objeto JSON padrão.

{

  "message": "Here is the information you requested...",
  "conversationId": "uuid-of-conversation",
  "messageId": "uuid-of-message"
}

*(Se is_active_agent: true for retornado, um humano assumiu o controle do bate-papo e message será null.)*

Modo 2: streaming de eventos enviados pelo servidor (?stream=true)

Ao anexar ?stream=true ao URL, você recebe um fluxo de eventos enviados pelo servidor (SSE) em tempo real. Seu código deve escutar estes tipos de eventos específicos:

• `evento: token`: Contém {"text": "chunk"}. Disparado para cada parte do texto de resposta da IA.
• `event: status`: Contém {"text": "Pesquisando na base de conhecimento..."}. Representa estados de execução da ferramenta de back-end.
• `event: done`: Contém {"messageId": "uuid", "conversationId": "uuid", "message": "full text"}. Disparado quando a geração está completamente concluída.
• `evento: erro`: Contém {"error": "Mensagem de erro"}. Disparado se ocorrerem limites de taxa ou erros.

Terminais de aquisição ao vivo

GET /api/chat/sessions

Recuperar sessões históricas.

POST /api/chat/toggle-agent

Pause a IA para controle humano. Carga útil: { "sessionId": "..." }

POST /api/chat/mensagem do agente

Envie uma mensagem humana. Carga útil: { "sessionId": "...", "message": "..." }

Atualizar configuração principal

Modifique as configurações principais, a personalidade e os limites de raspagem do assistente.

{

  "business_name": "Acme Corp",
  "business_url": "acme.com",
  "business_description": "We sell anvils.",
  "system_prompt": "You are a helpful assistant.",
  "language": "en",
  "tone_personality": "Friendly",
  "support_email": "[email protected]",
  "additional_instructions": "Never mention the Roadrunner.",
  "is_multi_language": true,
  "is_dev_mode": false,
  "is_active": true,
  "max_pages": 15,
  "max_depth": 2,
  "widget_config_merge": {
    "rateLimitEnabled": true
  }
}

*Nota: Todos os campos são opcionais. Envie apenas os campos que deseja atualizar.*

Excluir assistente

DELETE /api/assistants/:id

Exclui permanentemente o assistente e distribui a exclusão em cascata para todos os nós de conhecimento, conversas e mensagens. Se o assistente nunca tiver sido totalmente configurado, isso reembolsará a cota mensal de criação.

POST /api/phone-numbers/:id/assign - Provisione um número. Carga útil: {}

POST /api/assistants/:id/outbound - Aciona chamada de saída. Carga útil: { "to": "+123...", "message": "..." }

GET /api/leads?id=leadId - Obtenha detalhes de um único lead, incluindo a transcrição completa da conversa.

GET /api/bookings?id=bookingId - Obtenha detalhes de uma única reserva, incluindo a transcrição da conversa.

POST /api/bookings/cancel - Cancela uma reserva ativa. Carga útil: { "bookingId": "uuid" }

POST /api/bookings/reschedule - Ajuste uma reserva. Carga útil: { "bookingId": "uuid", "newTime": "ISO-8601" }

Recupere o uso do ciclo de cobrança do workspace, os limites do plano de assinatura e a contagem total de assistentes. Observação: Ao usar uma chave de API, a solicitação tem automaticamente como escopo o espaço de trabalho da chave de API; você não precisa fornecer um teamId.

Resposta (`200 OK`):

{

  "planName": "Pro",
  "periodStr": "2023-10-01",
  "assistantCount": 3,
  "usage": {
    "message_count": 1450,
    "harvest_count": 12,
    "recrawl_count": 5,
    "train_count": 2,
    "assistants_created_count": 1,
    "voice_minutes_used": 0,
    "sms_count": 0,
    "email_count": 0,
    "whatsapp_count": 0
  },
  "limits": {
    "messages": 5000,
    "assistants": 5,
    "training": 50,
    "recrawls": 20
  },
  "workspaceOwnerId": "uuid"
}