:Integrar o serviço de assistente de IA ao WeCom

Configurar a instância do serviço de assistente de IA do DataWorks

Retorne ao console do DataWorks e acesse a seção Channel Configuration na aba Basic Information da página de detalhes da instância.

1. Na seção Channel Configuration, selecione WeCom como canal.

2. Selecione Use URL Callback como modo de conexão.

3. Insira ou gere aleatoriamente os seguintes parâmetros:

   Parâmetro	Descrição	Requisitos de formato
   Token	Verifica a origem da solicitação para garantir que as requisições venham do servidor do WeCom.	3 a 32 caracteres (letras ou dígitos)
   EncodingAESKey	Criptografa o conteúdo da mensagem para evitar interceptação ou adulteração dos dados durante a transmissão.	Requisitos de formato: Exatamente 43 caracteres (dígitos ou letras). Padrão de criptografia: Algoritmo AES-256-CBC.

   Importante

   Mantenha o Token e a EncodingAESKey seguros e não os divulgue a terceiros.

   É possível gerar o Token e a EncodingAESKey no console do DataWorks ou no console de administração do WeCom. Após gerá-los em um dos consoles, copie os valores para o outro. Os valores dos parâmetros devem ser idênticos em ambos os lados.

4. Configure a lista de permissões de IP: Restrinja o acesso à URL de callback apenas aos intervalos de IP especificados. A lista deve incluir os IPs do servidor do WeCom. Para obter detalhes, consulte a documentação de IP de callback do WeCom.

5. Clique em Save.

   Após salvar a configuração, aguarde até que o status da instância mude para Running.

Nas informações do canal WeCom na página de detalhes da instância, visualize a Callback URL (callbackUrl) no seguinte formato:

https://ai-assistants.cn-beijing.data.aliyuncs.com/xxxx/plugins/wecom/bot?apikey=sk-ai-assistants-xxxxx

Copie a URL de callback completa (incluindo o parâmetro ?apikey=...) para usar na próxima etapa, ao configurar o console de administração do WeCom. Se a página exibir Callback configuration failed, verifique o motivo da falha e salve a configuração novamente.

Configurar no console de administração do WeCom

1. Faça login no console de administração do WeCom.

2. Acesse Security & Management > Management Tools > Intelligent Bot > Create Bot e alterne para Create in API Mode.

3. Defina o método de conexão como URL Callback.

4. Insira os três itens a seguir:

   Item de configuração	Valor	Descrição
   URL	URL de callback copiada do console do DataWorks	URL completa, incluindo o parâmetro ?apikey=...
   Token	Igual ao Token configurado no console do DataWorks	Deve ser idêntico em ambos os lados
   EncodingAESKey	Igual à EncodingAESKey configurada no console do DataWorks	Deve ser idêntica em ambos os lados (43 caracteres)

5. Clique em Save.

Após salvar, o servidor do WeCom envia automaticamente uma solicitação de verificação para a URL de callback:

• Verificação bem-sucedida: O console de administração do WeCom exibe uma mensagem de sucesso e a instância pode começar a receber mensagens.

• Falha na verificação: Verifique se o Token e a EncodingAESKey são exatamente iguais, se a instância está no estado Running, se a URL de callback foi copiada integralmente (incluindo a parte ?apikey=) e se a lista de permissões de IP está configurada.

Lista de permissões de IP

A lista de permissões de IP restringe quais IPs podem acessar a URL de callback para evitar solicitações não autorizadas.

Rotação da API Key

Se a API Key for comprometida ou precisar de rotação periódica, passe o mouse sobre o botão URL Callback e clique no botão de atualização na janela pop-up para renovar a API Key. Após a atualização:

• Uma nova API Key é gerada e a URL de callback antiga torna-se inválida imediatamente.

• Atualize a nova URL de callback no console de administração do WeCom.

Após a rotação, atualize a URL de callback no console de administração do WeCom. Caso contrário, as mensagens não serão recebidas.

Alternar de WebSocket para callback de URL

1. Na configuração do canal, altere o modo de conexão para URL Callback.

2. Insira o Token e a EncodingAESKey.

3. Após clicar em Save, conclua a configuração no console de administração do WeCom conforme descrito em Configurar no console de administração do WeCom.

Alternar de callback de URL de volta para WebSocket

1. Na configuração do canal, altere o modo de conexão para Use Long-lived Connection.

2. Insira o Bot ID e o Secret.

3. Após clicar em Save, os recursos do gateway de webhook são limpos automaticamente.

A modificação da configuração do canal aciona uma reinicialização da instância. Após a reinicialização, apenas os dados do workspace (memória e habilidades) são retidos. Reinstale as dependências personalizadas.

Falha na verificação da URL de callback?

• Verifique se o Token e a EncodingAESKey são exatamente iguais aos configurados no console do DataWorks.

• Confirme se a instância está no estado Running e se a configuração de callback não apresenta falhas.

• Certifique-se de que a URL de callback foi copiada integralmente (incluindo a parte ?apikey=...).

Configuração bem-sucedida, mas nenhuma mensagem recebida?

• Verifique se a lista de permissões de IP inclui os intervalos de IP de callback do WeCom.

• Confirme se a API Key não sofreu rotação (caso tenha sofrido, atualize a URL de callback no console de administração do WeCom).

• Verifique a página de detalhes da instância em busca de mensagens de erro relacionadas ao callback.

O callback ainda está ativo após excluir a instância?

Ao excluir uma instância, todos os recursos do gateway são limpos automaticamente e a URL de callback torna-se inválida imediatamente. Nenhuma ação adicional é necessária.

O callback parou de funcionar após excluir a lista de permissões?

Depois que todos os IPs da lista de permissões são excluídos, o endereço 127.0.0.1 é adicionado automaticamente para bloquear todo o acesso externo. Adicione novamente os intervalos de IP de callback do WeCom para restaurar o acesso.

Como obtenho os intervalos de IP do servidor do WeCom?

Consulte a documentação de IP de callback do WeCom.