Mesa de ayuda (API v1)

Mesa de ayuda recibe una solicitud desde un kiosco, WhatsApp, la web o tu propio sistema, crea su ticket en el mismo instante y ofrece solo los canales que una persona puede atender ahora: videollamada, llamada o chat. Si no hay nadie disponible, el asistente de IA de la cola atiende por chat cuando el origen lo permite. Si tampoco es posible, la solicitud queda en espera con prioridad y pasa a la siguiente persona que quede libre.

Es un servicio aparte. Se habilita en el contrato del cliente desde Central con el servicio Mesa de ayuda. Sin ese servicio, la API responde 403.

Acceso

• Llamadas de servidor a servidor con Authorization: Bearer tk_live_… y permisos helpdesk:read o helpdesk:write. Las claves de pruebas (tk_test_…) crean solicitudes en el entorno sandbox.
• La clave nunca va en el navegador ni en el kiosco. Tu backend llama a la API; al navegador del agente solo le entregas un token de sesión de 15 minutos.
• Las acciones de un agente indican quién actúa con una de estas cabeceras:
  • X-TalkHero-Agent: <id del agente en talkHero>
  • X-TalkHero-Agent-External: <id del empleado en tu sistema>
• Cada acción queda en la auditoría con la clave usada.

Equipo y disponibilidad

Una persona cuenta como disponible solo si cumple todo esto: está activa, marcó Disponible, su consola está conectada (stream abierto o latido en los últimos 45 segundos), pertenece a la cola, la cola está en horario y tiene capacidad libre en ese canal. Mientras atiende una llamada o videollamada no recibe otras ofertas.

Stream del agente

GET /v1/helpdesk/stream con Authorization: Bearer hds_… entrega eventos SSE: ready, offer, request, call, presence y message. Cada evento trae solo identificadores y estado; consulta el detalle desde tu backend. La conexión envía un ping cada 20 segundos y se cierra a los 55; vuelve a conectar al cerrarse.

Colas

GET/POST /v1/helpdesk/queues y PATCH /v1/helpdesk/queues/{id}. Cada cola define canales, horario semanal en hora de Colombia, asistente de IA de respaldo (ai_agent_id), tiempo para aceptar una oferta (20 segundos por defecto), intentos de oferta (3), tiempo de timbre (60 segundos), tiempo máximo de espera (120 minutos), duración máxima de llamada (60 minutos) y plazo del ticket en minutos. PUT /v1/helpdesk/queues/{id}/members define quiénes la atienden y su prioridad. La primera solicitud crea la cola General si no existe ninguna.

Aviso por WhatsApp a la mesa

Una cola puede avisar por WhatsApp cuando una solicitud es urgente (high o critical) o cuando nadie puede tomarla. Configura alert en la cola:

{ "alert": { "channel_account_id": "<remitente WhatsApp del cliente>", "template_id": "<plantilla de utilidad>", "phones": ["+573001112233"], "on": ["no_agents", "urgent"], "reminder_minutes": 15 } }

• Se envía 1 aviso por solicitud y celular (hasta 5 celulares) y, si sigue en espera, 1 recordatorio. Las solicitudes de prueba nunca envían.
• La plantilla debe ser de utilidad, del remitente del mismo cliente, con 5 variables: 1 referencia, 2 origen, 3 ubicación, 4 motivo, 5 fecha y hora de Colombia.
• Cada aviso consume del cupo de WhatsApp Notification del cliente y queda en la auditoría.

Entrada desde WhatsApp y el chat web

Con intake_channels (whatsapp, widget), una conversación de ese canal que pide hablar con una persona se convierte en una solicitud de chat de la cola, con su ticket y la misma conversación. Las respuestas del agente llegan al cliente por el mismo canal. Si el asistente de IA de una solicitud pide ayuda humana, la solicitud vuelve a las personas de su cola.

Solicitudes

curl -X POST https://my.talkhero.app/api/v1/helpdesk/requests \
  -H "Authorization: Bearer $TALKHERO_KEY" -H "Content-Type: application/json" \
  -d '{
    "request_id": "0b0e5a8c-6f1e-4c55-9a2a-3f4b8d1e2c10",
    "origin": { "kind": "kiosk", "ref": "kiosco-0142", "name": "Kiosco Centro", "location": "Punto Centro", "platform": "android" },
    "capabilities": ["video", "voice"],
    "source": "user",
    "subject": "El kiosco no entregó el cambio",
    "context": { "transaction_id": "TRX-55120", "amount_cop": 20000 }
  }'

• request_id es obligatorio y hace la creación idempotente: repetirlo con el mismo contenido devuelve la misma solicitud; con otro contenido responde 409.
• capabilities indica qué puede mostrar el dispositivo. channel pide un canal directo si está disponible.
• source: "user" significa que una persona pidió ayuda. source: "auto" significa que el dispositivo reportó un problema por sí mismo: la llamada timbra primero y la persona debe aceptar.
• context admite hasta 30 claves; las que caben se copian a los campos personalizados del ticket.

