Docs
Contents

Message Targets (User Targets)

Feature Overview

Message Target is a specific message delivery terminal address bound under an Agentbase Auth User, covering three channel types: Email address, SMS short code/mobile number, and client device push token (Push Token, such as APNs / FCM device identifiers). In enterprise applications (for example, "Enterprise Intelligent Customer Service and Knowledge Hub enterprise-ai-hub-210"), the same natural person user (such as architect user_zhangwei_001 Zhang Wei) often simultaneously owns a work email, an on-call mobile number, and a mobile office App device token. When the Messaging service performs P1 incident alert broadcasts, support ticket status change notifications, or knowledge base publication reminders, it does not send physical messages directly to the abstract userId; instead, it resolves the user or Topic into the valid-state Targets under that user, and then routes them by the Target's providerType (email / sms / push) to the corresponding third-party Messaging Provider to complete final delivery.

By decoupling "User Identity (User)" and "Communication Terminal (Target)" into a one-to-many model, Agentbase achieves fine-grained multi-channel reach governance: it supports automatically deriving a primary email and mobile number Target when creating a user, dynamically registering and rotating mobile Push device tokens through the Server API, subscribing specific Targets to different message Topics (Topic Subscriber), and one-click cleanup of invalid terminals from the Console when a user deregisters or a device is reported lost.

Core Concepts and Architecture

Message Targets span three core subsystems: Auth Users, Messaging Topics, and Messaging Providers. Their architectural relationships are as follows:

Message Targets (User Targets): workflow diagram, not a runtime screenshot

Flow diagram, not a runtime screenshot; read the relationships between steps or states along the arrows.

View the flow diagram in full size

Core Concepts and Field Definitions

Core concept / attribute fieldIdentifier / TypeArchitectural responsibility and business semantics
Message Target$id (targetId)A communication destination entity belonging to a single userId, globally unique at the user dimension, with a lifecycle controlled by the owning user (deleting a user cascades into cleanup of all of their Targets).
Channel type (providerType)email | sms | pushIdentifies the communication channel category through which this Target receives messages, determining the Provider type matched during message delivery and the identifier validation format.
Terminal identifier (identifier)stringThe actual delivery address: email channel uses a standard RFC 5322 email address; sms channel uses an E.164 formatted mobile number with international country code (e.g., +8613800138001); push channel uses an FCM Registration Token or APNs Device Token obtained by the client SDK.
Bound provider (providerId)string | nullAn optional binding to a specific Messaging Provider instance ID. If empty, messages are automatically routed at send time to the current project's enabled default Provider of the same type.
Terminal name (name)string (up to 128 characters)A human-readable remark name (e.g., 张伟的 iPhone 16 Pro 值班机), mainly used for distinguishing push type devices and for operational identification in the Console.
Session association (sessionId)string | nullThe optional Session ID associated when the client registers a Push Target through a session; useful for identifying device status when that session logs out or is expired and cleaned up.
Expired flag (expired)booleanIndicates whether this Target has been marked as an invalid terminal by the remote channel (e.g., APNs / FCM reporting Unregistered).

Roles, Entry Points, and Relationships

Applicable Roles and Responsibility Division

Role nameCore use scenarioRequired permission scope (Role / API Scope)
Organization administrator / Security administratorAudit user-bound emails, mobile numbers, and push devices in the Console; clean up Targets of departed employees or reported-lost devicesConsole owner / admin / developer roles
Backend application development engineerUse the Server SDK / REST API to batch import backup notification emails, on-call mobile numbers, or bind custom Providers for usersAPI Key with users.read, targets.read, targets.write
Mobile / frontend development engineerObtain the system Push Token after user login in the App and register it as a Push Target of the current accountClient Session authentication (calling the Account Push Target endpoint) or proxied registration via the business backend
Operations on-call managerAdd Targets of VIP architects and on-call engineers to alert Topics (e.g., topic_sla_p1_alerts) and verify delivery receipts in the Message CenterConsole access + messages.read, topics.write, subscribers.write

Console Entry and Navigation Path

  1. Log in to the Agentbase Console and enter the project 企业智能客服与知识中台 (enterprise-ai-hub-210) under the target organization (e.g., Agentbase 企业智能中台).

  2. In the left main navigation bar, select "Build" -> "Auth" (/auth); the "Users" (Users) list page opens by default.

  3. Click the target user row (e.g., user_zhangwei_001 Zhang Wei) to enter the user details view.

  4. In the horizontal tab bar at the top of the user details page, switch to the "Targets" (Message Targets) tab (path: /console/project-default-enterprise-ai-hub-210/auth/user-user_zhangwei_001/targets).

Relationships with Upstream and Downstream Modules

Feature Details and Operation Guide

1. Automatic Generation and Lifecycle Synchronization Mechanism

In Agentbase, a user's basic communication profile stays automatically in sync with Targets, reducing manual repeated configuration:

  1. Automatic derivation on user creation:

    • In the Console under "Auth -> Users -> Create User" or when calling POST /v1/users, as long as email is filled in (e.g., zhangwei@enterprise.example.com), the system immediately generates a providerType = "email" Target.

    • If an E.164-compliant phone is also filled in (e.g., +8613800138001), the system simultaneously generates a providerType = "sms" Target.

  2. Synchronization on user contact info modification:

    • When an administrator modifies a user's email or mobile number on the user details page, the associated automatic Target identifier (identifier) is updated accordingly.

  3. Cascade cleanup on user deletion:

    • When an Auth user is deleted, all Targets under that user and the associated Topic Subscriber records are removed in the same cleanup process, ensuring no marketing or alert messages continue to be sent to deregistered users.

