Test Channel Configurations

Use list_channel_instances and test_channel_configuration (ListChannelInstances and TestChannelConfiguration in Go) to inspect existing channel instances in a workspace and precheck an unsaved channel configuration without creating an instance. The example below validates a WeCom enterprise mail (wecom_mail) configuration.

Task flow

List existing channel instances for the provider
                       │
                       ▼
Build an unsaved channel configuration and secret payload
                       │
                       ▼
Run connectivity precheck and inspect status or diagnostics

Prerequisites

  1. Complete the endpoint, personal access token, and workspace setup in Use the SDK.

  2. Sign in to the target WeCom enterprise mailbox, enable IMAP/SMTP, and generate a client-specific password (authorization code, separate from your mailbox login password and personal access token); see Configure WeCom enterprise mail for console preparation details.

  3. Export the full mailbox address and client-specific password in your terminal:

export WECOM_MAIL_EMAIL='<wecom-mail-address>'
export WECOM_MAIL_PASSWORD='<client-specific-password>'

List instances and test a configuration

The example first lists saved channel instances under provider "wecom" (which can include other WeCom channel types and does not require an existing mail instance), then submits the wecom_mail address and client-specific password for live connectivity validation.

import os

import moi_product_sdk as sdk


def main():
    client = sdk.new_with_personal_access_token(
        os.environ["PRODUCT_API_BASE_URL"],
        os.environ["PRODUCT_API_KEY"],
    )
    service = client.workspace(os.environ["WORKSPACE_ID"]).agents()

    instances = service.list_channel_instances("wecom")
    print("Total instances:", instances.total)
    for instance in instances.items:
        print(instance.id, instance.name, instance.channel_type, instance.last_test_status)

    request = sdk.ChannelInstanceCreateRequest(
        channel_type="wecom_mail",
        config={
            "email": os.environ["WECOM_MAIL_EMAIL"],
            "timeout_seconds": "30",
        },
        secrets={
            "password": os.environ["WECOM_MAIL_PASSWORD"],
        },
    )
    result = service.test_channel_configuration("wecom", request)
    print("OK:", result.ok, "Status:", result.status)
    print("Last test status:", result.last_test_status, "Tested at:", result.last_tested_at)
    if not result.ok or result.last_test_status != "succeeded":
        print("Failure reason:", result.last_test_error)
        print("Error code:", result.error_code, "Suggestion:", result.suggestion)
        raise SystemExit(1)
    print("Mail connection test passed; configuration is not saved.")


if __name__ == "__main__":
    main()
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func requiredEnv(name string) string {
	value := os.Getenv(name)
	if value == "" {
		log.Fatalf("missing environment variable: %s", name)
	}
	return value
}

func main() {
	ctx := context.Background()
	client, err := sdk.NewWithPersonalAccessToken(
		requiredEnv("PRODUCT_API_BASE_URL"),
		requiredEnv("PRODUCT_API_KEY"),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	workspace, err := client.Workspace(requiredEnv("WORKSPACE_ID"))
	if err != nil {
		log.Fatal(err)
	}
	service := workspace.Agents()

	instances, err := service.ListChannelInstances(ctx, "wecom")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Total instances:", instances.Total)
	for _, instance := range instances.Items {
		fmt.Println(instance.ID, instance.Name, instance.ChannelType, instance.LastTestStatus)
	}

	request := sdk.ChannelInstanceCreateRequest{
		ChannelType: "wecom_mail",
		Config: map[string]string{
			"email":           requiredEnv("WECOM_MAIL_EMAIL"),
			"timeout_seconds": "30",
		},
		Secrets: map[string]string{
			"password": requiredEnv("WECOM_MAIL_PASSWORD"),
		},
	}
	result, err := service.TestChannelConfiguration(ctx, "wecom", request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("OK:", result.OK, "Status:", result.Status)
	fmt.Println("Last test status:", result.LastTestStatus, "Tested at:", result.LastTestedAt)
	if !result.OK || result.LastTestStatus != "succeeded" {
		fmt.Println("Failure reason:", result.LastTestError)
		fmt.Println("Error code:", result.ErrorCode, "Suggestion:", result.Suggestion)
		os.Exit(1)
	}
	fmt.Println("Mail connection test passed; configuration is not saved.")
}

Inspect test results

  • When ok is True (true in Go) and last_test_status is succeeded, the credentials and network connection to the external mail service are valid.

  • When validation fails, inspect last_test_error, error_code, and suggestion on the response object to diagnose and fix the configuration.

Limitations and notes

  • test_channel_configuration connects to the external mail server to verify credentials, without persisting the configuration or updating last_test_status on saved channel instances. After the precheck passes, follow Configure WeCom enterprise mail in the console to save and bind the instance.

Next steps

Last updated on