Mensajes

Verificar Ventana de Conversacion (24h)

WhatsApp permite enviar mensajes de texto libre solo dentro de una ventana de 24 horas desde el ultimo mensaje del contacto. Fuera de esa ventana, unicamente puedes iniciar conversacion con un template aprobado por Meta.

Este endpoint te dice si la ventana esta abierta o cerrada. Solo necesitas el numero de telefono.

Flujo recomendado

Consulta la ventana del contacto
Ventana open — envia texto libre con POST .../messages
Ventana closed — envia un template con POST .../messages/send-template

Endpoint

GET /v2/messages/organizations/{organization_id}/contacts/addresses/{address}/service-window?organization_address={org_address}

Parametro	Tipo	Ubicacion	Descripcion
`organization_id`	string	Path *	UUID de tu organizacion
`address`	string	Path *	Numero del contacto (ej: 5215512345678)
`organization_address`	string	Query *	Phone Number ID de tu numero de WhatsApp

Ejemplo:

curl -X GET "https://api.mirlo.com/v2/messages/organizations/{organization_id}/contacts/addresses/5215512345678/service-window?organization_address=100000000000001" \
  -H "X-API-Key: sk_live_tu_api_key"

Response:

{
  "status": "open"
}

Status	Significado	Accion
`open`	Ventana activa (ultimo mensaje entrante hace menos de 24h)	Enviar texto libre
`closed`	Ventana cerrada (mas de 24h sin mensaje entrante)	Enviar template

La ventana de 24h se renueva con cada mensaje entrante del contacto. Consulta este endpoint antes de cada envio para elegir entre texto libre o template.

Enviar Template Message

Envia un mensaje de WhatsApp usando un template de Meta a un solo destinatario. Este es el endpoint mas simple y recomendado para la mayoria de integraciones y automatizaciones.

POST /v2/messages/organizations/{organization_id}/messages/send-template

Request Body

{
  "organization_address": "100000000000001",
  "to": "+525512345678",
  "meta_template_id": "999888777666555",
  "do_not_pause": false,
  "components": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "parameter_name": "nombre_cliente", "text": "Juan Perez" },
        { "type": "text", "parameter_name": "numero_pedido", "text": "#12345" }
      ]
    }
  ]
}

Ejemplo con imagen en header

{
  "organization_address": "100000000000001",
  "to": "+525512345678",
  "meta_template_id": "999888777666555",
  "do_not_pause": true,
  "components": [
    {
      "type": "header",
      "parameters": [
        { "type": "image", "image": { "link": "https://example.com/image.jpg" } }
      ]
    },
    {
      "type": "body",
      "parameters": [
        { "type": "text", "parameter_name": "nombre", "text": "Juan" }
      ]
    }
  ]
}

Parametros

Campo	Tipo	Requerido	Descripcion
`organization_address`	string	Si	Phone Number ID de WhatsApp Business
`to`	string	Si	Numero de telefono del destinatario (formato E.164)
`meta_template_id`	string	Si	ID del template en Meta
`do_not_pause`	boolean	No	Si es `true`, no pausa el agente/bot despues de enviar. Default: `false`
`components`	array	No	Variables del template (header, body, buttons)

Response (201 Created)

{
  "id": "12345678-abcd-1234-efgh-123456789abc",
  "conversation_id": "87654321-dcba-4321-hgfe-cba987654321",
  "external_id": "wamid.HBgNNTIxNTUzOTg3NTg0NhUCABEYEjE4RTZBRUQyRjc3OEQ0NDQ0MwA=",
  "status": {
    "pending": "2026-01-22T20:26:38.569Z",
    "accepted": "2026-01-22T20:26:39.161Z"
  },
  "template_name": "mi_template",
  "template_language": "es"
}

Consultar estado del mensaje

GET /v2/messages/organizations/{organization_id}/messages/{id}

Estado	Descripcion
`pending`	Creado, esperando envio
`accepted`	Aceptado por Meta
`sent`	Enviado
`delivered`	Entregado al dispositivo
`read`	Leido por el usuario
`failed`	Error (ver status.error para detalles)

Errores comunes

Codigo	Mensaje
400	Organization address does not have an access token
400	Parameter name is missing (template usa NAMED params)
404	Organization address not found
404	Failed to get template from Meta

