Configura la API de Google Chat

Cada app de Google Chat que crees requiere su propio proyecto de Google Cloud con la API de Chat habilitada y configurada.

Para realizar llamadas a la API de solo lectura con autenticación de usuario, como obtener espacios y enumerar mensajes, solo necesitas habilitar la API y crear un cliente de OAuth.

Para realizar llamadas a la API de creación, actualización y eliminación, o para implementar y probar una app de Chat interactiva (creada como un complemento de Google Workspace que extiende Chat), también debes configurar la API de Chat. En la configuración de la API de Chat, se especifican todos los detalles de la app de Chat, como el nombre visible, el avatar, los extremos de implementación y las funciones interactivas.

Requisitos previos

Elige un nombre visible, un avatar y una descripción para tu app de Chat

Cuando habilitas la API de Chat, configuras los detalles de tu app de Chat que se muestran a los usuarios en Chat, incluidos un nombre visible, un avatar y una descripción. Estos detalles solo aparecen en Chat. Para publicar tu app de Chat en Marketplace, también debes especificar los detalles que aparecen en la ficha de Marketplace de tu app de Chat.

Antes de configurar una app de Chat, prepara la siguiente información:

Campo Descripción Formato
Nombre de la aplicación Es el nombre visible de la app de Chat. Hasta 25 caracteres alfanuméricos
URL del avatar Es la imagen que se muestra como el avatar de tu app de Chat. Es una URL HTTPS que apunta a una imagen gráfica cuadrada (PNG o JPEG). El tamaño recomendado es de 256 × 256 píxeles o más.
Descripción Es una descripción breve de la app de Chat que se muestra cuando los usuarios buscan apps en Chat. Hasta 40 caracteres alfanuméricos
Descripción larga Opcional. Es una descripción de lo que puede hacer la app de Chat, que se muestra cuando los usuarios inician una conversación con la app de Chat o abren la página principal de sesiones de un agente. Actualmente, solo se admite cuando se actualiza la configuración de la app con la consola de Google Cloud y no se admite a través de la API de complementos de Google Workspace. Hasta 250 caracteres

El nombre, el avatar y la descripción de la app de Chat se muestran a los usuarios en la IU de Chat. Para algunas solicitudes de escritura de la API de Chat, Chat usa esta información para atribuir las acciones que realiza una app de Chat en Chat.

Por ejemplo, si llamas al método spaces.create(), Chat incluye el nombre de la app de Chat en la descripción de quién creó el espacio, como se muestra en la siguiente imagen:

La app de Google Chat crea un espacio para un usuario.
Figura 1: Es el mensaje de atribución que muestra Chat cuando se usa el método spaces.create() para crear un espacio en nombre de un usuario.

Para interactuar con las apps de Chat, los usuarios también ven o usan esta información de las siguientes maneras:

  • Menciona con @ la app de Chat para agregarla a un espacio o enviarle un mensaje.
  • Busca y comienza un mensaje directo con la app de Chat. En el menú Apps, los mensajes directos muestran el nombre y el avatar de la app de Chat.
  • En la barra para escribir, los usuarios pueden explorar las apps de Chat y ver su nombre, avatar y descripción.

Configura tu app de Chat en la consola de Google Cloud

