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

Escopos e privilégio mínimo

Cada chave fica limitada aos escopos selecionados. Use chaves somente leitura sempre que possível e uma chave separada para cada integração. Um escopo de escrita não concede automaticamente o escopo de leitura correspondente.

assistants:read
assistants:write
analytics:read
artifacts:read
artifacts:write
billing:read
bookings:read
bookings:write
chat:write
connectors:read
connectors:write
conversations:read
conversations:write
knowledge:read
knowledge:write
leads:read
leads:write
telephony:read
telephony:write
widget:write

API-key rate limit

Each developer key is limited to 300 requests per rolling minute by default. The limit is atomic across all application instances and can be changed by the platform with API_KEY_RATE_LIMIT_PER_MINUTE. A rejected request returns 429; retry only after the window resets.

Listar assistentes

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

Crie um assistente

POST /api/assistants

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.

Creation validation and quota safety

Creation allowance is reserved atomically before insertion, so concurrent requests cannot exceed the monthly quota. Database insertion failures refund that reservation. A created assistant starts inactive in developer mode; call the setup endpoint and wait for its successful terminal event before publishing it.

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: {}.

Upload, crawl, and index consistency

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

Send only the fields you want to change. The API rejects unknown keys and invalid nested data instead of silently storing configuration the widget cannot use.

{
  "designPreset": "corporate-soft",
  "primaryColor": "#1972F5",
  "theme": "dark",
  "bubbleStyle": "branded-drawer",
  "bubbleText": "Talk to our team",
  "welcomeMessages": [
    {
      "text": "Hello! How can I help?",
      "delay": 1.5
    }
  ],
  "welcomeSuggestions": [
    "View pricing",
    "Book a demo"
  ],
  "pageVisibility": {
    "mode": "exclude",
    "paths": [
      "/checkout/*"
    ]
  },
  "voiceEnabled": true,
  "voiceName": "Aoede",
  "copilotEnabled": true,
  "gdprConsentEnabled": true,
  "privacyPolicyUrl": "https://example.com/privacy"
}

Page visibility matching

