快速开始

阅读指引：本篇带你走完一次完整的接入流程：准备资料、取得凭据、验证环境、完成授权、发出第一条消息。各步骤的接口字段细节见对应的服务端 API 文档。

接入流程总览

当前不提供第三方自助创建应用的 OpenAPI。请向平台管理员提交应用资料，由管理员完成创建、授权与发布，再安全交付接入凭据。

开发者提交资料
  → 管理员检查 app_identifier 是否占用
  → 创建应用草稿
  → 配置能力 Scope、应用发布范围、可信域名、完整 oauth_callback_uri
  → 应用后端部署 Webhook 验签与验证响应
  → 管理员配置并验证 webhook_url
  → 管理员在首次发布时确认完整能力范围和完整发布范围
  → 从后台详情安全交付 app_key + app_secret + sign_key
  → 应用后端开始 OAuth2/OpenAPI 联调

注意：第三方应用系统的接入不等于开放平台注册或应用管理权限。

第一步：准备应用资料

第二步：取得接入凭据

管理员在应用创建并验证 Webhook 后交付以下凭据，务必通过安全渠道接收：

第三步：获取应用 Token 并验证环境

POST /openapi/v1/oauth2/token，推荐使用 HTTP Basic 传递凭据：

curl -X POST "${OPENAPI_BASE_URL}/openapi/v1/oauth2/token" \
  -u "${APP_KEY}:${APP_SECRET}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials"

返回包含 access_token（有效期以 expires_in 为准）、refresh_token 与 scope 即表示凭据可用。Token 须按 expires_in 全局缓存复用，不要每次调用接口都重新获取。详见《应用级 Token》。

第四步：完成一次用户授权

按应用形态二选一：

• H5 页面（不依赖 JSSDK）：构造 GET /openapi/v1/oauth2/authorize 地址并导航，平台 302 回调 redirect_uri 携带 code，应用后端用 code 换用户 Token。
• 客户端内 H5（接入 JSSDK）：页面调用 getAuthCode 获取授权码（无需 config），交给应用后端换用户 Token。

两种方式都要求 redirect_uri 与管理员登记的回调 URI 精确一致，并校验 state。详见《身份授权》与《用户授权 OAuth2》。

第五步：发送第一条消息

用应用 Token 向授权用户发送一条文本消息：

curl -X POST "${OPENAPI_BASE_URL}/openapi/v1/messages/send" \
  -H "Authorization: Bearer ${APP_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "demo_20260921_0001",
    "recipient": {
      "type": "user",
      "ids": ["20001"]
    },
    "message": {
      "type": "text",
      "payload": {
        "content": "接入联调成功。"
      }
    }
  }'

request_id 是幂等标识，同一次重试必须复用原值和完全相同的内容。消息类型、接收目标与 Scope 的完整规则见《发送应用消息》。

下一步

• 需要接收用户回复和事件：先在应用后端实现 Webhook 验签，再让管理员配置 webhook_url，见《消息与素材》。
• 需要同步组织架构：申请 contact:organization:read 能力后按《目录与群数据同步》开发。
• 需要在 H5 中调用客户端能力：阅读《JSSDK 快速开始》完成 config 初始化。