API pública Beta

Encuentra las conversaciones que requieren atención

Filtra por awaitingReply, unread, unassigned, assigneeId, agentGroupId, snoozed, priority o tagIds. awaitingReply ignora las notas internas; unread es específico del compañero autenticado. unassigned significa sin asignado individual, aunque haya un equipo asignado. Las etiquetas coinciden con cualquiera de los IDs enviados.

GET /api/v1/conversations?status=open&awaitingReply=true&compact=true&sort=waitingSince&direction=asc

Ordena por waitingSince, lastMessageAt, createdAt o prioridad de negocio, con direction asc o desc. Los IDs resuelven los empates. Si omites filtros, se mantienen compact=false y snoozed=any. En REST, tagIds acepta IDs separados por comas; MCP también acepta un array. waitingSince empieza en el primer mensaje entrante después de la última respuesta; los seguimientos y las notas internas no lo reinician. Ejecuta este análisis de la cola de espera de forma programada aunque no llegue ningún webhook, para que los hilos antiguos vuelvan a aparecer.

Ponte al día sin releer la bandeja

Usa GET /api/v1/sync con conversations:read. El feed duradero incluye cambios de conversaciones, etiquetas, mensajes, propiedades de contactos, memorias y registros de eliminación. Cada carga requiere además su propio permiso de lectura: los cuerpos de los mensajes necesitan messages:read y las memorias, contact-memory:read. Las credenciales restringidas solo reciben los canales permitidos.

1. Empieza sin cursor, sigue nextCursor hasta que hasMore sea false y guarda ese cursor.
2. Lee las listas actuales de conversaciones y contactos y el historial que necesites para tu estado inicial.
3. Reproduce desde el cursor guardado para captar los cambios ocurridos durante esa lectura. Procesa cada página y guarda nextCursor.

Elimina duplicados por el id del evento: la reproducción es «al menos una vez», así que las acciones posteriores necesitan su propia protección contra duplicados. Una petición sin cursor cubre la última hora, no una instantánea completa. Los eventos se conservan 30 días; HTTP 410 resync_required significa que debes volver a cargar el estado. Vuelve a cargarlo también después de ampliar los permisos o el acceso a canales. Usa limit hasta 100 y maxBodyChars hasta 10 000 (500 por defecto). Pon compact=true para obtener los campos textPreview/textTruncated de los mensajes, limitados a 200 caracteres, en lugar de body/bodyTruncated. Los webhooks pueden activar a un agente; el feed sigue disponible sin suscripciones a webhooks o cuando la entrega de webhooks está atascada.

Registra las comprobaciones una vez y comparte el resultado

Antes de repetir una investigación, lee list_conversation_checks (GET /api/v1/conversations/{conversationId}/checks). Guarda un resultado con record_conversation_check (PUT a la misma ruta), indicando key, result, checkedBy y, opcionalmente, una reference para el ID o la URL de la tarjeta. Por ejemplo: key=product-version, result=Shopstar Go verified, checkedBy=Engineer, reference=card-X. Sonny registra el actorId autenticado y la marca de tiempo checkedAt. Reutilizar una key sustituye solo esa comprobación; es el estado actual, no un historial. Las lecturas necesitan conversations:read y las escrituras conversations:write, ambas limitadas al canal de la conversación. Estas llamadas no envían ninguna respuesta ni marcan al vendedor como respondido.

Asigna y actualiza el trabajo por lotes

Descubre los compañeros y equipos activos y asignables con GET /api/v1/members and /teams (members:read). Las respuestas incluyen la disponibilidad y el acceso efectivo a canales, sin direcciones de correo. Usa conversations:write para cambiar status, priority, assigneeId, agentGroupId, snoozedUntil, snoozedUntilReply, addTagIds o removeTagIds.

POST /api/v1/conversations/batch
{
  "conversationIds": ["conversation_1", "conversation_2"],
  "updates": { "agentGroupId": "team_1", "assignment": "round_robin" }
}

La asignación rotativa elige un miembro del equipo disponible que pueda acceder al canal de la conversación. Si no hay ningún miembro que cumpla los requisitos, una actualización individual devuelve 409 y un elemento del lote falla. Cada lote acepta hasta 100 IDs únicos y aplica un cambio de forma atómica por conversación. Revisa cada resultado { id, ok, error? }; algunos elementos pueden fallar. Los lotes usan el límite de peticiones actual, sin cobro ponderado por número de elementos.

