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

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/asistentes

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

BORRAR /api/asistentes/:id

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

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

Actualizar la apariencia del 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": []
  }
}

Nombres de voz disponibles

• Mujer: Zephyr, Aoede, Core, Leda, Callirrhoe, Despina, Erinome, Laomedeia, Achernar, Pulcherrima, Gacrux, Algenib, Sulfat
• Masculino: Puck, Charon, Fenrir, Orus, Enceladus, Jápeto, Umbriel, Algieba, Autonoe, Rasalgethi, Alnilam

Logotipo personalizado

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

Formato: multipart/form-data con campo file.

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 src="https://chirps.cc/widget.js" data-assistant-id="YOUR_ASSISTANT_ID_HERE"></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

Nota: Este punto final es público y *no* requiere el encabezado de clave API Autorización: Portador. La autenticación se maneja implícitamente a través del "assistantId".

{

  "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á nulo.)*

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:

• `evento: token`: Contiene {"text": "chunk"}. Se dispara por cada fragmento del texto de respuesta de la IA.
• `evento: estado`: Contiene {"text": "Buscando base de conocimientos..."}. Representa los estados de ejecución de la herramienta backend.
• `evento: hecho`: Contiene {"messageId": "uuid", "conversationId": "uuid", "message": "full text"}. Despedido cuando la generación está completamente terminada.
• `evento: error`: Contiene {"error": "Mensaje de error"}. 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": "..." }

POST /api/chat/mensaje-agente

Enviar mensaje humano. Carga útil: { "sessionId": "...", "message": "..." }

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

BORRAR /api/asistentes/: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/:id/assign - Proporciona un número. Carga útil: {}

POST /api/assistants/:id/outbound - Activar llamada saliente. Carga útil: { "a": "+123...", "mensaje": "..." }

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

GET /api/bookings?id=bookingId: recupera los detalles de una sola reserva, incluida la transcripción de la conversación.

POST /api/bookings/cancel - Cancelar una reserva activa. Carga útil: { "bookingId": "uuid" }

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

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