Cuando tengas los detalles de tu app de Chat, abre tu proyecto de Cloud y configura la API de Chat:

  1. En la consola de Google Cloud, ve a la página de la API de Chat y haz clic en la página Configuración:

    Ir a la página de configuración de la API de Chat

  2. En Información de la aplicación, completa los campos Nombre de la app, URL del avatar y Descripción.

  3. Opcional: Completa el campo Descripción larga.

  4. Opcional: En el menú Sintaxis de lenguaje de marcado, selecciona la sintaxis de lenguaje de marcado predeterminada (Markdown o Chat) para los mensajes de tu app de Chat. Para obtener más información sobre el formato de texto y cómo Chat determina la sintaxis de lenguaje de marcado para las solicitudes a la API, consulta Cómo dar formato a los mensajes.

  5. En Funciones interactivas, configura si tu app de Chat responde a las interacciones de los usuarios:

    Para compilar una app de Chat interactiva, activa Habilitar funciones interactivas y completa lo siguiente:

    1. En Funcionalidad, haz lo siguiente:
      • Opcional: Selecciona Admitir la página principal de la app para mostrar una tarjeta de la página principal en la pestaña Página principal de los mensajes directos 1:1 con la app de Chat.
      • Selecciona Unirse a espacios y conversaciones grupales para que tu app de Chat esté disponible para instalarla y usarla. De forma predeterminada, los usuarios pueden instalar la app de Chat y enviar mensajes con ella en un espacio dedicado entre el usuario y la app de Chat. Los usuarios también pueden agregar la app de Chat e interactuar con ella en espacios con varias personas.
    2. En Configuración de la conexión, selecciona la arquitectura que deseas usar para recibir objetos de evento de Chat:

      • Para usar un servicio HTTP, selecciona URL de extremo HTTP y proporciona una URL.
      • Para usar un proyecto de Google Apps Script, selecciona Apps Script y proporciona un ID de implementación para el proyecto.
      • Para usar un agente de Dialogflow, selecciona Dialogflow, elige Dialogflow CX o Dialogflow ES, y proporciona el nombre del recurso del agente.
      • Para usar Pub/Sub, selecciona Cloud Pub/Sub y, luego, ingresa el nombre del tema.
    3. Opcional: Para enrutar objetos de evento a extremos o funciones específicos, ve a Configuración de conexión > Activadores y proporciona o actualiza los extremos o las funciones de devolución de llamada para los siguientes activadores de Chat:

      • Página principal de la app (si la opción Admitir la página principal de la app está habilitada): Un usuario abre la pestaña Página principal en un mensaje directo 1:1 con la app de Chat.
      • Se agregó al espacio: Un usuario agrega la app de Chat a una conversación grupal o un espacio, o instala la app de Chat para mensajes 1:1.
      • Mensaje: Un usuario envía un mensaje a la app de Chat. Por ejemplo, un usuario envía un mensaje directo a la app de Chat o menciona con @a la app de Chat en un espacio con varias personas.
      • Se quitó del espacio: Un usuario desinstala o quita la app de Chat de un espacio.
      • Comando de app: Un usuario invoca un comando rápido, un comando de barra o una acción de mensaje desde la app de Chat.
    4. Opcional: Agrega otras funciones interactivas, como sesiones, instrucciones de inicio, comandos (comandos rápidos, comandos de barra y acciones de mensajes) o vistas previas de vínculos.

    5. En Visibilidad, selecciona Hacer que esta app de Chat esté disponible para personas y grupos específicos y, luego, ingresa las direcciones de correo electrónico de las personas o los Grupos de Google de tu organización de Google Workspace:

      • Para instalar y probar la app, ingresa tu propia dirección de correo electrónico.
      • Para compartir una app de Chat interna con un equipo o con toda tu organización sin publicarla en Marketplace, ingresa uno o más Grupos de Google. Los grupos no tienen un límite de miembros. Si tu app solicita permisos de chat.app.*, de todas formas, debes publicar la app para que el administrador la apruebe.
      • Si tu administrador restringe las instalaciones de Marketplace a las apps de una lista de entidades permitidas, la consola de Google Cloud limita este campo a cinco direcciones de correo electrónico de usuarios individuales para el desarrollo. La visibilidad del grupo solo se aplica después de que un administrador agrega la app a la lista de entidades permitidas.
  6. Opcional: En Registros, selecciona la casilla de verificación Registrar errores en Logging para usar Google Cloud Logging. Para obtener más información, consulta Consulta los registros de errores de las apps de Chat.

  7. Haz clic en Guardar.

Después de guardar la configuración, cualquier persona que hayas especificado en el parámetro de configuración Visibilidad de la API de Chat podrá instalar, probar o usar la app de Chat. Para comenzar a probar y depurar tu app de Chat, consulta Prueba las funciones interactivas de las apps de Google Chat.

Configura tu app de Chat con Google Cloud CLI

En lugar de usar la consola de Google Cloud, puedes ver y actualizar la configuración de una app de Chat desde la línea de comandos con la CLI de Google Cloud (gcloud CLI). Por ejemplo, puedes configurar una app de Chat desde una secuencia de comandos o mantener su configuración en un archivo que almacenes con tu código.

El grupo de comandos gcloud beta workspace-add-ons chat-app-config tiene los siguientes comandos:

  • describe: Muestra la configuración.
  • update: Configura una app de Chat por primera vez o cambia su configuración.