La respuesta incluye ticket_id, reference (por ejemplo MA-20261113-71D945), state, available_channels, pending_offer, position en la cola y la última llamada.

Otras rutas del solicitante: GET /v1/helpdesk/availability?capabilities=video,voice,chat, GET /v1/helpdesk/requests/{id}, POST …/{id}/channel (video, voice, chat, ai o wait), POST …/{id}/answer ({"accepted": true} cuando timbra), POST …/{id}/join (token de la sala), POST …/{id}/end, POST …/{id}/messages, GET …/{id}/messages?after=…, POST …/{id}/cancel y POST …/{id}/csat (1 a 5).

Acciones del agente

Todas llevan X-TalkHero-Agent o X-TalkHero-Agent-External:

• POST …/{id}/offer/accept y POST …/{id}/offer/decline. Una oferta vencida o rechazada pasa a la siguiente persona.
• POST …/{id}/take toma un caso en espera o con la IA.
• POST …/{id}/call crea la sala de video o voz y devuelve livekit.url y livekit.token del agente. El agente siempre inicia la llamada.
• POST …/{id}/rejoin entrega un token nuevo para volver a una llamada activa.
• POST …/{id}/messages envía un mensaje; con "internal": true guarda una nota interna en el ticket.
• POST …/{id}/transfer cambia de cola.
• POST …/{id}/resolve exige una nota de cierre. Termina la llamada, deja la nota en el ticket y lo pasa a resuelto.
• GET /v1/helpdesk/requests (filtros state, queue_id, agent_id, origin, from, to) y GET /v1/helpdesk/stats alimentan el tablero.

Llamadas y video

Las salas usan LiveKit. Cada sala admite 3 participantes y se cierra sola 5 minutos después de quedar vacía. Los tokens duran 10 minutos. La grabación está desactivada. Los minutos de llamada del mes se comparan con el límite del servicio en el contrato; al alcanzarlo, una nueva llamada responde 403.

La conexión real de ambas partes la confirma LiveKit por webhook. La solicitud pasa a in_progress y se registran las horas de entrada de cada parte y la duración.

Panel de talkHero (sin integración propia)

Los clientes que no integran su propio sistema atienden desde el panel, en Mesa de ayuda:

• Consola: cada miembro (propietario, administrador o agente) se activa como agente, marca Disponible y recibe ofertas con aviso. Desde el detalle toma casos, inicia videollamada o llamada, escribe al solicitante, deja notas internas en el ticket y resuelve con nota de cierre. Un miembro que no es administrador solo actúa como él mismo.
• Analítica: solicitudes por día, porcentaje de resueltas, espera y atención promedio, abandonadas, atendidas por la IA, minutos de llamada, CSAT y desglose por origen y canal (7, 30 o 90 días, en hora de Colombia). También está en GET /v1/helpdesk/analytics?days=30.
• Colas (administradores): canales, entrada desde WhatsApp y chat web, tiempo para aceptar y espera máxima.

Rutas de sesión del panel: GET /v1/helpdesk/me (mi agente) y POST /v1/helpdesk/me (activarme como agente).

Flujos

El disparador Solicitud de Mesa de ayuda (helpdesk_request) inicia un flujo cuando una solicitud se crea, queda sin nadie disponible, se asigna, se resuelve, se abandona o se cancela. Puede limitarse por origen (kiosk, whatsapp, web, api). Corre una vez por solicitud y evento, después de confirmar el cambio. Las solicitudes de prueba corren el flujo en modo prueba.

En los pasos están disponibles {{context.request.reference}}, {{context.request.subject}}, {{context.request.origin.ref}}, {{context.request.context.<campo>}} y {{context.ticket_id}}. Además de los pasos generales, hay dos pasos propios:

• Nota interna en el ticket (add_ticket_note): deja una nota que solo ve el equipo.
• Urgencia de la solicitud (update_helpdesk_request): cambia la urgencia, que define el orden de la fila.

La plantilla Kiosco con dinero retenido sube la prioridad del ticket, consulta la transacción con la acción kiosk_lookup_transaction, deja el resultado como nota y, si el dinero quedó retenido, pone la solicitud de primera en la fila.

Webhooks

Suscribe tu endpoint a: helpdesk.request.created, helpdesk.request.offered, helpdesk.request.queued, helpdesk.request.ai_assigned, helpdesk.request.assigned, helpdesk.call.ringing, helpdesk.call.started, helpdesk.call.ended, helpdesk.request.resolved, helpdesk.request.abandoned, helpdesk.request.cancelled y helpdesk.agent.presence_changed, además de los eventos ticket.*. Se firman igual que el resto de webhooks y se emiten en la misma transacción del cambio.