Campos disponibles

Esta guía responde la pregunta más frecuente al integrar: "¿qué puedo obtener de cada conversación y dónde está?". Los ejemplos usan GET /api/v1/accounts/{account_id}/conversations/{conversation_id} y GET .../conversations/{conversation_id}/messages.

Mapa de campos

Dato	Dónde está	Notas
Id de conversación	`id`	Es el número que ves en la URL del panel.
Bandeja / línea	`inbox_id`	El detalle de la bandeja (nombre, teléfono, tipo) está en `GET .../inboxes/{id}`.
Canal	`meta.channel`	`Channel::Whatsapp`, `Channel::FacebookPage`, `Channel::Api`, `Channel::WebWidget`, `Channel::Email`, etc. Algunas conexiones de Instagram usan `Channel::FacebookPage`; otras usan un canal propio o externo. Revisá la bandeja y sus metadatos.
Nombre y teléfono del contacto	`meta.sender.name`, `meta.sender.phone_number`	También `email`, `identifier` y `additional_attributes` del contacto.
Campaña / anuncio de origen	`additional_attributes.meta_referral`	Cuando se registró un origen de Meta; la actualización depende del canal. Ver origen de anuncios.
Agente asignado	`meta.assignee`	`id`, `name`, `email`, `availability_status`. Puede faltar si no está asignada.
Cuándo se asignó y quién asignó	Mensaje de actividad `"Asignado a {agente} por {usuario}"`	Ver mensajes de actividad.
Hilo completo de mensajes	`GET .../messages`	Timestamp, autor, texto, adjuntos, si es privado.
Etiquetas	`labels`	Array de strings.
Estado	`status`	`open`, `pending`, `snoozed`, `resolved`.
Eventos de estado (apertura, resolución, reapertura, con autor y fecha)	Mensajes de actividad + webhook `conversation_status_changed`	Ver abajo.
Notas privadas	Mensajes con `private: true`	Vienen en el mismo hilo.
Prioridad	`priority`	`urgent`, `high`, `medium`, `low` o `null`.
Atributos personalizados	`custom_attributes`	Los que definiste en Ajustes → Atributos personalizados.
Fechas	`created_at`, `last_activity_at`, `first_reply_created_at`, `waiting_since`	Epoch en segundos.

Ejemplo recortado de una conversación:

{
  "id": 4821,
  "inbox_id": 12,
  "status": "resolved",
  "labels": ["presupuesto-enviado", "lead-ads"],
  "priority": null,
  "created_at": 1725292800,
  "additional_attributes": {
    "meta_referral": {
      "source_type": "ad",
      "source_id": "120211234567890",
      "headline": "Cocinas a medida",
      "body": "Pedí tu presupuesto sin cargo",
      "ctwa_clid": "ARAkP...",
      "captured_at": "2026-09-02T14:00:00Z"
    }
  },
  "meta": {
    "channel": "Channel::Whatsapp",
    "sender": { "id": 991, "name": "Ana Pérez", "phone_number": "+5491155551234" },
    "assignee": { "id": 7, "name": "Lucía", "email": "lucia@empresa.com" }
  }
}

Mensajes

GET .../conversations/{conversation_id}/messages devuelve los últimos 20 mensajes; para ir hacia atrás pasá ?before={id_del_mensaje_más_viejo}. Cada mensaje tiene:

Campo	Significado
`id`	Id del mensaje.
`created_at`	Epoch en segundos.
`message_type`	`0` entrante (cliente), `1` saliente (agente o bot), `2` actividad (sistema), `3` template.
`sender`	Quién lo escribió. `sender.type` es `contact` (cliente), `user` (agente) o `agent_bot` (bot). En mensajes de actividad no hay `sender`.
`content`	Texto del mensaje. Para actividades, el texto del evento.
`private`	`true` si es una nota privada (no se envió al cliente).
`content_type`	`text`, `input_select`, `cards`, `form`, etc.
`content_attributes`	Datos extra según el canal (por ejemplo, a qué mensaje responde).
`attachments[]`	Adjuntos con `file_type` (`image`, `audio`, `video`, `file`, `location`, `contact`, `share`, `story_mention`), `data_url` y `thumb_url`.
`status`	`sent`, `delivered`, `read` o `failed` en salientes.