Los comandos usan el recurso chatAppConfig en la API de complementos de Google Workspace.

Antes de comenzar

  1. Instala gcloud CLI. Si ya instalaste gcloud CLI, ejecuta gcloud components update para asegurarte de tener la versión más reciente.
  2. Accede a gcloud CLI con tu cuenta de usuario. Los comandos no admiten cuentas de servicio.

    gcloud auth login
  3. Establece el proyecto de Cloud de tu app de Chat como el proyecto predeterminado de gcloud CLI. Usa el ID del proyecto, ya que los comandos no aceptan un número de proyecto.

    gcloud config set project PROJECT_ID

    Como alternativa, agrega la marca --project a cada comando.

  4. Habilita la API de complementos de Google Workspace en el proyecto de Cloud:

    gcloud services enable gsuiteaddons.googleapis.com
  5. Asegúrate de tener los siguientes roles de Identity and Access Management (IAM) en el proyecto de Cloud:

    • Desarrollador de complementos de Google Workspace (roles/gsuiteaddons.developer) para ver y actualizar la configuración, o Lector de complementos de Google Workspace (roles/gsuiteaddons.reader) para solo verla. Estos roles incluyen los permisos que se indican en Requisitos previos y autenticación.
    • Consumidor de Service Usage (roles/serviceusage.serviceUsageConsumer). gcloud CLI usa el proyecto de Cloud como el proyecto de cuota para sus solicitudes, lo que requiere el permiso serviceusage.services.use.

    Los roles de propietario y editor incluyen todos estos permisos. Los roles de propietario de apps de Chat y visualizador de apps de Chat, que otorgan acceso a la página de configuración en la consola de Google Cloud, no son suficientes.

Observa la configuración

Para ver la configuración de tu app de Chat, ejecuta el comando describe:

gcloud beta workspace-add-ons chat-app-config describe

El resultado es similar a este:

avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png
description: Helps manage tasks and schedules
displayName: Cymbal Assistant
errorLoggingEnabled: true
interactiveFeatureConfig:
  allowlistedTestingPrincipals:
  - user@example.com
  appCommands:
  - command: /help
    commandId: 1
    commandType: SLASH_COMMAND
    description: Show available commands
  connectionConfig:
    httpEndpointConfig:
      commonUrl: https://example.com/chat
  supportsMultiuserSpaces: true
  urlPatterns:
  - hostPattern: example.com
    pathPrefix: tasks/
name: projects/123456789012/chatAppConfig
state: ACTIVE

Si el proyecto de Cloud aún no tiene una app de Chat, el comando se ejecuta correctamente y solo imprime el campo name de la configuración:

name: projects/123456789012/chatAppConfig

Para cambiar el resultado, agrega una de las siguientes marcas:

  • --format=json: Imprime la configuración en formato JSON.
  • --view=basic: Excluye la configuración de las funciones interactivas (interactiveFeatureConfig).
  • --format="value(displayName)": Imprime solo el nombre visible o una línea vacía si el proyecto de Cloud aún no tiene una app de Chat. Una app de Chat configurada siempre tiene un nombre visible, por lo que puedes usar esta marca en una secuencia de comandos para verificar si existe una app de Chat.

Actualiza la configuración

Para configurar una app de Chat por primera vez o cambiar su configuración, ejecuta el comando update. Especifica la configuración con marcas o en un archivo de configuración. No puedes combinar ambos en un solo comando.

La primera vez que ejecutes el comando para un proyecto de Cloud, debes especificar, al menos, un nombre visible y una descripción. A menos que establezcas el estado como inhabilitado, la app de Chat estará activa en cuanto finalice el comando. Las personas que incluyas como verificadores podrán encontrarla y usarla.

Usa marcas

En el siguiente ejemplo, se configura una app de Chat que recibe eventos en un extremo HTTP:

gcloud beta workspace-add-ons chat-app-config update \
    --display-name="Quickstart App" \
    --description="Quickstart app" \
    --avatar-uri=https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png \
    --http-endpoint-url=HTTP_ENDPOINT_URL \
    --supports-multiuser-spaces \
    --add-allowlisted-testing-principals=USER_EMAIL \
    --error-logging-enabled