Comparte el contexto del cliente con Sonny AI

Lista, guarda y elimina memorias de contactos con contact-memory:read/write. Indica tanto contactId como un sourceId accesible; el contacto debe tener una conversación en ese origen. Los datos guardados usan la misma validación, gestión de duplicados y límites que la aplicación, y se registran como memorias manuales.

Lee las definiciones de propiedades en /api/v1/properties y lee o define valores en /api/v1/contacts/{contactId}/properties. MCP ofrece list_properties, get_contact_properties y set_contact_property. Requieren contacts:read/write y acceso a todos los canales. Indica exactamente un propertyId o un propertyName, con un valor de cadena o null para borrarlo. Los valores de texto, número, URL, fecha y selección se validan según la definición del campo.

PUT /api/v1/contacts/contact_1/properties
{ "propertyName": "Plan", "value": "Pro" }

GET /api/v1/contacts?property[Plan]=Pro

Los filtros de propiedades coinciden con cadenas guardadas exactas; si hay varias propiedades, deben coincidir todas. Los valores escritos por la API se etiquetan como datos de la API en Co-Pilot y en el respondedor automático. Se siguen aplicando las reglas existentes de cliente verificado y de origen. Los valores de campos internos introducidos a mano siguen excluidos de este contexto de IA.

Lee los mismos informes que tu equipo

Con reporting:read, llama a GET /api/v1/reporting/{kind}. Los tipos son overview, volume, response-times, agents, sources, tags, csat, ai, knowledge, leads y online-hours. overview combina recuentos, tiempos de respuesta y CSAT. Los filtros son period (de 1 a 365 días, 30 por defecto), fechas from/to emparejadas (to es exclusiva), granularity (day/month), source, assigneeId y tagId. source acepta all, all-chat, all-email, website:{id} o email:{id}.

Los informes usan las consultas del panel y las comprobaciones de acceso actuales. knowledge usa las fechas y los canales permitidos, independientemente del origen, el asignado o la etiqueta seleccionados. online-hours mide la presencia en el espacio de trabajo de los compañeros accesibles; sus recuentos de conversaciones siguen limitados por canal. Los endpoints /csat existentes mantienen su permiso csat:read independiente y pueden describir una población distinta.

Envía archivos con respuestas o notas internas

Concede attachments:write y sube un archivo de hasta 25 MB para una conversación. POST /api/v1/attachments recibe los campos multipart file y conversationId. La respuesta contiene un id y expiresAt. Pasa hasta 10 attachmentIds a una respuesta o nota en el plazo de una hora. Cada subida está vinculada a tu usuario y a la conversación, y solo se puede usar una vez. Las subidas sin usar se eliminan cuando caducan.

POST /api/v1/conversations/conversation_1/reply
{ "attachmentIds": ["upload_1"] }

Las respuestas requieren messages:send; las notas internas requieren messages:write y nunca llegan a los clientes. Se admiten mensajes solo con adjuntos. Las respuestas por correo incluyen los archivos que caben en el tamaño máximo del correo y enlaces de descarga para el resto; los correos de chat sin conexión incluyen enlaces a los archivos. Los enlaces enviados por correo siguen funcionando mientras exista el adjunto, así que los destinatarios pueden abrirlos más tarde. Reenviar el correo comparte el acceso a esos archivos. Consulta emailDeliveryStatus para ver los fallos de entrega.

Las lecturas de mensajes autorizadas incluyen downloadUrl, downloadExpiresAt, aiStatus, aiDescription y aiExtractedText, además de videoTranscripts para los vídeos enlazados (Loom, Vimeo y otros). Los enlaces de descarga duran 15 minutos; vuelve a leer el mensaje para obtener enlaces nuevos. Las nuevas subidas por API/MCP tienen almacenamiento privado. Los adjuntos más antiguos siguen siendo públicos y se marcan como access=legacy_public: su URL original no caduca. Leer un mensaje inicia la lectura de sus imágenes si el espacio de trabajo tiene Sonny AI. Las lecturas de imágenes y las transcripciones de vídeo terminan poco después de que llegue un mensaje: mientras alguna siga en curso, la respuesta empieza con readsInProgress, cuyo nextStep indica la llamada exacta que hay que hacer. Pasa waitSeconds (hasta 30) para esperarlas en una sola petición. Los mensajes del widget y en tiempo real para clientes nunca incluyen extracciones ni transcripciones.