Back to Details

sinch-provisioning-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Sinch Provisioning API

Sinch Provisioning API

Overview

概述

Use this skill for Conversation API channel provisioning. Validated against Provisioning API v1.2.36. Prefer deterministic flows: confirm context, choose endpoint family, execute minimal calls, verify state.
本技能用于Conversation API渠道预配，已针对Provisioning API v1.2.36验证。 优先采用确定性流程：确认上下文、选择端点系列、执行最少调用、验证状态。

Agent Workflow (Default)

Agent工作流（默认）

Use this sequence unless the user requests otherwise.
  1. Confirm scope and identifiers
  • Confirm 
    projectId
  • Confirm microservice scope — each is a separate REST service: WhatsApp, RCS, KakaoTalk, Conversation, Webhooks, or Bundles
  1. Choose the endpoint family first
  • WhatsApp account/senders/templates/flows/solutions: 
    /v1/projects/{projectId}/whatsapp/...
  • RCS: 
    /v1/projects/{projectId}/rcs/...
  • KakaoTalk: 
    /v1/projects/{projectId}/kakaotalk/...
  • Conversation (channel info): 
    /v1/projects/{projectId}/conversation/...
  • Webhooks: 
    /v1/projects/{projectId}/webhooks...
  • Bundles: 
    /v1/projects/{projectId}/bundles...
  1. Apply safe defaults
  • Webhook 
    target
    must be unique per project
  • Use 
    ALL
    for webhook triggers when broad coverage is needed
  • WhatsApp template language delete: 
    deleteSubmitted
    defaults to 
    false
  1. Verify async operations
  • Some operations are asynchronous — register a provisioning webhook to receive completion notifications
  • Webhook payloads contain the full JSON response as payload
  • Alternatively, poll status endpoints for state changes
  • For bundles, subscribe to 
    BUNDLE_DONE
  1. Handle failures predictably
  • All endpoints return a PAPI Error (Provisioning API Error) on failure:
    json
    {
  "errorCode": "string (enum)",
  "message": "string (human-readable errorCode)",
  "resolution": "string (what can be changed/improved)",
  "additionalInformation": {} // optional, contains context e.g. senderId
}
  • For 
    429
    and 
    5xx
    , retry with bounded backoff (default: max 3 retries, exponential + jitter, max 10s delay)
  • For 
    4xx
    , use 
    resolution
    and 
    additionalInformation
    from the PAPI Error to guide correction
  1. Return actionable result
  • Include resource IDs, resulting state, and next required action
除非用户另有要求，否则请遵循以下步骤。
  1. 确认范围和标识符
  • 确认
    projectId
  • 确认微服务范围——每个都是独立的REST服务：WhatsApp、RCS、KakaoTalk、Conversation、Webhooks或Bundles
  1. 先选择端点系列
  • WhatsApp账户/发送方/模板/流程/解决方案：
    /v1/projects/{projectId}/whatsapp/...
  • RCS：
    /v1/projects/{projectId}/rcs/...
  • KakaoTalk：
    /v1/projects/{projectId}/kakaotalk/...
  • Conversation（渠道信息）：
    /v1/projects/{projectId}/conversation/...
  • Webhooks：
    /v1/projects/{projectId}/webhooks...
  • Bundles：
    /v1/projects/{projectId}/bundles...
  1. 应用安全默认值
  • 每个项目的Webhook 
    target
    必须唯一
  • 当需要广泛覆盖时，为webhook触发器使用
    ALL
  • WhatsApp模板语言删除：
    deleteSubmitted
    默认值为
    false
  1. 验证异步操作
  • 部分操作是异步的——注册预配webhook以接收完成通知
  • Webhook负载包含完整的JSON响应作为有效载荷
  • 或者，轮询状态端点以检查状态变化
  • 对于捆绑包，订阅
    BUNDLE_DONE
  1. 可预测地处理失败
  • 所有端点在失败时都会返回PAPI Error（Provisioning API Error）：
    json
    {
  "errorCode": "string (enum)",
  "message": "string (human-readable errorCode)",
  "resolution": "string (what can be changed/improved)",
  "additionalInformation": {} // optional, contains context e.g. senderId
}
  • 对于
    429
    和
    5xx
    错误，使用有界退避策略重试（默认：最多3次重试，指数退避+抖动，最大延迟10秒）
  • 对于
    4xx
    错误，使用PAPI Error中的
    resolution
    和
    additionalInformation
    来指导修正
  1. 返回可执行的结果
  • 包含资源ID、最终状态以及下一步所需操作

Getting Started

快速入门

Authentication

认证

See sinch-authentication for full auth setup.
Supported auth methods:
  • OAuth 2.0 bearer token (recommended)
  • HTTP Basic auth
Prefer OAuth 2.0 for automation/CI. Use Basic auth only for quick manual tests.
有关完整的认证设置，请参阅sinch-authentication。
支持的认证方式：
  • OAuth 2.0承载令牌（推荐）
  • HTTP Basic认证
自动化/CI场景优先使用OAuth 2.0。仅在快速手动测试时使用Basic认证。

Canonical curl Example

标准curl示例

bash
curl -X GET "https://provisioning.api.sinch.com/v1/projects/{PROJECT_ID}/whatsapp/senders" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
bash
curl -X GET "https://provisioning.api.sinch.com/v1/projects/{PROJECT_ID}/whatsapp/senders" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

