MosendDeveloper

Handoff a humano

Si tenés un bot externo que conversa con tus clientes vía la API, podés escalarle una conversación a un asesor humano cuando el cliente lo pida. Un solo POST marca la conversación como "pendiente de asesor" y dispara toda la maquinaria que ya vive en el inbox: badge, push a los asesores, recordatorios y el webhook saliente.

El endpoint

POST /organizations/{orgId}/conversations/{conversationId}/request-handoff
  • Auth: X-Api-Key con scope conversations:write (o una key sin scopes = acceso total).
  • Body opcional: { "detail": "texto libre" } — queda en el log y se incluye en el webhook saliente (ej. "cliente pidió hablar con ventas").
  • Idempotente: si la conversación ya estaba en handoff, no se vuelve a disparar (no duplica push ni mensajes).

Ejemplo

# Bash / curl
curl -X POST \
  "https://api.mosend.dev/organizations/${ORG_ID}/conversations/${CONVERSATION_ID}/request-handoff" \
  -H "X-Api-Key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "detail": "el cliente pidió hablar con un asesor de ventas" }'

# Respuesta (200)
# { "data": { "ok": true }, "timestamp": "..." }
// Node.js (18+)
await fetch(
  `https://api.mosend.dev/organizations/${ORG_ID}/conversations/${conversationId}/request-handoff`,
  {
    method: 'POST',
    headers: { 'X-Api-Key': API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ detail: 'el cliente pidió un asesor' }),
  },
);
# Python
import requests
requests.post(
    f"https://api.mosend.dev/organizations/{ORG_ID}/conversations/{conversation_id}/request-handoff",
    headers={"X-Api-Key": API_KEY, "Content-Type": "application/json"},
    json={"detail": "el cliente pidió un asesor"},
    timeout=15,
)

Qué pasa al dispararlo

Una sola llamada activa, en cadena:

  • La conversación queda marcada como pendiente de asesor: aparece la etiqueta/badge en el inbox y entra al filtro "Pendientes de asesor" en tiempo real.
  • Se silencia cualquier automatización de Mosden sobre esa conversación (bot interno, auto-respuestas), para que no pise al asesor.
  • La conversación queda sin asignar para que cualquier asesor disponible la pueda tomar.
  • Se manda push destacado a los asesores, con recordatorios a los 2, 5 y 10 minutos si nadie la reclama.
  • Si la org configuró un mensaje de handoff, se le envía al cliente automáticamente.
  • Se dispara el webhook saliente conversation.handoff_requested (si tenés uno suscrito) — útil si querés además notificar a Slack, Teams, etc.

Flujo recomendado para un bot externo

  1. Tu bot conversa con el cliente vía POST /messages.
  2. Cuando detectás (con tu propia lógica/IA) que el cliente quiere un humano — por ejemplo escribe "quiero hablar con una persona" — llamás a request-handoff sobre esa conversación.
  3. Tu bot deja de responder en esa conversación (vos controlás eso del lado tuyo).
  4. Los asesores ven la solicitud en el inbox de Mosend y la atienden.

Notas

  • Necesitás el conversationId de Mosend. Lo obtenés de GET /conversations, del webhook message.new (campo data.conversationId), o de la respuesta de POST /messages.
  • Si tu API key tiene scope por phone-number, solo podés escalar conversaciones de los números permitidos.
  • Para recibir la notificación de handoff en tu sistema (en vez de dispararla), suscribite al evento conversation.handoff_requested en Webhooks salientes.