2. Registering Expansion Targets via Server API / SDK (Push Devices and Backup Notification Channels)

On the user details Targets tab, an authorized user can click Create target, choose a channel, and enter the recipient identifier. Name, target ID, and provider ID are optional. Alternatively, call POST /v1/users/{userId}/targets via the Server API or SDK. Actual delivery also requires a provider for the selected channel.

Create target form with email, SMS, and push channel choices

Empty form for a test user; no target was created and no message was sent.

Request Parameter Specification (POST /v1/users/{userId}/targets)

Parameter nameTypeRequiredValidation rules and default value description
userIdstringYesPath parameter, the $id of the target Auth user (e.g., user_zhangwei_001).
targetIdstringNoCustom Target ID (up to 36 characters; only letters, digits, periods, hyphens, and underscores allowed, and it must not start with a special character); when "unique()" is passed or omitted, the server automatically generates a unique ID.
providerTypestringYesChannel enum value; only one of email, sms, push is allowed.
identifierstringisdelivery endpoint address: email must pass valid email format validation; sms must be an E.164 phone number starting with + and no more than 15 digits; push is a non-empty device Token string.
providerIdstringNoAssociated Messaging Provider ID (e.g., a specified APNs or FCM Provider ID); when omitted, the project's default Provider of the same type is used.
namestringNoTerminal display name (1–128 characters); for push devices, a readable name such as iOS-P1-OnCall-Device is recommended.

Operation Steps and Executable Command Examples

The following example demonstrates how to use the project API Key (with the targets.write and targets.read permission scopes checked) to register an iOS mobile push device Target for VIP architect user_zhangwei_001 and query all valid Targets under that user:

Step 1: Create the device target; confirm HTTP 2xx and inspect the result.

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS -X POST "${APPBASE_ENDPOINT}/users/user_zhangwei_001/targets" -f -i \
  -H "Content-Type: application/json" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -d '{
    "targetId": "tgt_zhangwei_ios_oncall",
    "providerType": "push",
    "identifier": "apns_prod_token_9f8e7d6c5b4a3210fedcba9876543210",
    "name": "张伟-iPhone16Pro-值班终端"
  }'
)

Step 2: List the user’s device targets separately after creation succeeds.

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS -X GET "${APPBASE_ENDPOINT}/users/user_zhangwei_001/targets" -f -i \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @-
)

Expected returns are HTTP 201 Created (creation) and 200 OK (list query); the response body contains the automatically generated Email/SMS Targets and the newly created Push Target:

{
  "total": 3,
  "targets": [
    {
      "$id": "6ad9ec41001122334455",
      "$createdAt": "2026-10-22T10:42:15.000+00:00",
      "$updatedAt": "2026-10-22T10:42:15.000+00:00",
      "name": "",
      "userId": "user_zhangwei_001",
      "providerId": null,
      "providerType": "email",
      "identifier": "zhangwei@enterprise.example.com",
      "expired": false
    },
    {
      "$id": "6ad9ec410066778899aa",
      "$createdAt": "2026-10-22T10:42:15.000+00:00",
      "$updatedAt": "2026-10-22T10:42:15.000+00:00",
      "name": "",
      "userId": "user_zhangwei_001",
      "providerId": null,
      "providerType": "sms",
      "identifier": "+8613800138001",
      "expired": false
    },
    {
      "$id": "tgt_zhangwei_ios_oncall",
      "$createdAt": "2026-10-22T11:20:00.000+00:00",
      "$updatedAt": "2026-10-22T11:20:00.000+00:00",
      "name": "张伟-iPhone16Pro-值班终端",
      "userId": "user_zhangwei_001",
      "providerId": null,
      "providerType": "push",
      "identifier": "apns_prod_token_9f8e7d6c5b4a3210fedcba9876543210",
      "expired": false
    }
  ]
}

3. Viewing, Auditing, and Batch-Cleaning Message Targets in the Console

  1. Navigate to 认证 -> 用户 -> click user_zhangwei_001 -> Targets tab.

  2. The list table shows the following key operational columns:

    • Target ID: the target's unique identifier (supports one-click copy $id, used for configuring precise delivery in Messaging or troubleshooting subscription relationships).

    • Target: for push type, prioritizes display of the readable name (e.g., 张伟-iPhone16Pro-值班终端); for email and sms types, displays the specific email address or mobile number identifier.

    • Type: displays the channel label (Email / SMS / Push).

    • Provider: displays the explicitly bound Messaging Provider name or ID; empty when the project default channel is used.

    • Created: the target registration timestamp.

  3. Batch unbinding and cleanup of invalid terminals:

    • When an employee changes phones, uninstalls the client App, or departs, check the corresponding checkboxes on the left side of the table; a batch action bar will appear at the bottom or top.

    • Click "Delete" and confirm again in the confirmation dialog to immediately remove the selected Targets. After deletion, any messages sent to that user or associated Topic will no longer be delivered to that terminal.

FAQ and Troubleshooting

Issue 1: Calling POST /v1/users/{userId}/targets returns 409 Conflict (user_target_already_exists)?

Issue 2: When sending a message to a user or topic in the Messaging module, the status shows a failure or an error indicates that no available recipient target was found?

Issue 3: When managing user Targets with an API Key, 401 Unauthorized (missing scopes (["targets.write"])) is returned?