Microservices

微服务

All endpoints are under 
https://provisioning.api.sinch.com/v1/projects/{projectId}/
. All return JSON responses. List endpoints are paginated; follow 
nextPageToken
to retrieve all results.
ServiceBase pathWhat it coversDocs
WhatsApp
/whatsapp/...
Accounts, senders (register/verify), templates, flows, solutionsAccounts, Senders, Templates, Flows, Solutions
RCS
/rcs/...
Accounts, senders (launch), questionnaire, test numbersAccounts, Senders, Questionnaire
KakaoTalk
/kakaotalk/...
Categories, senders (register/verify), templatesCategories, Senders, Templates
Bundles
/bundles/...
Orchestrator: create Conversation App, assign test number, link apps, create subproject, register webhooksBundles
Conversation
/conversation/...
Sender info for Instagram, Messenger, Telegram, ViberConversation
Webhooks
/webhooks/...
Provisioning webhook registration and managementWebhooks
所有端点都位于
https://provisioning.api.sinch.com/v1/projects/{projectId}/
下，均返回JSON响应。列表端点支持分页；请跟随
nextPageToken
获取所有结果。
服务基础路径覆盖范围文档
WhatsApp
/whatsapp/...
账户、发送方（注册/验证）、模板、流程、解决方案Accounts, Senders, Templates, Flows, Solutions
RCS
/rcs/...
账户、发送方（上线）、调查问卷、测试号码Accounts, Senders, Questionnaire
KakaoTalk
/kakaotalk/...
分类、发送方（注册/验证）、模板Categories, Senders, Templates
Bundles
/bundles/...
编排器：创建Conversation App、分配测试号码、关联应用、创建子项目、注册webhookBundles
Conversation
/conversation/...
Instagram、Messenger、Telegram、Viber的发送方信息Conversation
Webhooks
/webhooks/...
预配webhook的注册与管理Webhooks

Trigger Strategy (Webhook)

触发器策略（Webhook）

Use 
ALL
unless the user explicitly asks for selective triggers. If 
ALL
is used, do not combine it with other trigger values. For production, prefer selective triggers when broad audit coverage is not required.
When selective filtering is requested, choose by family:
  • WhatsApp account: 
    WHATSAPP_ACCOUNT_*
    , 
    WHATSAPP_WABA_ACCOUNT_CHANGED
  • WhatsApp sender/template: 
    WHATSAPP_SENDER_*
    , 
    WHATSAPP_TEMPLATE_*
  • RCS: 
    RCS_ACCOUNT_COMMENT_ADDED
    , 
    RCS_SENDER_*
  • KakaoTalk: 
    KAKAOTALK_SENDER_*
    , 
    KAKAOTALK_TEMPLATE_*
  • Bundles: 
    BUNDLE_DONE
除非用户明确要求选择特定触发器，否则请使用
ALL
。 如果使用
ALL
，请勿将其与其他触发器值组合。 对于生产环境，当不需要广泛的审计覆盖时，优先选择特定触发器。
当需要选择性过滤时，按系列选择：
  • WhatsApp账户：
    WHATSAPP_ACCOUNT_*
    , 
    WHATSAPP_WABA_ACCOUNT_CHANGED
  • WhatsApp发送方/模板：
    WHATSAPP_SENDER_*
    , 
    WHATSAPP_TEMPLATE_*
  • RCS：
    RCS_ACCOUNT_COMMENT_ADDED
    , 
    RCS_SENDER_*
  • KakaoTalk：
    KAKAOTALK_SENDER_*
    , 
    KAKAOTALK_TEMPLATE_*
  • Bundles：
    BUNDLE_DONE

Critical Gotchas

关键注意事项

  1. Sender OTP flow order is strict (WhatsApp and KakaoTalk)
  • Register first, then verify
  1. WhatsApp templates are project-level
  • Do not route through sender-scoped template paths
  1. Template delete behavior
  • Language-specific delete defaults to draft-only unless 
    deleteSubmitted=true
    (query flag)
  1. Webhook uniqueness constraint
  • Uniqueness is on 
    target
    URL per project, not on trigger overlap
  1. Async completion
  • Sender/template/account transitions can be asynchronous; rely on status endpoints or webhooks
  1. Deprecated WhatsApp utility endpoints
  • longLivedAccessToken
    and 
    wabaDetails
    are deprecated. Use only for legacy flows when explicitly requested.
  1. 发送方OTP流程顺序严格（WhatsApp和KakaoTalk）
  • 先注册，再验证
  1. WhatsApp模板是项目级的
  • 请勿通过发送方范围的模板路径访问
  1. 模板删除行为
  • 除非设置
    deleteSubmitted=true
    （查询参数），否则特定语言的删除默认仅针对草稿版本
  1. Webhook唯一性约束
  • 唯一性基于每个项目的
    target
    URL，而非触发器重叠
  1. 异步完成
  • 发送方/模板/账户的状态转换可能是异步的；请依赖状态端点或webhook
  1. 已弃用的WhatsApp工具端点
  • longLivedAccessToken
    和
    wabaDetails
    已弃用。仅在用户明确要求的遗留流程中使用。

Links

链接

Use these pages instead of adding inline examples.
请使用以下页面，而非添加内联示例。