Test the created channel instance¶

Verify the current credentials and connection configuration of the saved channel instance.

POST https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/channels/{provider}/instances/{instance_id}/test

Before you call¶

First query the channel instance details and confirm the instance to be tested. Prepare a personal access token with access to the target workspace, target workspace ID, channel provider ID, and instance ID.

The example below uses:

$AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.
$WORKSPACE_ID: Target workspace ID, passed through the X-Workspace-ID Header and also as workspace_id in the path.
$PROVIDER: Channel Provider ID, as provider in the path.
$INSTANCE_ID: Channel instance ID to test, as instance_id in the path.

Request example¶

curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/channels/$PROVIDER/instances/$INSTANCE_ID/test" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

Path parameters¶

Parameters	Type	Is it required	Description
`workspace_id`	string	Yes	Workspace ID.
`provider`	string	Yes	Channel Provider ID.
`instance_id`	string	Yes	Channel instance ID.

Successful response¶

Returns 200 on success. The test uses the current saved credentials and configuration and updates the instance’s most recent test information.

{
  "code": 0,
  "data": {
    "instance": {
      "id": "inst_01",
      "workspace_id": "ws_01",
      "provider": "wecom",
      "channel_type": "wecom_mail",
      "name": "告警通道",
      "status": "active"
    },
    "ok": true,
    "status": "passed",
    "last_test_status": "passed",
    "last_tested_at": "2026-08-18T01:00:00Z"
  }
}

When the external connection test fails but the test request is processed normally, the interface still returns 200:

{
  "code": 0,
  "data": {
    "instance": {
      "id": "inst_01",
      "provider": "wecom"
    },
    "ok": false,
    "status": "failed",
    "last_test_status": "failed",
    "last_test_error": "<错误信息>",
    "error_code": "<ERROR_CODE>",
    "error_stage": "<STAGE>",
    "provider_error_code": "<PROVIDER_CODE>",
    "provider_error_message": "<PROVIDER_MESSAGE>",
    "error_category": "<CATEGORY>",
    "suggestion": "<SUGGESTION>",
    "last_tested_at": "2026-08-18T01:00:00Z"
  }
}

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` when the test request is successfully processed, even if the connection test itself fails.
`data.instance`	object	An insensitive projection of the instance under test.
`data.ok`	boolean	Whether the connection test passed.
`data.status`	string	This and the latest test status.
`data.last_test_status`	string	This and the latest test status.
`data.worker_id`	string	The performer and request ID returned when available.
`data.request_id`	string	The performer and request ID returned when available.
`data.last_test_error`	string	Error message when the test fails.
`data.error_code`	string	The error code, stage, and category of the service classification.
`data.error_stage`	string	The error code, stage, and category of the service classification.
`data.error_category`	string	The error code, stage, and category of the service classification.
`data.provider_error_code`	string	Error message returned by Provider; returned when available.
`data.provider_error_message`	string	Error message returned by Provider; returned when available.
`data.suggestion`	string	Actionable fix suggestion; returned when available.
`data.last_tested_at`	string	Test time, using RFC 3339 format.

Error response¶

{
  "code": 2,
  "message": "<错误信息>"
}

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`2`（`INVALID_ARGUMENT`）	Provider, instance ID, saved configuration, or credentials are not available.	Check the path; update configuration or resave credentials if necessary.
`401`	`6`（`UNAUTHENTICATED`）	Lack of valid identity credentials.	Check API Key.
`403`	`5`（`PERMISSION_DENIED`）	The current identity does not have permissions for the test instance, or the credential access is denied.	Check workspace and provider side permissions.
`404`	`3`（`NOT_FOUND`）	The instance does not exist or does not belong to the Provider in the path.	Check the Provider and Instance ID.
`503`	`15`（`UNAVAILABLE`）	Channel instance services or test dependencies are temporarily unavailable.	Try again later.

Follow-up operations¶

When the connection fails Update channel instance, then retest.

Last updated on Sep 3, 2026