Atención al cliente
API, webhooks o BYOD: ¿qué integración necesitas?
Tres formas de conectar initdesk a tu stack, y solo una de ellas es la nueva API, disponible hoy en developers.initdesk.com.
Si has leído el marketing de initdesk, probablemente hayas visto «conecta cualquier API». Eso suele significar Bring Your Own Data (BYOD): initdesk llama a tu endpoint para que los agentes vean plan, historial de pedidos o uso junto al ticket.
Hoy lanzamos algo distinto: la API de initdesk y la documentación para desarrolladores en developers.initdesk.com. Tus sistemas pueden llamar ahora a initdesk en
https://api.initdesk.com para leer y escribir tickets, solicitantes, conversaciones y contenido del Help Center: la superficie soportada para CRM, herramientas internas, automatización y portales personalizados.Tres vías de integración. Tres direcciones de datos. Elige según quién inicia la petición HTTP, no por palabras de moda.
Tres direcciones (mapa rápido)
| Integración | Quién llama a quién | Ideal para |
|---|---|---|
| API (nueva hoy) | Tú → initdesk (api.initdesk.com) | Crear o listar tickets, sincronizar Help Center, CRM y herramientas internas |
| Webhooks | initdesk → tu URL HTTPS | Reacciones en tiempo real cuando cambian mensajes, asignaciones o estado |
| BYOD | initdesk → tu endpoint de cliente | Contexto de cliente en vivo en la barra lateral del ticket y borradores de IA |
Ninguna sustituye a las otras. Muchos equipos usan BYOD más la API: contexto junto al hilo, tickets creados desde el producto. Webhooks más la API es habitual cuando necesitas un evento que dispare un trabajo que luego obtiene el detalle completo del ticket.
Cuándo usar la API
La API es el valor por defecto adecuado cuando tu código necesita leer o cambiar datos de initdesk bajo demanda.
Trabajos típicos:
- Crear tickets desde un flujo «Contactar soporte» en la app, un CRM o una herramienta de operaciones internas (tú eliges la bandeja; el solicitante es un cliente en términos de la API).
- Listar o buscar tickets para paneles, informes de SLA o resúmenes de escalación que gestionas tú.
- Leer o publicar mensajes cuando construyes un portal personalizado o reflejas hilos en otro sitio.
- Publicar o actualizar artículos y colecciones del Help Center desde un repositorio, CMS o pipeline de lanzamiento.
Todo tiene alcance bajo una organización:
/organizations/{organization_id}/...
Usa el ID numérico de la organización en Configuración → General (no el
public_id de cadena usado en las URL del producto). Autentica con un token con alcance de org en cada petición:X-Initdesk-Token: <your_token>
Emite tokens en Configuración → Acceso a la API (Propietario de la cuenta o Administrador). El valor en bruto se muestra una vez; guárdalo como una contraseña y revócalo si se filtra. Autenticación completa, límites de tasa y relaciones de entidades están en la documentación para desarrolladores y la guía de entidades.
El esquema OpenAPI está en api.initdesk.com/schema.yaml. Para una primera llamada mínima, consulta Conéctate a la API de initdesk en 15 minutos, publicado hoy junto con este artículo.
Lo que la API no es: un sustituto de integraciones nativas del producto. Crear o enlazar issues de Linear sigue en la interfaz de initdesk y la capa de plugins; hoy no hay recurso Linear en la API. El flujo de Issues de Linear desde tickets de soporte sigue aplicando: usa la API para datos de tickets y mensajes, no para archivar issues en Linear.
Cuándo bastan los webhooks
Elige webhooks cuando initdesk deba empujarte un evento y tu trabajo sea reaccionar: notificar en Slack, arrancar n8n, invalidar caché o añadir una fila a una tabla de analítica.
Configúralos en Configuración → API y webhooks. Elige los eventos que te importan (por ejemplo mensaje creado, asignado, resuelto, cambio de estado). Tu endpoint debe devolver una respuesta 2xx en unos cinco segundos o la entrega puede marcarse como fallida.
Los webhooks llevan notificaciones, no una exportación completa de tu cuenta. Si necesitas cuerpos de tickets estructurados, asignados o campos del Help Center bajo demanda, usa la API (o combina: el webhook despierta tu worker, la API aporta la carga).
Referencia de producto: Webhooks en el Help Center de initdesk.
Cuándo encaja BYOD
BYOD es para contexto del cliente en el momento de responder: estado de facturación, plan de suscripción, último pedido, feature flags, lo que viva en tu API de administración.
initdesk hace POST a tu endpoint HTTPS (con cabeceras de autenticación opcionales que configures) y renderiza la respuesta en la barra lateral del ticket con plantillas Liquid. Esos mismos datos pueden informar respuestas borrador de IA, para que los agentes no adivinen solo por el asunto.
BYOD no crea tickets, lista tu bandeja ni publica artículos de ayuda. No sustituye a la API, y la API no extrae datos arbitrarios de tus sistemas a la barra lateral. Para esa división, consulta Bring Your Own Data en Actualizaciones de initdesk y la guía del plugin BYOD.
Combinaciones habituales (y un antipatrón)
BYOD + API crear ticket — Un cliente abre soporte desde tu app; haces
POST de un ticket con su correo y asunto. Cuando un agente abre el hilo, BYOD ya cargó el contexto de la cuenta al lado.Webhook + API recuperar — Un webhook de «mensaje creado» dispara tu worker; el worker llama a recuperar ticket y listar mensajes del hilo completo antes de publicar en un canal interno.
API del Help Center + hábitos editoriales — Sincronizas artículos desde git; los agentes siguen los patrones de contenido de Autoservicio que de verdad se usa para que búsqueda y chat de IA sigan siendo fiables.
Antipatrón: reconstruir initdesk en tu base de datos — Hacer polling de la API a una bandeja sombra duplica estado de asignado, notas internas y gestión de spam por lo que ya pagas en el producto. Prefiere webhooks o lecturas puntuales para las vistas que de verdad necesitas.
Siguientes pasos
- Documentación para desarrolladores (disponible hoy): developers.initdesk.com
- Primera llamada a la API: Primeros pasos con la API de initdesk
- Acceso o preguntas beta: support@initdesk.com
initdesk es un help desk con IA para equipos pequeños: bandeja compartida, Help Center, BYOD, webhooks y —desde hoy— una API para tickets, solicitantes, mensajes y contenido del Help Center. Consulta Actualizaciones del producto para notas de lanzamiento y X @initdeskhq para anuncios.