Reemplaza lo siguiente:

  • HTTP_ENDPOINT_URL: Es la URL HTTPS que recibe objetos de evento de Chat.
  • USER_EMAIL: Es la dirección de correo electrónico de una persona o un grupo de tu organización de Google Workspace que puede instalar y probar la app de Chat, como tu propia dirección de correo electrónico.

El comando imprime la configuración actualizada.

En la siguiente tabla, se enumeran las marcas para los parámetros de configuración en la página Configuración de la API de Chat en la consola de Google Cloud. Para obtener detalles sobre cada marca, consulta la referencia del comando update.

Configuración en la consola de Google Cloud Marcas
Nombre de la aplicación --display-name
URL del avatar --avatar-uri por la URL HTTPS de una imagen que cumpla con los requisitos de avatar o --clear-avatar-uri para usar el avatar predeterminado
Descripción --description
Estado de la aplicación --state=active o --state=disabled
Sintaxis de marcas --markup-syntax=markdown o --markup-syntax=chat
Unirse a espacios y conversaciones grupales --supports-multiuser-spaces o --no-supports-multiuser-spaces
Configuración de conexión Uno de las siguientes opciones:
  • URL del extremo HTTP: --http-endpoint-url
  • Apps Script: --apps-script-deployment-id
  • Cloud Pub/Sub: --pubsub-topic con un tema en el mismo proyecto de Cloud, con el formato projects/PROJECT_ID/topics/TOPIC_ID
  • Dialogflow: --dialogflow-edition=es o --dialogflow-edition=cx con --dialogflow-agent establecido en el nombre del recurso del agente o entorno, como projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID
Visibilidad --add-allowlisted-testing-principals, --remove-allowlisted-testing-principals y --clear-allowlisted-testing-principals
Registrar errores en Logging --error-logging-enabled o --no-error-logging-enabled

Los comandos, las vistas previas de vínculos y los extremos independientes para cada activador no tienen marcas. Para configurarlas, usa un archivo de configuración.

Por ejemplo, para desactivar tu app de Chat sin cambiar sus otros parámetros de configuración, ejecuta el siguiente comando. Para volver a activarlo, usa --state=active.

gcloud beta workspace-add-ons chat-app-config update --state=disabled

Usa un archivo de configuración

Para mantener la configuración en un archivo o establecer parámetros que no tengan marcas, pasa un archivo YAML o JSON al comando update. El archivo usa los campos del recurso chatAppConfig, que son los mismos campos que imprime el comando describe.

  1. Crea un archivo que contenga la configuración que deseas actualizar. Por ejemplo, crea un archivo llamado chat_app_config.yaml con el siguiente contenido:

    displayName: Cymbal Assistant
    description: Helps manage tasks and schedules
    avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png
    state: ACTIVE
    errorLoggingEnabled: true
    interactiveFeatureConfig:
      supportsMultiuserSpaces: true
      connectionConfig:
        httpEndpointConfig:
          commonUrl: https://example.com/chat
      appCommands:
      - commandId: 1
        commandType: SLASH_COMMAND
        command: /help
        description: Show available commands
      urlPatterns:
      - hostPattern: example.com
        pathPrefix: tasks/
      allowlistedTestingPrincipals:
      - USER_EMAIL
    

    Reemplaza USER_EMAIL por la dirección de correo electrónico de una persona o un grupo de tu organización de Google Workspace que pueda instalar y probar la app de Chat.

  2. Ejecuta el comando update con la marca --config-file:

    gcloud beta workspace-add-ons chat-app-config update \
        --config-file=chat_app_config.yaml

Para comenzar desde la configuración actual de una app de Chat, guarda el resultado del comando describe en un archivo:

gcloud beta workspace-add-ons chat-app-config describe > chat_app_config.yaml

Luego, edita el archivo, borra los campos que no quieras cambiar y pasa el archivo al comando update. Si el archivo contiene un parámetro de configuración que el comando no puede actualizar, este fallará. Para obtener más información, consulta Limitaciones.

El comando update ignora el campo name del archivo. Siempre actualiza el proyecto de Cloud que estableciste en gcloud CLI, por lo que puedes usar el mismo archivo para configurar una app de Chat en otro proyecto de Cloud.

