Resumen
Tu aplicación puede iniciar y continuar las conversaciones en la bandeja de entrada de los miembros del área de trabajo, donde también hablan con el asistente de veinte. Un mensaje puede terminar en una pregunta, un formulario o un cambio para aprobar, que el miembro responde de la charla antes de la conversación continúa con el asistente. Los ayudantes de la bandeja de entrada se exportan tanto detwenty-sdk/logic-function como de twenty-sdk/front-component, así que un ejecutado programado y un botón en tu aplicación publican de la misma manera.
Enviando un mensaje
sendInboxMessage() publica un mensaje de tu aplicación en los chats de uno o más miembros del espacio de trabajo y devuelve el threadId de la conversación.
src/logic-functions/notify-first-recording.ts
workspaceMemberIdslista a los miembros que reciben la conversación, al menos uno. El primer miembro de una nueva conversación la posee, y los demás la siguen como participantes. Un envío posterior bajo la misma clave que lista a los nuevos miembros los agrega; los miembros deja fuera mantener la conversación.threadKeyelige la conversación para esta aplicación, compartida por todos los miembros a los que se envía. Una nueva clave inicia una conversación tituladatitle; una clave que usaste antes añade el mensaje a esa conversación.- El mensaje que identifica el mensaje dentro de la conversación es
idempotencyKeycyKey`. Enviar de nuevo con las mismas claves no escribe nada nuevo, así que reintentas y ejecuciones simultáneas nunca duplican un mensaje. textes markdown, y puede llevar menciones y referencias de registro. El miembro que menciona recibe una notificación, incluso cuando no está enworkspaceMemberIds.toolCall(opcional) termina el mensaje en uno de:- una llamada a las respuestas de los miembros, que pausa la conversación:
ask_question(una pregunta de elección múltiple),request_form(campos a rellenar) opropose_tool_call(una llamada a aprobar). Suinputtoma eltoolName, losargumentoscon la herramienta y una fraseResumen. La herramienta debe ser una que el rol predeterminado de tu app pueda ejecutar por sí mismo, comocreate_one_personoupdate_one_opportunity(con eliddel registro); un correo electrónico (send_emailodraft_email, conrecipients,subjecty unbodyque indique su formato:{ type: 'html', html }o{ type: 'text', text }; se rechaza una cadena sin formato) no necesita permiso de tu app. El miembro revisa la llamada en la misma tarjeta que una llamada que el asistente propone, lo edita si quieren, y la llamada aprobada se ejecuta con su propio acceso; - una de las herramientas propias de tu aplicación, por
logicFunctionUniversalIdentifier, renderizada por su componente frontal con elinputyoutputque pases. No detiene la conversación.
- una llamada a las respuestas de los miembros, que pausa la conversación:
- Sólo una llamada al miembro puede esperar en una conversación a la vez: enviar otra antes de que la respuesta falle con
THREAD_AWAITING_ANSWER. Los mensajes simples y las llamadas a herramientas de aplicaciones siguen siendo aceptables. - Sólo el miembro propietario de una conversación puede eliminarla, y se ha eliminado una conversación para todos los miembros: no se restablece y no se añade nada a ella. Los otros miembros pueden darse de baja para sacarlo de su propia bandeja de entrada.
- Cada miembro debe tener el permiso ‘AI’, y la llamada falla sin escribir el mensaje cuando uno de ellos no puede tener la conversación. Su aplicación [rol predeterminado] (/developers/extend/apps/config/roles) debe conceder
SystemPermissionFlag.AI.
Quién envía el mensaje
La aplicación siempre escribe un mensaje, independientemente de lo que haya activado la llamada. La llamada en sí misma se ejecuta como el predeterminado clientes API:- En una función lógica, actúa como la persona que activó la carrera, o como su solicitud cuando nadie lo hizo, como en un horario cron.
- En un componente delantero, actúa como el miembro que mira la página. Cuando el token ha caducado, la llamada se actualiza una vez a través de Veinte y se vuelve a intentar.
AI, como todos los destinatarios.
Para publicar desde un componente frontal, importa los mismos ayudantes de twenty-sdk/front-component. Publicar en la bandeja de entrada muestra cómo abrir la conversación después.
Menciones y referencias de registros
La bandeja de entrada muestra las fichas de referencia entext como fichas. Escribirlos con estos ayudantes en lugar de a mano:
src/logic-functions/flag-idle-deal.ts
inboxMention({ workspaceMemberId })escribe una mención de un miembro del espacio de trabajo, yinboxReferenceRecord({ objectNameSingular, recordId })un chip que enlaza a cualquier registro.- Ambos leen la etiqueta que muestra el chip, como lo hace el composer: el nombre completo del miembro o su correo electrónico cuando el nombre está vacío, y el identificador de la etiqueta del registro, como el nombre de una empresa. Los corchetes se convierten en paréntesis y los saltos de línea se convierten en espacios, por lo que el chip siempre se renderiza.
- Leen con el mismo acceso que el resto de la llamada, por lo que el acceso tiene que llegar al miembro o al registro. Una referencia de registro hace dos peticiones, una para el campo de etiqueta del objeto y otra para el registro.
- Un miembro mencionado recibe la conversación en su bandeja de entrada, sin leer, con una mención por resolver, como cuando un compañero de equipo lo menciona. No necesita estar en
workspaceMemberIds, y también se puede mencionar al miembro propietario de la conversación. Se omite un miembro mencionado que no puede participar en la conversación, por ejemplo, sin el permisoAI, y el mensaje se sigue enviando. - Las menciones notifican una vez, cuando el mensaje se escribe por primera vez: volver a enviarlo con las mismas claves no notifica a nadie, incluso con un
textdiferente, y una nuevaidempotencyKeyvuelve a mencionar. - Solo una mención completa notifica. Una en código insertado o en un bloque de código, una cuyos corchetes tienen caracteres de escape (
\[\[), y un@nameescrito no notifican a nadie. Una referencia a un registro nunca notifica ni comparte el registro. INBOX_ASSISTANT_MENTIONescribe la referencia canónica del asistente del compositor. La bandeja de entrada lo muestra como@Ada; su identidad estable es independiente de su etiqueta. Esta referencia por sí sola no solicita una respuesta del asistente desde un mensaje de la aplicación.
Asociar registros a una conversación
attachRecordToInboxThread() vincula una conversación a un registro y detachRecordFromInboxThread() elimina el vínculo.
src/logic-functions/file-call-recap.ts
- Ambos reciben el
threadIdde la conversación y el registro comoobjectNameSingularyrecordId. Una conversación se puede vincular a personas, empresas, oportunidades y registros de objetos personalizados. - Ambos son idempotentes: asociar un registro dos veces mantiene un solo vínculo y desasociar un registro que no está asociado no cambia nada.
- La llamada se ejecuta con el mismo acceso que enviar un mensaje, lo que requiere el permiso
AI. Un miembro debe poder editar la conversación, y tu aplicación puede actuar en una conversación que ella misma escribió o en una a la que se concedió su rol predeterminado; de lo contrario, la llamada falla conTHREAD_NOT_FOUND. - El registro debe poder leerse con ese acceso; de lo contrario, la llamada falla con
RECORD_NOT_FOUND.
Archivar una conversación
archiveInboxThread() archiva una conversación que escribió tu aplicación, para los miembros que indiques, como si cada uno de ellos la hubiera archivado desde su bandeja de entrada. Úsalo cuando el trabajo relacionado con un mensaje se haya realizado en otro lugar: el correo electrónico que propusiste se envió desde Gmail, la reunión sobre la que preguntaste se aprobó en el calendario.
src/logic-functions/on-email-sent-archive-thread.ts
- Solo tu aplicación puede llamarlo en una conversación que ella misma escribió o en una para la que se concedió su función predeterminada; de lo contrario, la llamada falla con
THREAD_NOT_FOUND. Los miembros archivan desde su propia bandeja de entrada. - Todos los miembros que nombres deben poder leer la conversación. Si alguno no puede, la llamada falla con
THREAD_NOT_FOUNDy la archiva para nadie. - Un mensaje nuevo en la conversación la devuelve a la bandeja de entrada, igual que cuando un miembro la archiva.
- Se omite a un miembro que dejó de seguir la conversación, por lo que permanece fuera de su bandeja de entrada.
workspaceMemberIds para marcar una conversación como terminada en su canal, tal como lo hace un miembro desde la vista del canal. Las bandejas de entrada de los propios miembros se mantienen como están, y una conversación que no está en ningún canal falla con CHAT_THREAD_NOT_IN_CHANNEL.