Para distinguir el autor declarado, mirá sender.type. agent_bot identifica un AgentBot; user identifica un usuario, que también puede ser el dueño de un token usado por una integración. No asumas que todo user fue escrito manualmente.

Mensajes de actividad

Los cambios de asignación, estado, etiquetas y prioridad quedan registrados como mensajes con message_type: 2 dentro del mismo hilo, con created_at y el texto del evento en el idioma de la cuenta:

Evento	Texto (español)
Asignación	`Asignado a {agente} por {usuario}`
Autoasignación	`{usuario} auto-asignado a esta conversación`
Desasignación	`Conversación no asignada por {usuario}`
Asignación a equipo	`Asignado a {equipo} por {usuario}`
Resolución	`La conversación fue marcada como resuelta por {usuario}`
Reapertura	`La conversación fue reabierta por {usuario}`
Pendiente / pospuesta	`La conversación fue marcada como pendiente por {usuario}` / `La conversación fue pospuesta por {usuario}`
Resolución automática	`La conversación fue marcada por el sistema debido a {n} días de inactividad`
Reapertura automática	`El sistema reabrió la conversación debido a un nuevo mensaje entrante.`
Etiquetas	`{usuario} agregó {etiquetas}` / `{usuario} eliminó a {etiquetas}`
Prioridad	`{usuario} estableció la prioridad a {prioridad}` / `{usuario} eliminó la prioridad`

Los textos dependen del idioma de la cuenta (los de arriba son los de español). Cuando lo hace una regla de automatización o el bot, el texto lo indica en lugar del nombre de un usuario. Si necesitás estos eventos estructurados en lugar de texto, usá los webhooks conversation_updated y conversation_status_changed, que traen changed_attributes con el valor anterior y el nuevo.

Escritura

Acción	Request
Agregar nota privada	`POST .../conversations/{id}/messages` con `{"content": "texto", "message_type": "outgoing", "private": true}`
Enviar mensaje al cliente	Igual, con `"private": false` (respeta la ventana de 24 h de WhatsApp; fuera de ella hay que usar un template).
Aplicar etiquetas	`POST .../conversations/{id}/labels` con `{"labels": ["etiqueta-1"], "mode": "append"}`. Sin `mode` reemplaza el conjunto completo.
Asignar agente	`POST .../conversations/{id}/assignments` con `{"assignee_id": 7}` (o `{"team_id": 3}`).
Cambiar estado	`POST .../conversations/{id}/toggle_status` con `{"status": "resolved"}`.
Prioridad	`POST .../conversations/{id}/toggle_priority` con `{"priority": "high"}`.
Atributos personalizados	`POST .../conversations/{id}/custom_attributes` con `{"custom_attributes": {"clave": "valor"}}`. Reemplaza el objeto completo: conservá las otras claves.
Nota en el contacto	`POST .../contacts/{contact_id}/notes` con `{"content": "texto"}`.

Administrá las etiquetas de la cuenta desde Ajustes → Etiquetas o POST .../labels. Para ejemplos completos y semántica de reemplazo, consultá gestionar conversaciones.

IDs, fechas y revisiones

Campo	Cómo usarlo
`id` de conversación	ID público relativo a la cuenta. Enlazalo siempre con `account_id`; no uses el ID interno de una base de datos.
`conversation_id` de mensaje por API	El mismo ID público de conversación.
`created_at`, `last_activity_at` por API	Epoch en segundos. Multiplicá por 1.000 para `new Date(...)` en JavaScript.
`created_at` de un evento de mensaje	ISO 8601. En los eventos de conversación, `created_at` sigue siendo epoch.
`snoozed_until`	Puede ser una fecha ISO 8601 o `null`.
`history_revision`	Revisión opaca del historial cuando la instalación la incluye. Puede cambiar por creación, edición o borrado de mensajes. Compará igualdad; no la interpretes como una fecha ni como un cursor.

Los campos opcionales pueden faltar o venir en null. En algunas fechas calculadas, la ausencia aparece como 0; no la conviertas en una fecha de negocio válida. No confundas meta.channel de la respuesta REST con channel en la raíz de un webhook de conversación.