Enterarse de por qué la IA se quedó callada

Un endpoint responde quince motivos posibles; otros dos solo se ven en la bandeja.

Un cliente escribió y nadie contestó. Antes de sospechar del modelo, existe un endpoint hecho exactamente para esta pregunta. Responde con un código que se puede alertar, y con una frase que se puede leer.

Trampa

No todo silence_reason significa que la IA está callada

Dos de los quince motivos no son silencio real. awaiting_human_reply describe una conversación traspasada a una persona, en un canal configurado para seguir respondiendo hasta que esa persona conteste. El texto exacto dice "The AI is NOT silent, it still answers the next inbound message". awaiting_payment depende del modo del workspace: en espera estricta sí calla; en el modo por defecto sigue respondiendo, con la confirmación de pago bloqueada nada más. Filtrar por «hay un motivo, luego está callada» clasifica mal estos dos casos.

Antes de empezar

conversations:read para consultar el estado y el historial.
messaging_accounts:read para revisar el canal detrás de la conversación.
El id o el display_id (C-163) de la conversación en duda.

1. Preguntar directo

curl https://api.vitrinadev.com/api/v1/conversations/01a0ce15-c122-7148-98b3-4dfefe93756e/ai-status \
  -H "Authorization: Bearer $VITRINA_KEY"

{
  "data": {
    "silence_reason": "handler_is_human",
    "explanation": "A teammate replied, so this conversation is handled by a human. The AI stays silent until it is explicitly returned to the AI."
  }
}

explanation llega en inglés siempre; la bandeja la localiza al mostrarla, esta llamada no. Cuando el próximo mensaje entrante sí va a recibir respuesta, silence_reason viene null:

curl https://api.vitrinadev.com/api/v1/conversations/01a0cbf4-d541-736b-915d-a5875e7caa46/ai-status \
  -H "Authorization: Bearer $VITRINA_KEY"

{ "data": { "silence_reason": null, "explanation": null } }

Un null limpio confirma que el problema, si lo hay, está en otra parte: el modelo, el canal o el proveedor. Los pasos siguientes acotan cuál.

2. Leer el motivo exacto cuando falta configuración

Algunos motivos nombran una configuración incompleta y no una decisión de nadie:

{
  "data": {
    "silence_reason": "webchat_account_missing",
    "explanation": "This web conversation has no messaging account, so the webchat AI opt-in cannot be read and the AI fails closed. This is a wiring bug."
  }
}

Una conversación de webchat sin messaging_account asociada no recibe respuesta de la IA. Si ves este motivo, contacta a soporte.

Los quince valores posibles, en un vistazo:

`silence_reason`	Qué significa
`handler_is_human`	Una persona ya contestó; vuelve con `return-to-ai`
`awaiting_human_reply`	Traspasada, pero el canal sigue respondiendo hasta que una persona escriba. No es silencio real
`outside_ai_availability`	Fuera de la ventana configurada para este canal
`channel_ai_disabled`	El canal está deshabilitado
`channel_account_missing`	La conversación perdió su `messaging_account` legible
`kept_with_human`	Alguien marcó la conversación para quedarse con personas
`human_took_over`	Una persona tomó el control a mano
`ai_handed_off`	La IA la traspasó, y no la retoma en la misma ventana
`availability_covering_human`	Sigue asignada a una persona; la ventana de IA cubre lo pendiente mientras tanto
`webchat_ai_disabled`	El widget tiene la IA apagada, con un agente configurado igual
`webchat_account_missing`	Al webchat le falta el `messaging_account`
`no_agent_configured`	Ningún agente: ni de etapa, ni de canal, ni el predeterminado del workspace
`contact_bot_disabled`	Alguien apagó la IA para este contacto, en todo canal
`big_account_contact`	La cuenta de Instagram supera el umbral de seguidores del workspace
`awaiting_payment`	Depende del modo del workspace; ver el recuadro inicial

3. Cruzar el motivo con el canal y el agente

ai-status explica el síntoma; el canal y el agente explican la causa. Cuando el motivo apunta al canal (channel_ai_disabled, no_agent_configured), el mismo dato vive publicado en messaging-accounts:

curl https://api.vitrinadev.com/api/v1/messaging-accounts/00000000-0000-4000-8000-000000005001 \
  -H "Authorization: Bearer $VITRINA_KEY"

{
  "data": {
    "name": "WhatsApp · Acme",
    "enabled": true,
    "assignee_ai_agent_id": null,
    "default_team_id": null
  }
}

enabled: false explicaría channel_ai_disabled sin adivinar. assignee_ai_agent_id en null no es un error: la conversación cae al agente is_default del workspace, que se confirma en GET /ai-agents. Sin ninguno con is_default: true, el motivo es no_agent_configured.

GET /messaging-accounts/{id}/health completa el cuadro con la entrega, no con la decisión de responder:

curl https://api.vitrinadev.com/api/v1/messaging-accounts/00000000-0000-4000-8000-000000005001/health \
  -H "Authorization: Bearer $VITRINA_KEY"

{ "data": { "channel": "whatsapp", "identity": { "display_name": "+56911112222" }, "webhook": null } }

Un silence_reason: null con health mostrando problemas de entrega apunta al proveedor, no a la configuración de la IA.

4. Reconstruir la línea de tiempo

Cada cambio de mano queda escrito en el hilo, con sender_type: "system" y un metadata.event_kind que dice qué pasó (handoff, returned_to_ai, y así). Dejar que la IA conteste, agende y avise cuando se salga del libreto muestra la forma exacta de esos mensajes vía GET /conversations/{id}/messages. Para esta receta alcanza con saber que están ahí: antes de asumir que nadie hizo nada, revisa si una persona o la plataforma ya actuó.

Lo que la API no contesta

Tres cosas se leen por la API pública: el motivo (ai-status), el canal (messaging-accounts) y el agente (ai-agents). Una cuarta no: la ventana de disponibilidad en sí, sus horarios exactos, es de solo lectura desde la aplicación. outside_ai_availability confirma que el motivo es la ventana; qué ventana es esa, y cuándo vuelve a abrir, se revisa en Configuración → Agentes de IA → Disponibilidad.

Cuando falla

Un 404 en ai-status significa que el id de conversación no existe en este workspace. Un 403 significa que la key no tiene conversations:read. Si silence_reason es null y el mensaje sigue sin respuesta, la pregunta cambia: ya no es si la IA debía contestar, sino si contestó y la entrega falló después. En ese caso, revisa el proveedor del canal.