Answer API

Envías un mensaje y recibes la respuesta de tu agente de IA en JSON, con las fuentes que citó y una señal needs_human cuando no puede resolverlo. Es la misma API que usa MelonHelp Tickets para responder tickets — cualquier sistema tuyo puede usarla igual.

El principio: la IA nunca decide por vos

La API nunca escala, ni crea tickets, ni avisa a nadie. Cuando el agente no puede continuar, responde needs_human: true y tu sistema decide qué hacer: crear un ticket, avisar por Slack, mostrar un formulario. Vos tenés el control.

Autenticación

Crea una API key en Melonhelp Agents → Settings → API. Se muestra una sola vez: guardala en un lugar seguro.

X-API-Key: mh_tu_clave_aqui

Pedir una respuesta

curl -X POST https://agents.melonhelp.com/v1/answer \
  -H "X-API-Key: mh_tu_clave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "¿Hacen envíos a Perú?",
    "conversationRef": "pedido-4821"
  }'

Parámetros

Campo	Requerido	Qué hace
`message`	Sí	El mensaje de tu usuario.
`conversationRef`	No	Identificador de la conversación en tu sistema. Si lo mandas, el agente recuerda el hilo entre llamadas.
`agentId`	No	Qué agente responde. Por defecto, el que configuraste para tickets.
`channel`	No	De dónde viene el mensaje (informativo, para tus métricas).

Respuesta

{
  "conversationId": "cnv_a1b2c3",
  "agentId": "agt_x9y8",
  "message": "Sí, enviamos a todo Perú. El envío tarda entre 3 y 5 días hábiles.",
  "sources": [
    { "externalId": "src_envios", "title": "Política de envíos", "score": 0.82 }
  ],
  "needs_human": false,
  "confidence": "high"
}

Campo	Qué significa
`message`	La respuesta del agente, lista para mostrar.
`sources`	Las fuentes de tu conocimiento que usó para responder.
`needs_human`	`true` = no pudo resolverlo. Acá decidís vos qué hacer.
`confidence`	`high`, `medium` o `low`.

Qué hacer cuando `needs_human` es `true`

El agente ya respondió algo razonable (según tu configuración, un "no lo sé" o una derivación). Lo que sigue depende de vos:

Crear un ticket en tu sistema con la conversación como contexto — es lo que hace MelonHelp Tickets.
Avisar a tu equipo por el canal que uses.
Dejar de consultar a la IA en ese hilo: si ya dijo que no puede, volver a preguntarle da lo mismo.

Buenas prácticas

Usa conversationRef para que el agente tenga contexto del hilo; sin él, cada llamada arranca de cero.
No vuelvas a llamar tras needs_human: true en la misma conversación.
Guarda la respuesta: el mismo mensaje puede dar respuestas distintas si tu conocimiento cambió.
Las conversaciones por API cuentan para el límite de tu plan (planes).

Todo queda registrado en Agents

Cada llamada crea una conversación en Melonhelp Agents, así ves lo que respondió el bot, sus métricas, y los knowledge gaps de lo que no supo — igual que con el widget.

Problemas comunes

401 invalid_api_key — la clave está mal o fue revocada. Genera una nueva en Settings → API.
404 agent_not_found — no tienes agentes publicados, o el agentId no existe en tu workspace.
502 answer_failed — el servicio de IA no pudo responder; reintenta con backoff.

Relacionado: Autenticación · Límites y errores · Conectar Tickets ↔ Agents