Cómo el comando aplica tus cambios

  • Solo cambian los parámetros de configuración que especificas. Con las marcas, el comando cambia la configuración de las marcas que pasas. Con un archivo de configuración, se cambian los campos que están en el archivo, por lo que el archivo no necesita contener toda la configuración. La configuración de conexión es una excepción: el tipo de conexión que estableces reemplaza al actual, y la edición de Dialogflow que estableces reemplaza toda la configuración de Dialogflow.
  • Las listas se reemplazan por completo. Si el archivo contiene el campo appCommands, urlPatterns o allowlistedTestingPrincipals, la lista del archivo reemplaza la lista actual. Para agregar o quitar verificadores individuales, usa las marcas --add-allowlisted-testing-principals y --remove-allowlisted-testing-principals.
  • Un valor vacío borra un parámetro de configuración. Por ejemplo, un archivo que contiene urlPatterns: [] en interactiveFeatureConfig quita todos los patrones de URL de vista previa de vínculos.
  • Un comando que falla no cambia nada. Si un valor no es válido, el comando imprime el error y deja la configuración como estaba.
  • Las solicitudes tienen un límite de frecuencia. La API limita la cantidad de solicitudes de lectura y de actualización por minuto para cada proyecto de Cloud y para cada organización. Cada comando update envía una solicitud de actualización. Si agregas o quitas verificadores con marcas, el comando también envía una solicitud de lectura. Para cambiar varios parámetros de configuración, pásalos en un comando o un archivo en lugar de ejecutar un comando para cada parámetro de configuración.

Limitaciones

  • Los comandos solo admiten apps de Chat creadas como complementos de Google Workspace.
  • Los comandos no admiten cuentas de servicio ni el robo de identidad de cuentas de servicio. Debes acceder a gcloud CLI con una cuenta de usuario.
  • Un proyecto de Cloud tiene una configuración de app de Chat, y los comandos no pueden borrarla. Para impedir que las personas usen la app de Chat, establece su estado como inhabilitado o borra el proyecto de Cloud.
  • Se aplica una actualización a la app de Chat en vivo. Los comandos no tienen un modo de borrador ni de ejecución de prueba.
  • Mientras una app de Chat esté publicada o en proceso de revisión en Google Workspace Marketplace, los comandos no podrán cambiar su nombre visible, avatar, descripción, comandos ni patrones de URL de vista previa de vínculos.
  • Los comandos admiten la configuración en el recurso chatAppConfig. Para configurar un parámetro que el recurso no incluye, usa la consola de Google Cloud.

Solucionar problemas

Si un comando falla, busca el texto del mensaje de error en la siguiente tabla. Si el mensaje comienza con un estado como INVALID_ARGUMENT, la API de complementos de Google Workspace rechazó la solicitud, y el texto después del estado describe el problema.

El mensaje de error contiene Causa Solución
Invalid choice: 'chat-app-config' o Invalid choice: 'workspace-add-ons' El comando no incluye beta o tu versión de gcloud CLI no incluye los comandos. Inicia el comando con gcloud beta workspace-add-ons chat-app-config. Si el error persiste, actualiza gcloud CLI a la versión más reciente.
PROJECT ID El proyecto se establece en un número de proyecto. Configura el proyecto con el ID del proyecto.
Failed to parse value(s) in protobuf El archivo de configuración contiene un campo que gcloud CLI no reconoce. En el mensaje de error, se indica el nombre del campo. Compara el nombre del campo con el resultado del comando describe. Si el campo es nuevo, actualiza gcloud CLI a la versión más reciente.
does not have permission to access projects instance La API rechazó la solicitud. El texto que aparece después de este mensaje indica el motivo. Por ejemplo:
  • Tu cuenta no tiene los roles de IAM necesarios. Si el texto contiene Caller does not have required permission to use project, falta el rol de consumidor de Service Usage.
  • La API de complementos de Google Workspace no está habilitada en el proyecto de Cloud.
  • Accediste con una cuenta de servicio.
