Conversaciones

Las conversaciones agrupan todos los mensajes entre tu organizacion y un contacto.

Listar Conversaciones

curl -X GET "https://api.mirlo.com/v2/messages/organizations/{organization_id}/conversations" \
  -H "X-API-Key: sk_live_tu_api_key"

Parametros de Query

Parametro	Tipo	Descripcion
`skip`	number	Registros a saltar (paginacion). Default: 0
`take`	number	Registros a retornar. Default: 20
`search`	string	Buscar por nombre o direccion del contacto
`status`	string	Filtrar por estado: `active`, `closed`, `archived`
`contact_id`	UUID	Filtrar por contacto
`service`	string	Filtrar por servicio. Separar con coma para multiples (ej. `whatsapp,messenger`)
`labels`	string	Filtrar por etiquetas (separadas por coma). Retorna conversaciones con CUALQUIERA de las etiquetas
`no_labels`	`true` \| `false`	Si `true`, retorna solo conversaciones sin etiquetas. Tiene prioridad sobre `labels`
`assigned_member_id`	UUID	Filtrar por agente asignado
`organization_address`	string	Filtrar por numero de la organizacion (ej. `+521234567890`)
`since`	string	Conversaciones desde esta fecha (ISO 8601)
`until`	string	Conversaciones hasta esta fecha (ISO 8601)
`date_field`	string	Campo para filtrar por fecha: `created_at` (default) o `last_message_timestamp`
`order_by`	string	Campo para ordenar. Default: `last_message_timestamp`
`order`	string	Direccion: `asc` o `desc`. Default: `desc`
`broadcast_id`	UUID	Filtrar por campana de broadcast
`is_broadcast`	`true` \| `false`	Si `true`, solo conversaciones iniciadas por broadcast
`crm_contact_id`	string	Filtrar por ID de contacto en el CRM
`include_messages`	number	Incluir los ultimos N mensajes por conversacion (max: 50)

Response

{
  "data": [
    {
      "id": "37c9df0b-4ebe-4a23-a119-1fbab2e0d29f",
      "organization_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "organization_address": "100000000000001",
      "contact_address": "+521234567890",
      "service": "whatsapp",
      "status": "active",
      "extra": {
        "member_id": "m1m2m3m4-m5m6-m7m8-m9m0-mambnmcndme",
        "labels": ["vip", "soporte"]
      },
      "last_message_at": "2026-01-22T18:30:00.000Z",
      "contact": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Juan Perez",
        "address": "+521234567890"
      }
    }
  ],
  "total": 45,
  "skip": 0,
  "take": 20
}

Obtener una Conversacion

curl -X GET "https://api.mirlo.com/v2/messages/organizations/{organization_id}/conversations/{conversation_id}" \
  -H "X-API-Key: sk_live_tu_api_key"

Actualizar una Conversacion

Permite modificar datos de una conversacion existente, incluyendo asignacion de agentes, etiquetas y archivado.

curl -X PATCH "https://api.mirlo.com/v2/messages/organizations/{organization_id}/conversations/{conversation_id}" \
  -H "X-API-Key: sk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "extra": {
      "labels": ["vip", "soporte"]
    }
  }'

Campos actualizables

Campo	Tipo	Descripcion
`name`	string	Nombre o titulo de la conversacion
`status`	string	Estado: `active` o `closed`
`extra`	object	Datos adicionales (ver abajo)

Campos de `extra`

Campo	Tipo	Descripcion
`member_id`	UUID \| null	ID del agente asignado. `null` para desasignar
`labels`	string[]	Etiquetas de la conversacion
`archived`	string \| null	Timestamp ISO 8601 para archivar. `null` para desarchivar
`team_id`	UUID \| null	ID del equipo asignado
`team_name`	string \| null	Nombre del equipo asignado

Los campos de extra se mezclan con los valores existentes. No es necesario enviar todos los campos, solo los que quieras modificar.

Eliminar una Conversacion

