La guía definitiva de API para desarrolladores

Todos los puntos finales de API requieren una clave API de Chirps en el encabezado "Autorización". Puede generar una clave API desde el Administrador de API en la [sección Desarrollador de su panel] (https://chirps.cc/dashboard/developers).

Authorization: Bearer <YOUR_CHIRPS_API_KEY>

Solicitud de ejemplo:

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

Manejo de errores estándar

Ámbitos y privilegio mínimo

Cada clave está limitada a los ámbitos seleccionados. Use claves de solo lectura siempre que sea posible y una clave distinta para cada integración. Un ámbito de escritura no concede automáticamente el ámbito de lectura correspondiente.

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

Límite de claves API

Cada clave de desarrollador admite 300 solicitudes por minuto móvil de forma predeterminada y atómica entre instancias. Un rechazo devuelve 429; espera al reinicio antes de reintentar.

Lista de asistentes

Obtiene una lista de todos los asistentes asociados con el espacio de trabajo de la clave API.

Crear un asistente

POST /api/assistants

Crea un nuevo asistente con todas las configuraciones 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
}

Eliminar asistente

DELETE /api/assistants/:id

Elimina permanentemente el asistente y elimina en cascada todos sus nodos de conocimiento y su historial. No se requiere carga útil.

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

Obtenga estadísticas de uso, mensajes totales, clientes potenciales capturados y métricas generales de participación para el asistente especificado. El parámetro "rango" es opcional (número de días, mínimo 7, máximo 365, predeterminado 30).

Respuesta 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
    }
  ]
}

Gestión de nodos de conocimiento

GET /api/assistants/:id/nodes: enumera todos los nodos de conocimiento para este asistente.

POST /api/assistants/:id/nodes - Inyecta manualmente un nuevo bloque de conocimiento.

{

  "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: modifica el contenido de un nodo existente o alterna su estado activo.

{

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

DELETE /api/assistants/:id/nodes/:nodeId - Elimina un bloque de conocimiento por completo.

POST /api/assistants/:id/nodes/:nodeId/re-crawl: obliga al raspador a volver a rastrear la URL asociada con este nodo y actualizar su contenido. Carga útil: {}.

Entrenamiento de IA

POST /api/assistants/:id/train: compila todos los nodos de conocimiento is_active y utiliza un orquestador de IA para sintetizar dinámicamente un nuevo mensaje maestro del sistema. Carga útil: {}.

Upload, crawl, and index consistency

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

Envía solo los campos que quieras cambiar. La API rechaza claves desconocidas y datos anidados inválidos.

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

Coincidencia de páginas

Usa rutas exactas como /pricing o /* para descendientes como /docs/*. include muestra coincidencias, exclude las oculta y all ignora las rutas.

Voces disponibles

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

Los artefactos usan llamadas a herramientas. El modelo llama la herramienta habilitada y Chirps renderiza la interfaz; no envíes cadenas {{ARTIFACT: ...}}.

{
  "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.

Opción A: Web Embed (frontend)

La forma más sencilla de integrar el asistente en un sitio web estándar (WordPress, Shopify, React, etc.). El código de inserción es puramente determinista. No necesita un punto final para recuperarlo. Simplemente coloque esto en el <head> de su sitio:

<script>
  window.chirpsConfig = { assistantId: "YOUR_ASSISTANT_ID" };
</script>
<script src="https://chirps.cc/embed.js" async></script>

Opción B: Integraciones sin cabeza (Backend/CRM/Bots)

Si está creando un cliente personalizado (como un bot de Discord, una integración de Telegram o una aplicación nativa de iOS), NO utilizará Web Embed. En su lugar, interactuará directamente con el punto final /api/chat.

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

Importante: las llamadas headless y de servidor a servidor deben incluir Authorization: Bearer <YOUR_CHIRPS_API_KEY>. Solo el widget instalado en el navegador usa el flujo público vinculado al origen. Nunca incluya una clave API en JavaScript del frontend.

{

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

*(También admite multipart/form-data con un campo file para archivos adjuntos si fileUploadEnabled es verdadero).*

Modo 1: Respuesta JSON estándar (predeterminada)

Al enviar una solicitud POST a /api/chat (sin el parámetro de transmisión), espera la respuesta AI completa y recibe un objeto JSON estándar.

{

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

*(Si se devuelve is_active_agent: true, un humano se ha hecho cargo del chat y message será null.)*

Modo 2: Transmisión de eventos enviados por el servidor (?stream=true)

Al agregar ?stream=true a la URL, recibirá una transmisión de eventos enviados por el servidor (SSE) en tiempo real. Su código debe escuchar estos tipos de eventos específicos:

• `event: token`: Contiene {"text": "chunk"}. Se dispara por cada fragmento del texto de respuesta de la IA.
• `event: status`: Contiene {"text": "Searching knowledge base..."}. Representa los estados de ejecución de la herramienta backend.
• `event: done`: Contiene {"messageId": "uuid", "conversationId": "uuid", "message": "full text"}. Despedido cuando la generación está completamente terminada.
• `event: error`: Contiene {"error": "Error message"}. Despedido si ocurren límites de tarifas o errores.

Puntos finales de adquisición en vivo

GET /api/chat/sessions

Recuperar sesiones históricas.

POST /api/chat/toggle-agent

Pausa la IA para que el hombre tome el control. Carga útil: { "sessionId": "...", "isActive": true }

POST /api/chat/agent-message

Enviar mensaje humano. 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

Actualizar la configuración principal

Modifique la configuración principal, la personalidad y los límites de raspado del asistente.

{

  "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 los campos son opcionales. Envíe únicamente los campos que desee actualizar.*

Eliminar asistente

DELETE /api/assistants/:id

Elimina permanentemente el asistente y la eliminación en cascada a todos los nodos de conocimiento, conversaciones y mensajes. Si el asistente nunca estuvo completamente configurado, se reembolsa la cuota de creación mensual.

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 - Activar llamada saliente. Carga útil: { "phoneNumber": "+123...", "callReason": "Confirm the requested appointment", "conversationId": "optional-uuid" }

GET /api/leads?id=leadId: obtiene detalles de un único cliente potencial, incluida la transcripción completa de la conversación.

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: recupera los detalles de una sola reserva, incluida la transcripción de la conversación.

DELETE /api/bookings/cancel?id=bookingId - Cancela una reserva activa. Añada &silent=true solo si su integración debe omitir intencionadamente el correo de cancelación de respaldo de Chirps.

POST /api/bookings/reschedule - Ajustar una 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 el uso del ciclo de facturación del espacio de trabajo, los límites del plan de suscripción y el recuento total de asistentes. Nota: Cuando se utiliza una clave API, la solicitud se limita automáticamente al espacio de trabajo de la clave API; no es necesario proporcionar un "teamId".

Respuesta (`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"
}

Qué pertenece a la API pública para desarrolladores

Estas rutas aceptan una clave API de Chirps con ámbitos y aplican el límite de su espacio de trabajo. Se excluyen intencionadamente las rutas de facturación/OAuth del panel, callbacks del widget, webhooks de proveedores, cron y MCP interno.

Asistentes

Conocimiento y entrenamiento

Widget, artefactos y conectores

Conversaciones, leads y reservas

Telefonía y cuenta