Verifica los requisitos en Antes de comenzar.
INVALID_ARGUMENT Un valor no es válido. Por ejemplo, el nombre visible debe tener entre 3 y 25 caracteres, y la descripción, entre 1 y 40 caracteres. Si el mensaje contiene not found or deleted, el ID del proyecto no es correcto. Corrige el valor que describe el mensaje de error y vuelve a ejecutar el comando.
FAILED_PRECONDITION La app de Chat no permite la solicitud. Por ejemplo, no se creó como un complemento de Google Workspace o se publicó en Google Workspace Marketplace y no se puede cambiar el parámetro de configuración. Sigue las instrucciones que se indican en el mensaje de error. Para configurar una app de Chat que no sea un complemento de Google Workspace, usa la consola de Google Cloud o conviértela.
RESOURCE_EXHAUSTED o 429 La API recibió demasiadas solicitudes para el proyecto de Cloud o para tu organización en un período breve. Espera un minuto y, luego, vuelve a ejecutar el comando.

Configura tu app de Chat con la API de complementos de Google Workspace

En lugar de configurar tu app de Chat de forma manual en la consola de Google Cloud, puedes leer y actualizar de manera programática la configuración de una app de Chat creada como un complemento de Google Workspace con el recurso chatAppConfig en la Google Workspace add-ons API.

chatAppConfig es un recurso singleton que siempre existe para cada proyecto de Cloud. Antes de guardar una configuración por primera vez, el recurso contiene una configuración vacía (que también es lo que GetChatAppConfig devuelve si lees el recurso antes de guardarlo por primera vez). Como el recurso ya existe, no necesitas crearlo por separado; usa UpdateChatAppConfig para guardar la configuración inicial y actualizar una configuración existente.

Requisitos previos y autenticación

Antes de llamar a GetChatAppConfig o UpdateChatAppConfig, completa los siguientes requisitos previos:

  1. Habilita la API de complementos de Google Workspace (gsuiteaddons.googleapis.com) en tu proyecto de Cloud. De manera opcional, puedes habilitar la API de Google Chat (chat.googleapis.com) si quieres ver o actualizar la configuración de la app de Chat en la consola de Google Cloud o llamar a la API de Chat.
  2. Autentícate como usuario humano con una credencial de OAuth 2.0 que incluya el permiso https://www.googleapis.com/auth/cloud-platform. La autenticación de la cuenta de servicio no se admite para los métodos chatAppConfig.
  3. Asegúrate de que el usuario autenticado tenga los permisos de Identity and Access Management (IAM) necesarios en el proyecto de Cloud de destino:
    • gsuiteaddons.chatAppConfigs.get y chat.bots.get para leer la configuración (GetChatAppConfig).
    • gsuiteaddons.chatAppConfigs.update, chat.bots.update y chat.bots.get para actualizar la configuración (UpdateChatAppConfig).
  4. Si usas una biblioteca cliente, instala la versión más reciente de la biblioteca cliente de la API de complementos de Google Workspace para tu lenguaje. Para obtener una lista de las bibliotecas cliente, consulta la referencia de la API de complementos de Google Workspace.

Actualiza la configuración de una app de Chat

Para configurar una app de Chat por primera vez o actualizar una configuración existente, envía una solicitud PATCH (UpdateChatAppConfig) al recurso singleton chatAppConfig de tu proyecto de Cloud:

  • Para el guardado inicial en un proyecto de Cloud con un chatAppConfig vacío, se requieren displayName (de 3 a 25 caracteres) y description (de 1 a 40 caracteres). Si omites interactiveFeatureConfig en el guardado inicial, la app de Chat se configurará como no interactiva.
  • Para las actualizaciones posteriores, usa el parámetro de consulta opcional updateMask para especificar los campos separados por comas que se actualizarán (u omite updateMask para actualizar todos los campos proporcionados). Cuando se actualiza un campo repetido (appCommands, urlPatterns o allowlistedTestingPrincipals), se reemplaza toda la lista.
PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "name": "projects/PROJECT_NUMBER/chatAppConfig",
  "displayName": "Cymbal Assistant",
  "description": "Helps manage tasks and schedules",
  "avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
  "state": "ACTIVE",
  "errorLoggingEnabled": true,
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "interactiveFeatureConfig": {
    "supportsMultiuserSpaces": false,
    "connectionConfig": {
      "httpEndpointConfig": {
        "commonUrl": "https://example.com/chat"
      }
    },
    "appCommands": [
      {
        "commandType": "SLASH_COMMAND",
        "commandId": 1,
        "command": "/help",
        "description": "Show available commands",
        "dialogEnabled": false
      }
    ],
    "urlPatterns": [
      {
        "hostPattern": "example.com",
        "pathPrefix": "tasks/"
      }
    ],
    "allowlistedTestingPrincipals": [
      "USER_EMAIL"
    ]
  }
}