curl -X DELETE "https://api.mirlo.com/v2/messages/organizations/{organization_id}/conversations/{conversation_id}" \
  -H "X-API-Key: sk_live_tu_api_key"

Archivar Conversaciones

Existen dos formas de archivar una conversacion, dependiendo de si quieres preservar o limpiar la asignacion actual.

Archivar y limpiar (recomendado)

Archiva la conversacion, desasigna al agente, limpia el equipo y las etiquetas. La conversacion queda lista para empezar de cero si el contacto vuelve a escribir.

curl -X PATCH "https://api.mirlo.com/v2/messages/organizations/{organization_id}/conversations/{conversation_id}" \
  -H "X-API-Key: sk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "extra": {
      "archived": "2026-01-22T18:30:00.000Z",
      "member_id": null,
      "assignment": null,
      "team_id": null,
      "team_name": null,
      "labels": []
    }
  }'

Este modo tambien limpia los campos de flujo automatico (flow_id, flow_member_id), de modo que al reactivarse la conversacion pase por el flujo de asignacion desde cero.

Archivar preservando datos

Archiva la conversacion pero mantiene el agente asignado, equipo y etiquetas. Util para archivar temporalmente sin perder contexto.

curl -X PATCH "https://api.mirlo.com/v2/messages/organizations/{organization_id}/conversations/{conversation_id}" \
  -H "X-API-Key: sk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "extra": {
      "archived": "2026-01-22T18:30:00.000Z"
    }
  }'

Desarchivar

Para desarchivar manualmente una conversacion, envia archived: null:

curl -X PATCH "https://api.mirlo.com/v2/messages/organizations/{organization_id}/conversations/{conversation_id}" \
  -H "X-API-Key: sk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "extra": {
      "archived": null
    }
  }'

Las conversaciones archivadas se desarchivan automaticamente cuando el contacto envia un nuevo mensaje. No es necesario desarchivar manualmente en ese caso.

Asignar un Agente

Asigna un miembro del equipo a la conversacion:

curl -X PATCH "https://api.mirlo.com/v2/messages/organizations/{organization_id}/conversations/{conversation_id}" \
  -H "X-API-Key: sk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "extra": {
      "member_id": "m1m2m3m4-m5m6-m7m8-m9m0-mambnmcndme"
    }
  }'

Para desasignar, envia "member_id": null.

Al asignar un agente se crea automaticamente un registro de asignacion con timestamp. Al desasignar o archivar, se actualiza el conteo de interacciones activas del miembro.

Asignar a un Equipo

Transfiere la conversacion a un equipo. El sistema busca un miembro disponible del equipo y le asigna la conversacion automaticamente.

curl -X POST "https://api.mirlo.com/v2/messages/organizations/{organization_id}/conversations/{conversation_id}/assign-team" \
  -H "X-API-Key: sk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "t1t2t3t4-t5t6-t7t8-t9t0-tatbtctdtet",
    "team_name": "Soporte Nivel 2"
  }'

Campo	Tipo	Requerido	Descripcion
`team_id`	UUID	Si	ID del equipo destino
`team_name`	string	No	Nombre del equipo (para referencia)

Notas

Las notas permiten agregar comentarios internos a una conversacion que no son visibles para el contacto.

Crear una Nota

curl -X POST "https://api.mirlo.com/v2/messages/organizations/{organization_id}/conversations/{conversation_id}/notes" \
  -H "X-API-Key: sk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Cliente solicito seguimiento la proxima semana",
    "member_id": "m1m2m3m4-m5m6-m7m8-m9m0-mambnmcndme",
    "organization_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }'

Campo	Tipo	Requerido	Descripcion
`content`	string	Si	Contenido de la nota
`member_id`	string	No	ID del miembro que crea la nota
`organization_id`	string	Si	ID de la organizacion
`actor`	string	No	Identificador del actor (ej. nombre del agente)

Listar Notas

