¿Cómo mantengo la bandeja actualizada sin polling?

Con un endpoint de webhook suscrito a message.new y email.new. La página dedicada muestra cómo lo conecta un agente. (function () { var root = document.getElementById('unipile-mcp-ui-faq'); if (!root) return; var buttons = root.querySelectorAll('.umuif-q'); for (var i = 0; i

Unipile MCP · Bandeja unificada

Construya una bandeja unificada con un agente de código

Q: ¿Puede una sola llamada a la API devolver los mensajes de todas las cuentas conectadas?

No, por diseño. account_id forma parte de la ruta, así que se llama una vez por cuenta y se fusiona en su aplicación. Lo que la API unifica es la forma de los objetos, no el número de llamadas. 02

Q: ¿Qué endpoints necesito para una bandeja unificada?

GET /v2/accounts/ para la lista de cuentas, luego GET /v2/{account_id}/chats y GET /v2/{account_id}/emails por cuenta, y después GET /v2/{account_id}/chats/{chat_id}/messages para abrir una conversación. Las respuestas salen por POST /v2/{account_id}/chats/{chat_id}/messages/send y POST /v2/{account_id}/emails/send. 03

Q: ¿Cómo funciona la paginación entre varias cuentas?

Un cursor por cuenta. Cada ruta de listado devuelve data, total_count y next_cursor. Devuelva next_cursor en el parámetro cursor y mantenga un mapa de cursores, uno por cuenta, en el estado de su aplicación. 04

Conversaciones de LinkedIn, WhatsApp y email en una sola lista, con respuesta desde la misma pantalla. Con el Servidor MCP de Unipile, su agente escribe la obtención y la fusión.

Construir una bandeja unificada con un agente Documentación de mensajería

Prueba gratis de 7 días, sin tarjeta.

Crea una bandeja unificada de LinkedIn, WhatsApp y email.

Ejecutar peticiónGET /v2/accounts/3 cuentas

Se ha añadido GET /api/inbox: una llamada por cuenta, un mismo formato de elemento, ordenado por fecha.

3 archivos modificados · 3 canales en una lista

Describa la próxima función…

El objetivo

Lo que quiere conseguir

Mostrar a sus usuarios todas las conversaciones de las cuentas que han conectado en una sola lista, y dejar que respondan sin salir de su producto. Primero lo honesto: account_id está en la ruta de todos los endpoints, así que una bandeja unificada es una llamada por cuenta seguida de una fusión en su aplicación. Lo que la API unifica es la forma de los objetos, no el número de llamadas.

Sin ello Un cliente por proveedor, una forma para cada uno

Un cliente LinkedIn, un cliente WhatsApp y un cliente de email, cada uno con su propio modelo y su propia paginación.

Un único «cargar más» que pierde mensajes en cuanto una cuenta se queda sin páginas antes que las demás.

Una respuesta que sale por la cuenta equivocada porque el chat y la cuenta no se guardaron juntos.

Con el servidor MCP de Unipile El resultado en su aplicación

Una sola lista de conversaciones de LinkedIn, WhatsApp y email, ordenada por fecha, con el canal como etiqueta.

Un «cargar más» que avanza un cursor por cuenta y nunca pierde un mensaje.

Respuesta desde la lista, por la cuenta propietaria del chat, probada en su aplicación de Development.

Prompt, pasos, código

Dé el prompt a su agente

Dos prompts, cada uno con los endpoints de Unipile que el agente lee y ejecuta y lo que llega a su proyecto. Las rutas están completas, sobre la URL base de la API https://api.unipile.com, con su clave con scope en la cabecera X-API-KEY .

Su agente · support-consoleApp de Development

Crea una bandeja unificada de LinkedIn, WhatsApp y email en esta aplicación: lista las cuentas conectadas, obtén una página de chats y una página de emails por cuenta, normalízalas en un único formato de elemento y ordénalas por fecha.

Ejecutar peticiónGET /v2/accounts/3 cuentas

Ejecutar peticiónGET /v2/{account_id}/chats200 · next_cursor

Se ha añadido GET /api/inbox: lista las cuentas, lanza GET /v2/{account_id}/chats y GET /v2/{account_id}/emails en paralelo, lleva ambos a un único InboxItem (id, account_id, canal, interlocutor, vista previa, fecha, no leído) y ordena por fecha. Al abrir un elemento se llama a la ruta de mensajes de ese chat. Ejecutado en la app de Development con una cuenta de prueba de LinkedIn, una de WhatsApp y una de Gmail.4 archivos modificados · probado en la app de Development

Una llamada por cuenta, un formato de elemento, un orden

El agente lee los esquemas Chat y Email a través del servidor y define la forma común mínima: un identificador, una fecha, un remitente, una vista previa y el canal. Todo lo específico de cada proveedor sigue disponible en el objeto original para la vista de detalle. Instagram y Telegram pasan por las mismas rutas de chat, así que un cuarto canal es una cuenta más, no un cliente más.

Endpoints que usa el agente

GET/v2/accounts/GET/v2/{account_id}/chatsGET/v2/{account_id}/emailsGET/v2/{account_id}/chats/{chat_id}/messagesPOST/v2/{account_id}/chats/{chat_id}/messages/sendPOST/v2/{account_id}/emails/send

Error frecuente: Buscar un filtro de consulta account_id. Está en la ruta: una llamada por cuenta y luego la fusión en su aplicación.

Construir la parte de LinkedIn en detalle

Su agente · support-consoleApp de Development

Añade paginación a la bandeja unificada: guarda un cursor por cuenta conectada, avanza cada uno por separado al cargar más y detén una cuenta cuando falte su next_cursor.

Leer endpointGET /v2/{account_id}/chatsdata, total_count, next_cursor

Ejecutar peticiónGET /v2/{account_id}/emails?cursor=…200 OK

Se ha sustituido el offset global por un Map<account_id, next_cursor> guardado en el estado de la bandeja. Cargar más hace avanzar en paralelo todas las cuentas que aún tienen cursor y vuelve a ordenar la lista fusionada. Una cuenta sin next_cursor se marca como agotada y se omite. Verificado con tres cuentas de distintos tamaños en la app de Development.2 archivos modificados · ningún mensaje perdido al cargar más

El envoltorio es el mismo en todas partes: data, total_count, next_cursor

Todas las rutas de listado devuelven el mismo envoltorio. Pase next_cursor en el parámetro cursor para obtener la página siguiente. El contrato indica usar el cursor cuando el proveedor lo admite y offset en caso contrario, y que limit es un máximo, no una garantía: una página corta no es el final de la lista, solo lo es la ausencia de next_cursor .

Endpoints que usa el agente

GET/v2/{account_id}/chatsGET/v2/{account_id}/emailsGET/v2/{account_id}/chats/{chat_id}/participants

Error frecuente: Un solo cursor para toda la bandeja. Cada cuenta pagina con su propio cursor; uno compartido pierde mensajes en cuanto una cuenta termina antes que las demás.

Mantener la lista al día con webhooks

Paginación

Un sobre, un cursor por cuenta

Literal del contrato v2 que el agente lee a través del servidor. Los mismos tres campos vuelven en todas las rutas de listado.

1El sobredata contiene la página, total_count el tamaño cuando el proveedor lo da, next_cursor el token de la página siguiente. La ausencia de next_cursor marca el final de la lista de esa cuenta.GET https://api.unipile.com/v2/{account_id}/chats?limit=20 { "object": "ChatList", "items": [ … ], "cursor": "…" }

2Cursor u offsetUse next_cursor siempre que el proveedor lo admita, y offset en caso contrario. Un código que asume uno de los dos para todos los proveedores se rompe en el primer buzón IMAP.GET https://api.unipile.com/v2/{account_id}/emails?cursor=…&limit=20 GET https://api.unipile.com/v2/{account_id}/chats?offset=40&limit=20

3El mapa de cursoresUna entrada por cuenta en el estado de su aplicación. Cargar más avanza todas las cuentas que aún tienen cursor y descarta las que no han devuelto ninguno.{ "acc_1a…": "eyJ…", "acc_9c…": null, "acc_f2…": "eyJ…" } limit es un máximo, no una garantía

De Development a producción

Pruebe primero en una aplicación de Development

Su dashboard de Unipile separa la aplicación de Development de la de Production. Dé al agente una clave con scope de Development y una cuenta de prueba por canal: tamaños de página reales, sin ningún cliente real.

1Recupere una página por cuentaLinkedIn, WhatsApp y una cuenta de email, fusionadas en una lista ordenada por fecha.

2Responda desde la listaLa llamada de envío sale por la cuenta propietaria del chat.

3Cargue más con cuentas desigualesNingún mensaje perdido, cuentas agotadas omitidas, y solo entonces cambie la clave a Production.

crm-app · DevelopmentUsada por su agente

Scopedev-tests · 2 cuentas

Clavescoped Account API key

CuentasCuenta de prueba LinkedIn, buzón de prueba Gmail

Webhooks1 endpoint · eventos de mensaje

crm-app · ProductionSin tocar

Scopeuno por workspace

Clavescoped keys, in your backend only

Cuentaslas cuentas propias de sus usuarios, vía Hosted Auth

Resolución de problemas

Errores habituales y qué significan

Los cuatro fallos que rompen una bandeja unificada, y cómo se corrige cada uno. Tres tienen que ver con la paginación.

Buscar account_id como filtro de query

Se espera que una sola llamada devuelva todas las cuentas. Soluciónaccount_id está en la ruta. Llame una vez por cuenta y fusione en su aplicación; la API unifica la forma, no el número de llamadas.

Un solo cursor para toda la bandeja

Cargar más pierde mensajes en cuanto una cuenta termina antes que las demás. SoluciónMantenga un mapa de account_id a next_cursor. Avance cada cuenta de forma independiente y detenga las que no han devuelto cursor.

Mezclar cursor y offset

El código funciona en un proveedor y se rompe en otro. SoluciónUse next_cursor cuando el proveedor lo admita y offset en caso contrario, tal como dice el contrato. Lea el sobre de cada cuenta en lugar de darlo por supuesto.

Tratar limit como una garantía

Una página corta se interpreta como el final de la lista. Soluciónlimit es un techo. Solo la ausencia de next_cursor termina la lista de una cuenta; una página con menos ítems de los pedidos no.

6000+ Empresas que innovan con Unipile

La confianza de los líderes del sector

1 API

Racionalizar las operaciones de los principales canales de comunicación

2 días

Rápida integración en directo con una configuración mínima

30%

Reducción de los esfuerzos y recursos de mantenimiento

Seguridad y conformidad integradas

Protección de nivel empresarial para sus datos y flujos de trabajo Más información sobre nuestra seguridad

SOC 2 Tipo II

Certificado

Controles de seguridad auditados de forma independiente que garantizan la protección de datos y la integridad operativa.

GDPR

Conforme

Pleno cumplimiento de la normativa europea de protección de datos para la privacidad de los usuarios.

99.9%

Tiempo de actividad de la plataforma en los últimos 24 meses

24/7

Asistencia global con API de alto rendimiento

FAQ de la bandeja unificada

Una llamada por cuenta, los endpoints necesarios, la paginación entre cuentas, la forma de los mensajes y los emails, y cómo mantener la lista viva.

No, por diseño. account_id forma parte de la ruta, así que se llama una vez por cuenta y se fusiona en su aplicación. Lo que la API unifica es la forma de los objetos, no el número de llamadas.

GET /v2/accounts/ para la lista de cuentas, luego GET /v2/{account_id}/chats y GET /v2/{account_id}/emails por cuenta, y después GET /v2/{account_id}/chats/{chat_id}/messages para abrir una conversación. Las respuestas salen por POST /v2/{account_id}/chats/{chat_id}/messages/send y POST /v2/{account_id}/emails/send.

Un cursor por cuenta. Cada ruta de listado devuelve data, total_count y next_cursor. Devuelva next_cursor en el parámetro cursor y mantenga un mapa de cursores, uno por cuenta, en el estado de su aplicación.

Las conversaciones de mensajería son objetos Chat y los emails son objetos Email, cada uno con sus propios campos. La normalización ocurre en su aplicación sobre al menos tres campos: identificador, fecha y remitente. El agente lee ambos esquemas a través del servidor y escribe ese mapeo.

Con un endpoint de webhook suscrito a message.new y email.new. La página dedicada muestra cómo lo conecta un agente.