Use exact paths such as /pricing, or append /* to include descendants such as /docs/*. include shows only matches; exclude hides matches; all ignores paths. Full URLs are normalized to their pathname by the widget.

Available voice names

Zephyr, Aoede, Kore, Leda, Callirrhoe, Despina, Erinome, Laomedeia, Achernar, Pulcherrima, Gacrux, Algenib, Sulafat, Puck, Charon, Fenrir, Orus, Enceladus, Iapetus, Umbriel, Algieba, Autonoe, Rasalgethi, Alnilam, Schedar, Sadachbia, Achird, Zubenelgenubi, Sadaltager

GET /api/assistants/:id/artifacts · PUT /api/assistants/:id/artifacts · PATCH /api/assistants/:id/artifacts

Artifacts are tool-driven UI. The model calls the enabled tool and Chirps renders it; integrations must send configuration JSON, never {{ARTIFACT: ...}} strings.

{
  "form": {
    "enabled": true,
    "title": "Request a quote",
    "description": "Collect the details needed for a quote.",
    "triggerRules": "When a visitor explicitly asks for a quote.",
    "fields": [
      {
        "key": "name",
        "label": "Full name",
        "type": "text",
        "required": true,
        "placeholder": "Jane Doe"
      },
      {
        "key": "email",
        "label": "Work email",
        "type": "email",
        "required": true
      }
    ],
    "submitLabel": "Request quote"
  },
  "booking": {
    "enabled": true,
    "title": "Book a consultation",
    "description": "Choose an available time.",
    "triggerRules": "When a visitor asks to book a meeting.",
    "services_enabled": false,
    "meetings_enabled": true,
    "requiresScheduling": true,
    "timezone": "Europe/Paris",
    "slotDuration": 30,
    "bufferMinutes": 10,
    "workingHours": {
      "monday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "tuesday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "wednesday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "thursday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "friday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "saturday": {
        "enabled": false,
        "start": "10:00",
        "end": "14:00"
      },
      "sunday": {
        "enabled": false,
        "start": "10:00",
        "end": "14:00"
      }
    },
    "blockedDates": [
      "2026-12-25"
    ],
    "meeting_intake_fields": [
      {
        "key": "email",
        "label": "Email",
        "type": "email",
        "required": true
      }
    ],
    "submitLabel": "Book meeting"
  },
  "card": {
    "enabled": false,
    "ctaLabel": "View details",
    "ctaUrl": "",
    "description": "",
    "triggerRules": ""
  },
  "csat_survey": {
    "enabled": true,
    "title": "How was your experience?",
    "description": "One-click feedback.",
    "triggerRules": "Only after the request is resolved."
  },
  "custom": []
}

Field schema

Booking service schema

Validation limits and scheduling rules

Tool-call prefill behavior

Start with GET /api/marketplace/connectors. Its provider definitions are the source of truth for credential fields, configuration fields, available tools, defaults, and required values; this keeps custom and future providers discoverable without a documentation release.

{
  "provider": "shopify",
  "name": "Shopify",
  "credentials": {}
}

1. Install the workspace connector record with POST /api/assistants/:id/connectors; credentials must be omitted or {}.
2. Read its exact field schema from GET /api/marketplace/connectors and activate it with POST /api/assistants/:id/connectors/:connectorId/activate.
3. Send configValues, optional enabledTools, and optional instructions. Chirps verifies non-custom connectors and discovers the tools before saving the integration.
4. Rotate secrets by calling the activation endpoint again. PUT only renames a named Custom API.
5. Use DELETE /api/assistants/:id/connectors with { connectorId } to disable it for one assistant. Use the nested DELETE .../:connectorId only to permanently remove it from the workspace and every assistant.

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>
  window.chirpsConfig = { assistantId: "YOUR_ASSISTANT_ID" };
</script>
<script src="https://chirps.cc/embed.js" async></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

Importante: chamadas headless e servidor a servidor devem incluir Authorization: Bearer <YOUR_CHIRPS_API_KEY>. Somente o widget instalado no navegador usa o fluxo público vinculado à origem. Nunca coloque uma chave de API no JavaScript do frontend.

{

  "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:

• `event: token`: Contém {"text": "chunk"}. Disparado para cada parte do texto de resposta da IA.
• `event: status`: Contém {"text": "Searching knowledge base..."}. 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.
• `event: error`: Contém {"error": "Error message"}. 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": "...", "isActive": true }

POST /api/chat/agent-message do agente

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

Complete chat response contract

{
  "message": "I've opened the booking calendar for you.",
  "messageId": "uuid",
  "conversationId": "uuid",
  "artifacts": [
    {
      "type": "booking",
      "title": "Book a consultation"
    }
  ],
  "sources": []
}

A human takeover returns { message: null, conversationId, is_active_agent: true }. A streaming request can therefore return JSON before an SSE stream begins; check the response Content-Type.

Complete SSE event reference

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/:subscriptionId/assign assigns an already-purchased Chirps phone subscription to an assistant. Send { "assistantId": "uuid" }; send { "assistantId": null } to unassign it. This endpoint does not purchase or provision a new number.

POST /api/assistants/:id/outbound - Aciona chamada de saída. Carga útil: { "phoneNumber": "+123...", "callReason": "Confirm the requested appointment", "conversationId": "optional-uuid" }

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

Public lead response

Lead objects contain id, assistant_id, conversation_id, session_id, name, email, phone, status, notes, artifact_id, ai_score, ai_summary, form_data, created_at, and the assistant business name. Internal voice-confirmation/idempotency identifiers are never returned.

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

DELETE /api/bookings/cancel?id=bookingId - Cancela uma reserva ativa. Adicione &silent=true somente quando a integração precisar suprimir intencionalmente o e-mail de cancelamento de contingência do Chirps.

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

Public booking response and time zones

Booking objects contain the public appointment, guest, status, notes, and timestamp fields plus business_timezone. Times are ISO-8601 instants; format them in the viewer's time zone while preserving the returned business zone for schedule context. Internal confirmation IDs, provider calendar-event IDs, and database range columns are omitted.

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"
}

What belongs in the public developer API

These routes accept a scoped Chirps API key and enforce its workspace boundary. Dashboard-only billing/OAuth routes, browser widget callbacks, provider webhooks, cron jobs, and internal MCP routes are intentionally excluded.

Assistants

Knowledge and training

Widget, artifacts and connectors

Conversations, leads and bookings

Telephony and account