Conversaciones

Hilos de conversación con un contacto en un número. Asignación, cierre, etiquetas, notas internas.

Base path: /organizations/:orgId/conversations·33 endpoints·Source: mosend-wb-backend/src/modules/conversations/conversations.controller.ts

GET/organizations/:orgId/conversations

bearer

Lista conversaciones del inbox con filtros por estado, número, asignado, etiqueta y no leídas.

Path params

orgIdstringrequerido

Query params

statusstringrequerido
phoneNumberIdstringrequerido
assigneeUserIdstringrequerido
tagIdstringrequerido
unreadOnlystringrequerido
handoffPendingstringrequerido
takestringrequerido
cursorstringrequerido
searchstringrequerido
resolutionOutcomestringrequerido

Respuestas

curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "createdAt": "2026-05-01T03:42:18.123Z"
    }
  ],
  "timestamp": "2026-05-01T03:42:18.123Z"
}

GET/organizations/:orgId/conversations/messaging-settings

bearer

Obtiene los ajustes de mensajería de la org (read receipts, indicador de escritura).

Path params

orgIdstringrequerido

Respuestas

curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/messaging-settings' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

PATCH/organizations/:orgId/conversations/messaging-settings

bearer

Actualiza los ajustes de mensajería de la org (read receipts, indicador de escritura, pestañas del inbox).

Path params

orgIdstringrequerido

Respuestas

curl -X PATCH 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/messaging-settings' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

GET/organizations/:orgId/conversations/unread-counts

bearer

Devuelve los conteos de no leídas por estado para los badges del inbox.

Path params

orgIdstringrequerido

Query params

phoneNumberIdstringrequerido

Respuestas

curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/unread-counts' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "createdAt": "2026-05-01T03:42:18.123Z"
    }
  ],
  "timestamp": "2026-05-01T03:42:18.123Z"
}

GET/organizations/:orgId/conversations/search

bearer

Busca dentro del contenido de los mensajes de la org con filtros por fecha, dirección y adjunto.

Path params

orgIdstringrequerido

Query params

qstringrequerido
fromstringrequerido
tostringrequerido
directionstringrequerido
hasAttachmentstringrequerido
sentByMestringrequerido
conversationIdstringrequerido

Respuestas

curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/search' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "createdAt": "2026-05-01T03:42:18.123Z"
    }
  ],
  "timestamp": "2026-05-01T03:42:18.123Z"
}

GET/organizations/:orgId/conversations/workload

bearer

Lista métricas de carga y performance reciente por agente (requiere reports:read).

Path params

orgIdstringrequerido

Respuestas

curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/workload' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

GET/organizations/:orgId/conversations/workload/settings

bearer

Obtiene la configuración del panel de workload (thresholds de SLA y staleness).

Path params

orgIdstringrequerido

Respuestas

curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/workload/settings' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

PATCH/organizations/:orgId/conversations/workload/settings

bearer

Actualiza parcialmente la configuración del panel de workload (thresholds).

Path params

orgIdstringrequerido

Respuestas

curl -X PATCH 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/workload/settings' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

GET/organizations/:orgId/conversations/notification-settings

bearer

Obtiene la configuración de notificaciones por correo (retraso de conversación).

Path params

orgIdstringrequerido

Respuestas

curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/notification-settings' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

PATCH/organizations/:orgId/conversations/notification-settings

bearer

Actualiza parcialmente la configuración de notificaciones por correo (retraso de conversación).

Path params

orgIdstringrequerido

Respuestas

curl -X PATCH 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/notification-settings' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

GET/organizations/:orgId/conversations/workload/agent/:userId

bearer

Detalle de workload de un agente: agregados y tenencias de los últimos N días.

Path params

orgIdstringrequerido
userIdstringrequerido

Query params

daysstringrequerido
fromstringrequerido
tostringrequerido

Respuestas

curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/workload/agent/00000000-0000-0000-0000-000000000000' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "createdAt": "2026-05-01T03:42:18.123Z"
    }
  ],
  "timestamp": "2026-05-01T03:42:18.123Z"
}

GET/organizations/:orgId/conversations/activity-trends

bearer

Serie temporal de conversaciones entrantes y cerradas por día (?days=N).

Path params

orgIdstringrequerido

Query params

daysstringrequerido

Respuestas

curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/activity-trends' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "createdAt": "2026-05-01T03:42:18.123Z"
    }
  ],
  "timestamp": "2026-05-01T03:42:18.123Z"
}