Enviar Mensaje (Texto Libre)

Envia un mensaje de texto directo (sin template) a un destinatario.

Los mensajes sin template solo pueden enviarse dentro de la ventana de 24 horas despues de que el usuario te envio un mensaje. Fuera de esta ventana, debes usar templates.

POST /v2/messages/organizations/{organization_id}/messages

Request Body

{
  "organization_address": "100000000000001",
  "service": "whatsapp",
  "contact_address": "5215512345678",
  "direction": "outgoing",
  "content": {
    "kind": "text",
    "text": "Hola, gracias por contactarnos. En que podemos ayudarte?"
  }
}

Ejemplo enviando imagen

{
  "organization_address": "100000000000001",
  "service": "whatsapp",
  "contact_address": "5215512345678",
  "direction": "outgoing",
  "content": {
    "kind": "image",
    "text": "Aqui esta la imagen que solicitaste",
    "file": {
      "uri": "https://example.com/imagen.jpg",
      "mime_type": "image/jpeg"
    }
  }
}

Parametros

Campo	Tipo	Requerido	Descripcion
`organization_address`	string	Si	Phone Number ID de WhatsApp Business
`service`	string	Si	Servicio: `whatsapp`, `instagram`, `messenger`
`contact_address`	string	Si	Numero de telefono del destinatario (sin prefijo +)
`direction`	string	Si	Usar `outgoing` para enviar mensajes
`content`	object	Si	Objeto con el contenido del mensaje
`content.kind`	string	Si	Tipo: `text`, `image`, `video`, `audio`, `document`
`content.text`	string	Depende	Texto del mensaje (requerido para text, caption para image/video)

Response (201 Created)

{
  "id": "12345678-abcd-1234-efgh-123456789abc",
  "conversation_id": "87654321-dcba-4321-hgfe-cba987654321",
  "external_id": "wamid.HBgNNTIxNTUzOTg3NTg0NhUCABEYEjE4RTZBRUQyRjc3OEQ0NDQ0MwA=",
  "status": {
    "pending": "2026-01-22T20:26:38.569Z",
    "accepted": "2026-01-22T20:26:39.161Z"
  }
}

Errores comunes

Codigo	Mensaje
400	Organization address does not have an access token
400	Message failed to send (fuera de ventana de 24 horas)
404	Organization address not found

Listar Mensajes

GET /v2/messages/organizations/{organization_id}/messages

Parametro	Tipo	Descripcion
`conversation_id`	UUID	Filtrar por conversacion
`direction`	string	Filtrar por direccion (`incoming`, `outgoing`)
`start_date`	ISO 8601	Fecha inicio del rango
`end_date`	ISO 8601	Fecha fin del rango

Ejemplos:

# Obtener ultimos 50 mensajes
curl -X GET "https://api.mirlo.com/v2/messages/organizations/{organization_id}/messages?conversation_id={id}&take=50" \
  -H "X-API-Key: sk_live_tu_api_key"

# Mensajes del ultimo mes
curl -X GET "https://api.mirlo.com/v2/messages/organizations/{organization_id}/messages?conversation_id={id}&start_date=2025-12-22T00:00:00Z&end_date=2026-01-22T23:59:59Z" \
  -H "X-API-Key: sk_live_tu_api_key"

# Solo mensajes entrantes
curl -X GET "https://api.mirlo.com/v2/messages/organizations/{organization_id}/messages?conversation_id={id}&direction=incoming" \
  -H "X-API-Key: sk_live_tu_api_key"

Tipos de Contenido

Tipo	Descripcion
`text`	Mensaje de texto
`image`	Imagen
`video`	Video
`audio`	Audio
`document`	Documento
`location`	Ubicacion
`data + template`	Template de WhatsApp

Referencia Rapida de Endpoints

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

Metodo	Endpoint	Descripcion
POST	`.../messages/send-template`	Enviar template message (recomendado)
POST	`.../messages`	Enviar mensaje de texto (ventana 24h)
GET	`.../messages`	Listar mensajes
GET	`.../messages/{id}`	Obtener un mensaje
GET	`.../contacts/addresses/{address}/service-window`	Verificar ventana de servicio 24h

En esta pagina