Este guia permite gerenciar aplicativos externos com o kChat usando webhooks.

Introdução

• Um webhook é um método que permite a uma aplicação ser notificada imediatamente quando um evento específico ocorre em outra aplicação, em vez de perguntar constantemente a essa aplicação se algo novo aconteceu ("polling").
  • Webhook de saída: o kChat comunica informações a outras aplicações quando um evento ocorre no kChat.
  • Webhook de entrada: o kChat recebe informações de outras aplicações para acionar ações no kChat.
• Não é possível importar o histórico das conversas de outra aplicação (Slack, Teams, Jabber, etc.) ou de outra Organização.
• Número máximo de Webhooks de entrada/saída:
  • kSuite Free = 1 / 1
  • kSuite Standard = 20 / 20
  • kSuite Business = ilimitado
  • kSuite Enterprise = ilimitado

Aceder à interface web do kChat

Pré-requisitos

• Não ser um utilizador externo (este não verá o menu Integrações).

Para configurar um webhook, encontre aplicações e integrações auto-hospedadas ou de terceiros:

1. Clique aqui para aceder à aplicação web kChat (serviço online ksuite.infomaniak.com/kchat) ou abra a aplicação de ambiente de trabalho kChat (aplicação para macOS / Windows / Linux).
2. Clique no ícone Novo ‍ ao lado do nome da sua organização kChat.
3. Clique em Integrações:
   
4. Aceda às categorias:
   

Guias específicos

Exemplos de integração no kChat:

• Calendário Infomaniak: exibir um lembrete de evento no kChat
• aplicativo n8n: ativar o envio de uma mensagem no kChat

Guias para outros usos

Para criar um webhook de entrada (para exibir um evento externo no kChat):

1. Clique na categoria Webhooks de entrada.
2. Clique no botão azul Adicionar webhooks de entrada:
   
3. Adicione um nome e uma descrição para o webhook.
4. Selecione o canal que receberá as mensagens.
5. Clique no botão para Salvar:
   
6. A URL a ser utilizada para seus desenvolvimentos é exibida (não a divulgue publicamente); exemplo: “https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx”:
   

Utilização do webhook

Exemplo rápido

1. Um comando curl específico (detalhado abaixo) é inserido em um terminal.
2. O comando contém a URL obtida no ponto 6 acima.
3. O comando terá como resultado a publicação de uma mensagem no canal especificado no ponto 4 acima:
   

Detalhes

Na aplicação que deve publicar no kChat:

1. Ajuste o código abaixo de acordo com a URL obtida no kChat:

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

2. Se necessário, use a mesma solicitação, mas com curl (para testar a partir de um aplicativo do tipo Terminal (interface de linha de comando, CLI / Command Line Interface) no seu dispositivo), como no exemplo da imagem acima:

   curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Hello, text1\nText2."}' {{URL_12}}

Se nenhum cabeçalho Content-Type for definido, o corpo da solicitação deve ser precedido por payload=, da seguinte forma:

payload={"text": "Hello, text1\nText2."}

Uma solicitação bem-sucedida receberá a seguinte resposta:

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	
}

Se você deseja ter o mesmo formato de resposta que o 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

você deve adicionar ?slack_return_format=true à URL do webhook.

Parâmetros

Além do campo text, aqui está a lista completa dos parâmetros suportados:

Exemplo de código com parâmetros

Veja como gerar uma mensagem mais completa com parâmetros, alguns dos quais podem substituir parâmetros já definidos durante a criação do webhook (nome de usuário, canal preferido, avatar, etc.), conforme indicado na tabela acima:

curl -i -X POST -H 'Content-Type: application/json' \
-d '{
"username": "System Monitor",
  "icon_url": "{{URL_13}}",
  "text": "### System Status Report\nEnvironment: PRODUCTION\nStatus: SUCCESSFUL\n\n---\n\n| Component | Version | Build ID | Status |\n|:----------|:-------:|:---------|:-------|\n| API-Core  | 2.4.1   | #88421   | OK     |\n| Web-UI    | 1.9.0   | #88425   | OK     |\n| Database  | 14.5    | N/A      | OK     |\n\n---\n\n**Commit Reference:**\n`git-ref: a7f8e9c21b` \n\n**Summary:**\nAll automated integration tests passed successfully. No manual intervention is required. Please contact the DevOps team for further details regarding this release."
}' \
{{URL_14}}

Resultado de um exemplo semelhante em imagem: