Conectar aplicaciones externas a kChat

Esta guía le permite gestionar aplicaciones externas con kChat utilizando webhooks.

Prólogo

• Un webhook es un método que permite a una aplicación ser informada inmediatamente cuando ocurre un evento particular en otra aplicación, en lugar de preguntar constantemente a esa aplicación si ha ocurrido algo nuevo (lo que se conoce como "polling").
  • Webhook saliente: kChat comunica información a otras aplicaciones cuando ocurre un evento en kChat.
  • Webhook entrante: kChat recibe información de otras apps para desencadenar acciones en kChat.
• No es posible importar el historial de conversaciones desde otra aplicación (Slack, Teams, Jabber, etc.) o desde otra Organización.

Acceder a la interfaz de webhooks de kChat

Requisitos previos

• No ser un usuario externo (este no verá el menú Integraciones).

Para configurar un webhook, encontrar aplicaciones e integraciones autoalojadas o de terceros:

1. Haga clic aquí‍ para acceder a la app Web kChat (servicio en línea kchat.infomaniak.com) o abra la app de escritorio kChat (aplicación de escritorio en macOS / Windows / Linux).
2. Haga clic en el icono Nuevo ‍ junto al nombre de su organización kChat.
3. Haga clic en Integraciones.
4. Accede a las categorías:
   

Ejemplo de integración

• Recordatorio de evento de calendario Infomaniak en kChat

Crear un simple webhook entrante

Para ello:

1. Haga clic en la categoría Webhooks entrantes.
2. Haga clic en el botón azul Agregar webhooks entrantes:
   
3. Añada un nombre y una descripción (máx. 500 caracteres) para el webhook.
4. Selecciona el canal que recibirá los mensajes
5. Guarde para obtener la URL (no la divulgue públicamente); ejemplo “https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx”.

Uso del webhook

En la aplicación que debe publicar en kChat:

1. Ajuste el código a continuación según la URL obtenida:

   POST /hooks/xxx-key-generated-xxx HTTP/1.1
   Host: your-server-kchat.xyz
   Content-Type: application/json
   Content-Length: 63
   {
       "text": "Hello, text1
   Text2."
   }

2. Opcionalmente, utilice la misma solicitud pero en curl (para probar desde una aplicación de tipo Terminal (interfaz de línea de comandos, CLI /Command Line Interface) en su dispositivo):
   curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Hello, text1 Text2."}' https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx

Si no se define ninguna cabecera Tipo de contenido no está definido, el cuerpo de la solicitud debe preceder de carga= así:

payload={"text": "Hello, text1 Text2."}

Una solicitud exitosa recibirá la siguiente respuesta:

HTTP/1.1 200 OK	
Content-Type: application/json	
X-Version-Id: 4.7.1.dev.12799dvd77e172e8a2eba0f4041ec1471.false	
Date: Sun, 01 Jun 2023 17:00:00 GMT	
Content-Length: 58	
	
{	
    "id":"x",	
    "create_at":1713198308869,	
    "update_at":1713198308869,	
    "delete_at":0,	
    "user_id":"x",	
    "channel_id":"x",	
    "root_id":"",	
    "original_id":"",	
    "participants":null,	
    "message":"test",	
    "type":"",	
    "props":{	
        "override_username":"webhook",	
        "override_icon_url":null,	
        "override_icon_emoji":null,	
        "webhook_display_name":"test",	
        "attachments":[	
	
        ],	
        "card":null,	
        "from_webhook":"true"	
    },	
    "hashtags":null,	
    "metadata":{	
        "embeds":[	
            {	
                "type":"message_attachment"	
            }	
        ],	
        "files":[	
	
        ],	
        "reactions":[	
	
        ]	
    },	
    "file_ids":null,	
    "has_reactions":false,	
    "edit_at":0,	
    "is_pinned":false,	
    "remote_id":null,	
    "reply_count":0,	
    "pending_post_id":null,	
    "is_following":false	
}

Si desea tener el mismo formato de respuesta que Slack:

HTTP/1.1 200 OK
Content-Type: text/plain
X-Request-Id: hoan69ws7rp5xj7wu9rmystry
X-Version-Id: 4.7.1.dev.12799dvd77e172e8a2eba0f4041ec1471.false
Date: Sun, 01 Jun 2023 17:00:00 GMT
Content-Length: 2
ok

debes agregar ?slack_return_format=true a la URL del webhook.

Parámetros

Además del campo text, aquí está la lista completa de los parámetros soportados:

Ejemplo de código con parámetros

Aquí está cómo generar un mensaje más completo con parámetros, algunos de los cuales pueden reemplazar parámetros ya establecidos durante la creación del webhook (nombre de usuario, canal preferido, avatar...) como se indica en la tabla anterior:

POST /hooks/xxx-clé-générée-xxx HTTP/1.1
Host: votre-serveur-kchat.xyz
Content-Type: application/json
Content-Length: 630
{
  "channel": "kchatemp",
  "username": "test-automation",
  "icon_url": "https://domain.xyz/wp-content/uploads/2023/06/icon.png",
  "text": "#### Résultats des tests pour le 27 juillet 2023
@channel veuillez vérifier les tests échoués.

| Composant  | Tests effectués   | Tests échoués                                   |
|:-----------|:-----------:|:-----------------------------------------------|
| Serveur     | 948         |  0                           |
| Client Web | 123         |  2 [(voir détails)](https://linktologs) |
| Client iOS | 78          |  3 [(voir détails)](https://linktologs) |"
}

Esto hará que se muestre este mensaje en el canal kchatemp de la organización :