curl -X GET "https://api.mirlo.com/v2/messages/organizations/{organization_id}/conversations/{conversation_id}/notes" \
  -H "X-API-Key: sk_live_tu_api_key"

Eliminar una Nota

curl -X DELETE "https://api.mirlo.com/v2/messages/organizations/{organization_id}/conversations/{conversation_id}/notes/{note_id}" \
  -H "X-API-Key: sk_live_tu_api_key"

Eventos (Audit Trail)

Obtiene el historial de eventos de una conversacion: asignaciones, cambios de etiquetas, archivados, etc.

curl -X GET "https://api.mirlo.com/v2/messages/organizations/{organization_id}/conversations/{conversation_id}/events" \
  -H "X-API-Key: sk_live_tu_api_key"

Parametros de Query

Parametro	Tipo	Descripcion
`types`	string	Filtrar por tipo de evento (separados por coma): `assignment`, `label_added`, `label_removed`

Response

[
  {
    "id": "evt-123",
    "conversation_id": "37c9df0b-4ebe-4a23-a119-1fbab2e0d29f",
    "type": "assignment",
    "data": {
      "member_id": "m1m2m3m4-m5m6-m7m8-m9m0-mambnmcndme",
      "assigned_by": "manual"
    },
    "created_at": "2026-01-22T18:30:00.000Z"
  }
]

Etiquetas Enriquecidas

Retorna las etiquetas de una conversacion junto con sus asociaciones a secuencias/flujos automaticos.

curl -X GET "https://api.mirlo.com/v2/messages/organizations/{organization_id}/conversations/{conversation_id}/labels/enriched" \
  -H "X-API-Key: sk_live_tu_api_key"

Response

{
  "labels": [
    {
      "name": "vip",
      "source": "messages",
      "isApplied": true,
      "sequences": {
        "triggers": [
          { "flowId": "flow-123", "name": "VIP Onboarding", "status": "active" }
        ],
        "interrupts": []
      }
    }
  ]
}

Direcciones por Etiqueta

Obtiene las direcciones de contacto (numeros de telefono) de todas las conversaciones que tienen una etiqueta especifica. Util para crear listas de destinatarios para broadcasts.

curl -X GET "https://api.mirlo.com/v2/messages/organizations/{organization_id}/conversations/addresses-by-label?label=vip&organization_id={organization_id}" \
  -H "X-API-Key: sk_live_tu_api_key"

Parametros de Query

Parametro	Tipo	Requerido	Descripcion
`label`	string	Si	Nombre de la etiqueta
`organization_id`	UUID	Si	ID de la organizacion

Response

{
  "addresses": ["+521234567890", "+529876543210"]
}

Estados de Conversacion

Estado	Descripcion
`active`	Conversacion activa con mensajes recientes
`closed`	Conversacion cerrada

El archivado no es un valor del campo status. Una conversacion archivada tiene status: "active" pero con extra.archived establecido. Para filtrar conversaciones archivadas, usa el parametro status=archived en el listado, que internamente filtra por el campo extra.

Referencia de Endpoints

Todos bajo https://api.mirlo.com/v2/messages/organizations/{organization_id}

Metodo	Endpoint	Descripcion
GET	`.../conversations`	Listar conversaciones
GET	`.../conversations/{id}`	Obtener una conversacion
PATCH	`.../conversations/{id}`	Actualizar conversacion (extra, status, name)
DELETE	`.../conversations/{id}`	Eliminar una conversacion
POST	`.../conversations/{id}/assign-team`	Transferir a un equipo
POST	`.../conversations/{id}/notes`	Crear nota
GET	`.../conversations/{id}/notes`	Listar notas
DELETE	`.../conversations/{id}/notes/{note_id}`	Eliminar nota
GET	`.../conversations/{id}/events`	Historial de eventos
GET	`.../conversations/{id}/labels/enriched`	Etiquetas con secuencias
GET	`.../conversations/addresses-by-label`	Direcciones por etiqueta

En esta pagina