Reemplaza lo siguiente en la URL, el encabezado y el cuerpo de la solicitud:

  • PROJECT_NUMBER: Es el número numérico del proyecto de Cloud que aloja tu app de Chat.
  • ACCESS_TOKEN: Es un token de acceso de OAuth 2.0 de usuario autorizado con el permiso https://www.googleapis.com/auth/cloud-platform.
  • USER_EMAIL: Es una dirección de correo electrónico o un Grupo de Google de tu organización de Google Workspace que se agregará a la lista de entidades permitidas para probar la app de Chat (por ejemplo, tu propia dirección de correo electrónico).
  • Los campos de configuración de ejemplo en el cuerpo de la solicitud (como displayName, description, avatarUri y interactiveFeatureConfig, incluidos la configuración del extremo, los comandos, los patrones de URL de vista previa de vínculos y las principales de prueba) con los valores de tu app de Chat. Para obtener detalles sobre todos los campos admitidos y las opciones de extremos, consulta la referencia de REST de projects.chatAppConfig y projects.chatAppConfig.patch.

Obtén la configuración de una app de Chat

Para leer la configuración actual de la app de Chat de un proyecto de Cloud, llama a GetChatAppConfig. Puedes pasar el parámetro de consulta opcional view (ChatAppConfigView):

  • BASIC (predeterminado): Devuelve metadatos básicos sin interactiveFeatureConfig.
  • FULL: Devuelve todos los campos de configuración, incluido interactiveFeatureConfig.

Si aún no se guardó la configuración de la app de Chat para el proyecto de Cloud, el método devuelve un objeto ChatAppConfig vacío.

HTTP

GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN

Node.js

const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;

const client = new GSuiteAddOnsClient();

async function getChatAppConfig() {
  const [response] = await client.getChatAppConfig({
    name: 'projects/PROJECT_NUMBER/chatAppConfig',
    view: 'FULL',
  });
  console.log(JSON.stringify(response, null, 2));
}

getChatAppConfig();

Python

from google.cloud import gsuiteaddons_v1

client = gsuiteaddons_v1.GSuiteAddOnsClient()

request = gsuiteaddons_v1.GetChatAppConfigRequest(
    name="projects/PROJECT_NUMBER/chatAppConfig",
    view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)

Límites de uso

Los métodos chatAppConfig tienen cuotas por proyecto. Si excedes una cuota, la solicitud falla con un código de estado HTTP 429: Too many requests. Para conocer los límites de cuota, consulta Límites de uso de la API de complementos de Google Workspace.

Solucionar errores

Si falla una solicitud chatAppConfig, verifica el código de estado HTTP y el campo message en la respuesta de error. En la siguiente tabla, se indican los errores comunes, sus causas y cómo resolverlos.

Código de estado HTTP Causas habituales Solución
400: Bad Request (INVALID_ARGUMENT)
  • El updateMask contiene un campo que no existe o no se puede actualizar.
  • Falta un valor de campo o no es válido. Por ejemplo, interactiveFeatureConfig no incluye un connectionConfig.
Verifica el campo message para ver el campo no válido y corrige la solicitud. Para conocer los campos y valores admitidos, consulta la referencia de projects.chatAppConfig.
400: Bad Request (FAILED_PRECONDITION)
  • La app de Chat no se creó como un complemento de Google Workspace.
  • No se puede cambiar el campo porque la app de Chat está publicada en Google Workspace Marketplace.
  • El valor nuevo no es compatible con la configuración existente de la app de Chat.
  • Convierte la app de Chat en un complemento de Google Workspace o configúrala en la consola de Google Cloud.
  • Sigue las instrucciones del campo message para actualizar la ficha publicada.
  • Verifica el campo message para ver el parámetro de configuración en conflicto y actualiza ambos parámetros en la misma solicitud, o bien cambia primero el parámetro existente.
403: Forbidden (PERMISSION_DENIED)
  • El usuario autenticado no tiene los permisos de IAM necesarios en el proyecto de Cloud.
  • La solicitud se autentica con una cuenta de servicio en lugar de una cuenta de usuario.
  • Otorga al usuario los permisos que se indican en Requisitos previos y autenticación.
  • Autentica como un usuario humano con el permiso https://www.googleapis.com/auth/cloud-platform.
