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).
`attachments`	No	Imágenes o PDF que acompañan al mensaje (comprobantes, capturas, facturas). El agente los lee y responde. Ver Adjuntos.

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`.

Adjuntos: imágenes y PDF

Si tu usuario manda una imagen (foto, captura, comprobante) o un PDF (factura, contrato), pásalos en attachments y el agente los lee y responde: transcribe el texto visible (montos, fechas, números de pedido) y entiende de qué se trata — sin que tengas que hacer OCR por tu cuenta.

curl -X POST https://agents.melonhelp.com/v1/answer \
  -H "X-API-Key: mh_tu_clave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "¿Me sirve este comprobante para el reembolso?",
    "conversationRef": "pedido-4821",
    "attachments": [
      {
        "mime": "image/jpeg",
        "filename": "comprobante.jpg",
        "contentBase64": "/9j/4AAQSkZJRgABAQ..."
      }
    ]
  }'

Cada adjunto:

Campo	Requerido	Qué es
`mime`	Sí	Tipo del archivo: `image/jpeg`, `image/png`, `application/pdf`, etc.
`contentBase64`	Sí	El archivo en base64, sin el prefijo `data:...;base64,`.
`filename`	No	Nombre del archivo (mejora el contexto y queda en el registro).

Detalles a tener en cuenta:

Formatos legibles: imágenes (image/*) y PDF. Otros formatos (video, etc.) se ignoran.
Audio, no: las notas de voz mándalas ya transcriptas dentro de message — la API no transcribe audio.
Límites: hasta 5 adjuntos por llamada, ~15 MB cada uno.
Si no se puede leer ningún adjunto (formato no soportado, imagen ilegible), el agente aplica su política de fallback y needs_human sale según tu configuración.
El archivo se usa solo para responder ese mensaje: no lo almacenamos. En el registro de la conversación queda el nombre y el tipo, no el archivo.

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