GET/organizations/:orgId/conversations/activity-heatmap

bearer

Heatmap día-de-semana × hora de actividad (?metric=volume|late|avgResponse).

Path params

orgIdstringrequerido

Query params

daysstringrequerido
metricstringrequerido

Respuestas

curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/activity-heatmap' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "createdAt": "2026-05-01T03:42:18.123Z"
    }
  ],
  "timestamp": "2026-05-01T03:42:18.123Z"
}

GET/organizations/:orgId/conversations/:id

bearer

Obtiene el detalle de una conversación por su id.

Path params

orgIdstringrequerido
idstringrequerido

Respuestas

curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/00000000-0000-0000-0000-000000000000' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

GET/organizations/:orgId/conversations/:id/messages

bearer

Lista los mensajes de una conversación con paginación por cursor.

Path params

orgIdstringrequerido
idstringrequerido

Query params

limitstringrequerido
beforestringrequerido
aroundstringrequerido

Respuestas

curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/00000000-0000-0000-0000-000000000000/messages' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "createdAt": "2026-05-01T03:42:18.123Z"
    }
  ],
  "timestamp": "2026-05-01T03:42:18.123Z"
}

GET/organizations/:orgId/conversations/:id/media

bearer

Lista mensajes de media de una conversación filtrados por categoría (image|video|audio|doc).

Path params

orgIdstringrequerido
idstringrequerido

Query params

categorystringrequerido
limitstringrequerido
beforestringrequerido

Respuestas

curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/00000000-0000-0000-0000-000000000000/media' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "createdAt": "2026-05-01T03:42:18.123Z"
    }
  ],
  "timestamp": "2026-05-01T03:42:18.123Z"
}

GET/organizations/:orgId/conversations/:id/media/counts

bearer

Conteos de media por categoría (image/video/audio/doc/links) para los tabs de Galería.

Path params

orgIdstringrequerido
idstringrequerido

Respuestas

curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/00000000-0000-0000-0000-000000000000/media/counts' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

GET/organizations/:orgId/conversations/:id/links

bearer

Lista URLs encontradas en mensajes de texto de la conversación (sub-tab Links de Galería).

Path params

orgIdstringrequerido
idstringrequerido

Query params

limitstringrequerido
beforestringrequerido

Respuestas

curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/00000000-0000-0000-0000-000000000000/links' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "createdAt": "2026-05-01T03:42:18.123Z"
    }
  ],
  "timestamp": "2026-05-01T03:42:18.123Z"
}

PATCH/organizations/:orgId/conversations/:id/status

bearer

Cambia el estado de la conversación (open/closed/snoozed); al cerrar acepta category y resolución.

Path params

orgIdstringrequerido
idstringrequerido

Respuestas

curl -X PATCH 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/00000000-0000-0000-0000-000000000000/status' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

POST/organizations/:orgId/conversations/:id/request-handoff

bearer

Solicita handoff a un asesor humano: marca pendiente, calla la automatización y notifica.

Path params

orgIdstringrequerido
idstringrequerido

Body (JSON)

reasonstring
Se acepta por compatibilidad; el origen queda registrado como «api».
detailstring
Texto libre para el registro y el webhook («cliente pidió hablar con ventas»).

Respuestas

curl -X POST 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/00000000-0000-0000-0000-000000000000/request-handoff' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>' \
  -H 'Content-Type: application/json' \
  -d '{"reason": "<reason>","detail": "<detail>"}'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "description": "string"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

PATCH/organizations/:orgId/conversations/:id/categorize

bearer

Asigna o corrige category y resolución de la conversación sin cambiar su estado.

Path params

orgIdstringrequerido
idstringrequerido

Respuestas

curl -X PATCH 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/00000000-0000-0000-0000-000000000000/categorize' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

POST/organizations/:orgId/conversations/:id/read

bearer

Marca la conversación como leída.

Path params

orgIdstringrequerido
idstringrequerido

Respuestas

curl -X POST 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/00000000-0000-0000-0000-000000000000/read' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

POST/organizations/:orgId/conversations/:id/unread

bearer

Marca la conversación como no leída.

Path params

orgIdstringrequerido
idstringrequerido

Respuestas

curl -X POST 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/00000000-0000-0000-0000-000000000000/unread' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

POST/organizations/:orgId/conversations/:id/typing