404: Not Found (NOT_FOUND) El proyecto de Cloud en el nombre del recurso no existe o el usuario autenticado no puede acceder a él. Verifica que el nombre del recurso use el número de proyecto correcto en el formato projects/PROJECT_NUMBER/chatAppConfig y que el usuario tenga acceso al proyecto de Cloud.
429: Too Many Requests (RESOURCE_EXHAUSTED) Se superó la cuota por proyecto. Espera y vuelve a enviar la solicitud más tarde. Para conocer los límites, consulta Límites de uso.

Consideraciones para los complementos de Google Workspace existentes

Las apps de Chat requieren una configuración diferente en comparación con los complementos de Google Workspace que extienden otras aplicaciones de Google Workspace. Si tu complemento extiende otras aplicaciones de Google Workspace, ten en cuenta los siguientes requisitos para configurar la app de Chat:

  • Tanto las personas como los administradores de Google Workspace deben poder instalar tu complemento desde Marketplace. Estos parámetros de configuración de la instalación se establecen en el SDK de Marketplace.
  • Las apps de Chat no usan el nombre ni el logotipo que configuras para otras aplicaciones de Google Workspace en el objeto addons.common del manifiesto.
  • En el caso de los complementos que se publican en Google Workspace Marketplace, no puedes guardar un borrador de los cambios en los parámetros de configuración de la API de Google Chat. Después de actualizar y guardar los parámetros de configuración de la API de Chat, la app de Chat actualizada estará disponible de inmediato para todos los usuarios existentes. Para actualizar tu ficha de Marketplace, puedes crear un borrador antes de enviar cualquier cambio.
  • Si creaste tu complemento con Apps Script, sigue estos pasos:
  • Si creaste el complemento con un servicio HTTP, omite los detalles de configuración de la app de Chat en el manifiesto de projects.deployments que crees con la API de complementos de Google Workspace. Las implementaciones de HTTP que especificas en el SDK de Google Workspace Marketplace solo se usan para otras aplicaciones de Google Workspace. En su lugar, configura tu app de Chat en la consola de Google Cloud, con la gcloud CLI o con el recurso chatAppConfig en la API de complementos de Google Workspace.

Otorga permiso a otras personas para configurar la API de Chat

Puedes otorgar acceso a usuarios específicos a la página de configuración de la app de Chat asignándoles el rol de Identity and Access Management (IAM) de Google Cloud de propietario de apps de Chat o visualizador de apps de Chat. Los usuarios con estos roles no pueden navegar a la página de configuración de las apps de Chat con el panel de APIs y servicios, pero pueden acceder a la página de configuración navegando a la consola de Google Cloud para el proyecto de Cloud host de la app de Chat de la siguiente manera:

https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID

En el ejemplo anterior, PROJECT_ID es el ID del proyecto de Google Cloud que aloja la app de Chat.

Apps de Chat que no son complementos: Configura la API de Google Chat

Si mantienes una app de Chat que no es un complemento de Google Workspace, tu configuración usa un solo extremo para todos los eventos de interacción en lugar de activadores por evento:

  1. En la consola de Google Cloud, ve a la página Configuración de la API de Chat:

    Ir a la página de configuración de la API de Chat

  2. En Funciones interactivas, activa Habilitar funciones interactivas.

  3. Borra Crea esta app de Chat como complemento de Google Workspace. Se abrirá un cuadro de diálogo en el que se te pedirá que confirmes la acción. En el diálogo, haz clic en Inhabilitar.

  4. En Funcionalidad, selecciona Admitir la página principal de la app o Unirse a espacios y conversaciones grupales según sea necesario.

  5. En Configuración de la conexión, especifica un solo extremo para tu app de Chat (URL del extremo HTTP, ID de implementación de Apps Script, nombre del tema de Cloud Pub/Sub o Dialogflow).

  6. Configura los Comandos, las Instrucciones de inicio, las Vistas previas de vínculos, la Visibilidad y los Registros opcionales y, luego, haz clic en Guardar.

Para actualizar una app de Chat que no es un complemento a un complemento de Google Workspace que extienda Google Chat, consulta Convierte una app de Google Chat en un complemento de Google Workspace.