bearer

Envía el indicador de "escribiendo" al contacto de la conversación.

Path params

orgIdstringrequerido
idstringrequerido

Respuestas

curl -X POST 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/00000000-0000-0000-0000-000000000000/typing' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

PATCH/organizations/:orgId/conversations/:id/assign

bearer

Asigna la conversación a un usuario o la libera (userId null).

Path params

orgIdstringrequerido
idstringrequerido

Body (JSON)

userIdstring · uuidrequerido
Usuario al que se asigna; null la libera.

Respuestas

curl -X PATCH 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/00000000-0000-0000-0000-000000000000/assign' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>' \
  -H 'Content-Type: application/json' \
  -d '{"userId": "00000000-0000-0000-0000-000000000000"}'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "description": "string"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

POST/organizations/:orgId/conversations/:id/claim

bearer

El usuario actual toma posesión de la conversación (autoasignación).

Path params

orgIdstringrequerido
idstringrequerido

Respuestas

curl -X POST 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/00000000-0000-0000-0000-000000000000/claim' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

PATCH/organizations/:orgId/conversations/:id/agent

bearer

Fija qué agente del bot atiende la conversación (agentId null = que decida el enrutador).

Path params

orgIdstringrequerido
idstringrequerido

Body (JSON)

agentIdstring · uuidrequerido
Agente del bot que atiende; null deja decidir al enrutador.

Respuestas

curl -X PATCH 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/00000000-0000-0000-0000-000000000000/agent' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>' \
  -H 'Content-Type: application/json' \
  -d '{"agentId": "00000000-0000-0000-0000-000000000000"}'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "description": "string"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

POST/organizations/:orgId/conversations/:id/devolver-al-bot

bearer

Devuelve la conversación al bot (reactiva el bot conservando el contexto).

Path params

orgIdstringrequerido
idstringrequerido

Respuestas

curl -X POST 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/00000000-0000-0000-0000-000000000000/devolver-al-bot' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

POST/organizations/:orgId/conversations/bulk-assign

bearer

Reasigna en lote varias conversaciones a un usuario o las libera.

Path params

orgIdstringrequerido

Body (JSON)

conversationIdsstring[]requerido
userIdstring · uuidrequerido
Usuario destino; null libera las conversaciones.

Respuestas

curl -X POST 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/bulk-assign' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>' \
  -H 'Content-Type: application/json' \
  -d '{"conversationIds": [],"userId": "00000000-0000-0000-0000-000000000000"}'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "description": "string"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

PATCH/organizations/:orgId/conversations/:id/snooze

bearer

Pospone la conversación hasta una fecha, o cancela el snooze (until null).

Path params

orgIdstringrequerido
idstringrequerido

Body (JSON)

untilstring
Fecha ISO hasta la que se pospone. null = reactivar ahora.
notestring
Motivo del snooze (visible al reabrirse).

Respuestas

curl -X PATCH 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/00000000-0000-0000-0000-000000000000/snooze' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>' \
  -H 'Content-Type: application/json' \
  -d '{"until": "<until>","note": "<note>"}'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "description": "string"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

PATCH/organizations/:orgId/conversations/:id/pin

bearer

Fija o desfija la conversación en el inbox.

Path params

orgIdstringrequerido
idstringrequerido

Body (JSON)

pinnedbooleanrequerido

Respuestas

curl -X PATCH 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/00000000-0000-0000-0000-000000000000/pin' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>' \
  -H 'Content-Type: application/json' \
  -d '{"pinned": true}'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "description": "string"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

POST/organizations/:orgId/conversations/:id/tags

bearer

Agrega una etiqueta a la conversación.

Path params

orgIdstringrequerido
idstringrequerido

Body (JSON)

tagIdstring · uuidrequerido

Respuestas

curl -X POST 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/00000000-0000-0000-0000-000000000000/tags' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>' \
  -H 'Content-Type: application/json' \
  -d '{"tagId": "00000000-0000-0000-0000-000000000000"}'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "cliente-vip",
    "color": "#16a34a"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

DELETE/organizations/:orgId/conversations/:id/tags/:tagId

bearer

Quita una etiqueta de la conversación.

Path params

orgIdstringrequerido
idstringrequerido
tagIdstringrequerido

Respuestas

curl -X DELETE 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/conversations/00000000-0000-0000-0000-000000000000/tags/00000000-0000-0000-0000-000000000000' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'

Response · 200

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}