sinch-conversation-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sinch Conversation API

Overview

概述

One unified API to send and receive messages across SMS, WhatsApp, RCS, MMS, Viber Business, Facebook Messenger, Instagram, Telegram, KakaoTalk, KakaoTalkChat, LINE, WeChat, and Apple Messages for Business. The API transcodes between a generic message format and channel-specific formats automatically.

Auth: OAuth2 bearer token (recommended) or HTTP Basic (

keyId:keySecret

, testing only — heavily rate limited). See sinch-authentication for setup.

通过一个统一的API，即可在SMS、WhatsApp、RCS、MMS、Viber Business、Facebook Messenger、Instagram、Telegram、KakaoTalk、KakaoTalkChat、LINE、微信和Apple Business Messages等渠道发送和接收消息。该API会自动在通用消息格式和各渠道专属格式之间进行转码。

认证方式： 推荐使用OAuth2承载令牌，或HTTP Basic认证（仅用于测试——有严格的速率限制）。设置方法请参考sinch-authentication。

Key Concepts

核心概念

Apps — Container for channel integrations. Each app has channels, webhooks, and a processing mode. Created via dashboard or API. Contacts — End-users with channel identities. Auto-created in CONVERSATION mode. Conversations — Message threads between app and contact. Only exist in CONVERSATION mode. Processing modes —

DISPATCH

(default): no contacts/conversations, for high-volume unidirectional SMS.

CONVERSATION

: auto-creates contacts/conversations, enables 2-way flows. Set per app. Message types —

text_message

media_message

card_message

carousel_message

choice_message

list_message

template_message

location_message

contact_info_message

. See Message Types. Channel fallback — Set

channel_priority_order

to try channels in sequence.

SWITCHING_CHANNEL

status indicates fallback. Delivery statuses —

QUEUED_ON_CHANNEL

→

DELIVERED

→

READ

, or

FAILED

SWITCHING_CHANNEL

when fallback occurs. Webhooks — Up to 5 per app. Default callback rate: 25/sec. 21 usable triggers — most common:

MESSAGE_INBOUND

MESSAGE_DELIVERY

EVENT_INBOUND

. See Callbacks & Webhooks for full trigger list. HMAC validation — Signature:

HMAC-SHA256(rawBody + '.' + nonce + '.' + timestamp, secret)

. Headers:

x-sinch-webhook-signature

-timestamp

-nonce

-algorithm

. Templates — Pre-defined messages with parameter substitution. Managed at

{region}.template.api.sinch.com

(V2 only — V1 no longer accessible). See references/templates.md. Batch sending — Up to 1000 recipients with

${parameter}

substitution. Base URL:

{region}.conversationbatch.api.sinch.com

. See references/batch.md.

Supported channels:

SMS

WHATSAPP

RCS

MMS

VIBERBM

MESSENGER

INSTAGRAM

TELEGRAM

KAKAOTALK

KAKAOTALKCHAT

LINE

WECHAT

APPLEBC

. Channel-specific details: SMS, WhatsApp, RCS, MMS. See Channel Support.

应用（Apps） —— 渠道集成的容器。每个应用包含渠道、Webhook和处理模式，可通过控制台或API创建。 联系人（Contacts） —— 拥有渠道身份标识的终端用户。在CONVERSATION模式下会自动创建。 对话（Conversations） —— 应用与联系人之间的消息线程。仅在CONVERSATION模式下存在。 处理模式 ——

DISPATCH

（默认）：无联系人/对话，适用于高容量单向SMS。

CONVERSATION

：自动创建联系人/对话，支持双向消息流。每个应用可单独设置模式。 消息类型 ——

text_message

、

media_message

、

card_message

、

carousel_message

、

choice_message

、

list_message

、

template_message

、

location_message

、

contact_info_message

。详情请见消息类型。 渠道降级 —— 设置

channel_priority_order

数组，按顺序尝试不同渠道。

SWITCHING_CHANNEL

状态表示触发了降级流程。 送达状态 ——

QUEUED_ON_CHANNEL

→

DELIVERED

→

READ

，或

FAILED

。触发降级时会显示

SWITCHING_CHANNEL

。 Webhook —— 每个应用最多可配置5个。默认回调速率：25次/秒。支持21种可用触发事件，最常用的有：

MESSAGE_INBOUND

、

MESSAGE_DELIVERY

、

EVENT_INBOUND

。完整触发事件列表请见回调与Webhook。 HMAC验证 —— 签名规则：

HMAC-SHA256(rawBody + '.' + nonce + '.' + timestamp, secret)

。相关请求头：

x-sinch-webhook-signature

、

-timestamp

、

-nonce

、

-algorithm

。 模板消息 —— 支持参数替换的预定义消息。仅可通过

{region}.template.api.sinch.com

管理（仅V2版本——V1已无法访问）。详情请见references/templates.md。 批量发送 —— 支持最多1000个收件人，可使用

${parameter}

进行参数替换。基础地址：

{region}.conversationbatch.api.sinch.com

。详情请见references/batch.md。

支持的渠道：

SMS

、

WHATSAPP

、

RCS

、

MMS

、

VIBERBM

、

MESSENGER

、

INSTAGRAM

、

TELEGRAM

、

KAKAOTALK

、

KAKAOTALKCHAT

、

LINE

、

WECHAT

、

APPLEBC

。各渠道详情：SMS、WhatsApp、RCS、MMS。完整渠道支持列表请见渠道支持。

Getting Started

快速开始

Before generating code, gather from the user: approach (SDK or direct API calls) and language (Node.js, Python, Java, .NET/C#, curl). Do not assume defaults.

When the user chooses SDK, fetch the relevant SDK reference page linked in Quick Reference for accurate method signatures. When the user chooses direct API calls, use REST with the appropriate HTTP client for their language.

Language	Package	Install
Node.js	`@sinch/sdk-core`	`npm install @sinch/sdk-core`
Java	`com.sinch.sdk:sinch-sdk-java`	Maven dependency (see below)
Python	`sinch`	`pip install sinch`
.NET	`Sinch`	`dotnet add package Sinch`

生成代码前，请向用户确认：实现方式（SDK或直接API调用）和开发语言（Node.js、Python、Java、.NET/C#、curl）。请勿默认任何选项。

当用户选择SDK时，请参考快速参考中链接的对应SDK参考页面，以获取准确的方法签名。当用户选择直接API调用时，使用REST方式，并结合其语言对应的HTTP客户端。

语言	包名	安装方式
Node.js	`@sinch/sdk-core`	`npm install @sinch/sdk-core`
Java	`com.sinch.sdk:sinch-sdk-java`	Maven依赖（见下方）
Python	`sinch`	`pip install sinch`
.NET	`Sinch`	`dotnet add package Sinch`

Java Maven dependency

Java Maven依赖

Before generating the Maven dependency, look up the latest release version of

com.sinch.sdk:sinch-sdk-java

on Maven Central and use that version.

xml

<dependency>
    <groupId>com.sinch.sdk</groupId>
    <artifactId>sinch-sdk-java</artifactId>
    <version>LATEST_VERSION</version>
</dependency>

生成Maven依赖前，请先在Maven Central上查询

com.sinch.sdk:sinch-sdk-java

的最新版本，并使用该版本。

xml

<dependency>
    <groupId>com.sinch.sdk</groupId>
    <artifactId>sinch-sdk-java</artifactId>
    <version>LATEST_VERSION</version>
</dependency>

Base URL

基础地址

Regional — must match the Conversation API app region:

US:
```
https://us.conversation.api.sinch.com
```
EU:
```
https://eu.conversation.api.sinch.com
```
BR:
```
https://br.conversation.api.sinch.com
```

按区域划分——必须与Conversation API应用的区域匹配：

美国：
```
https://us.conversation.api.sinch.com
```
欧洲：
```
https://eu.conversation.api.sinch.com
```
巴西：
```
https://br.conversation.api.sinch.com
```

Send a Text Message (curl)

发送文本消息（curl示例）

bash

curl -X POST "https://us.conversation.api.sinch.com/v1/projects/{PROJECT_ID}/messages:send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "recipient": {
      "identified_by": {
        "channel_identities": [{
          "channel": "SMS",
          "identity": "+15551234567"
        }]
      }
    },
    "message": {
      "text_message": {
        "text": "Hello from Sinch Conversation API!"
      }
    },
    "channel_properties": {
      "SMS_SENDER": "+15559876543"
    }
  }'

For SDK examples, see the SDK references in Quick Reference.

bash

curl -X POST "https://us.conversation.api.sinch.com/v1/projects/{PROJECT_ID}/messages:send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "recipient": {
      "identified_by": {
        "channel_identities": [{
          "channel": "SMS",
          "identity": "+15551234567"
        }]
      }
    },
    "message": {
      "text_message": {
        "text": "Hello from Sinch Conversation API!"
      }
    },
    "channel_properties": {
      "SMS_SENDER": "+15559876543"
    }
  }'

SDK示例请见快速参考中的SDK链接。

Common Patterns

常见使用模式

Channel fallback — Add
```
channel_priority_order
```
array and list all channel identities in
```
recipient
```
. See Messages API Reference.
Recipient by contact ID — Use
```
{ "recipient": { "contact_id": "CONTACT_ID" } }
```
instead of
```
identified_by
```
when the contact already exists.

Rich messages —

card_message

carousel_message

choice_message

list_message

. See Message Types.

WhatsApp templates — Required outside the 24h service window. Use
```
template_message
```
with an approved template. See references/templates.md.
Webhooks — Register via
```
POST /webhooks
```
with
```
target
```
,
```
target_type: "HTTP"
```
, and
```
triggers
```
array. Each webhook target URL must be unique per app — attempting to register a duplicate target returns
```
400 INVALID_ARGUMENT
```
. See Webhooks API Reference.
Transcode —
```
POST /messages:transcode
```
to preview how a message renders on a specific channel without actually sending it. Useful for testing rich messages.

渠道降级 —— 添加
```
channel_priority_order
```
数组，并在
```
recipient
```
中列出所有渠道身份标识。详情请见消息API参考。
通过联系人ID指定收件人 —— 当联系人已存在时，使用
```
{ "recipient": { "contact_id": "CONTACT_ID" } }
```
替代
```
identified_by
```
。
富媒体消息 —— 包括
```
card_message
```
、
```
carousel_message
```
、
```
choice_message
```
、
```
list_message
```
。详情请见消息类型。
WhatsApp模板消息 —— 在24小时服务窗口外必须使用已审核通过的模板。使用
```
template_message
```
并指定已通过审核的模板。详情请见references/templates.md。
Webhook注册 —— 通过
```
POST /webhooks
```
接口注册，需指定
```
target
```
、
```
target_type: "HTTP"
```
和
```
triggers
```
数组。每个应用的Webhook目标URL必须唯一——尝试注册重复目标会返回
```
400 INVALID_ARGUMENT
```
。详情请见Webhook API参考。
消息转码预览 —— 调用
```
POST /messages:transcode
```
接口，可预览消息在指定渠道的呈现效果，无需实际发送。适用于测试富媒体消息。

Common Tasks

常见任务

Send a message — See Messages API Reference

List messages —

GET /v1/projects/{project_id}/messages

(filter by

messages_source

)

Events —
```
POST /events:send
```
for typing indicators, composing events
Capability lookup —
```
POST /capability:query
```
(async; result via
```
CAPABILITY
```
webhook)
Manage apps — See App API Reference
Manage contacts — See Contact API Reference. Includes merge, getChannelProfile, identityConflicts.
Manage conversations — See Conversation API Reference. Includes recent, stop, inject-message/event.
Manage webhooks — See Webhooks API Reference
Templates — See Template Management API and references/templates.md
Batch send — See Batch API and references/batch.md

发送消息 —— 请见消息API参考

列出消息 ——

GET /v1/projects/{project_id}/messages

（可通过

messages_source

过滤）

发送事件 ——
```
POST /events:send
```
接口可发送输入指示器、正在编辑事件等
能力查询 ——
```
POST /capability:query
```
（异步；结果通过
```
CAPABILITY
```
Webhook返回）
应用管理 —— 请见应用API参考
联系人管理 —— 请见联系人API参考，包括合并、获取渠道资料、身份冲突处理等功能。
对话管理 —— 请见对话API参考，包括最近对话、停止对话、注入消息/事件等功能。
Webhook管理 —— 请见Webhook API参考
模板管理 —— 请见模板管理API和references/templates.md
批量发送 —— 请见批量API和references/batch.md

Executable Scripts

可执行脚本

Bundled Node.js scripts in

scripts/

for sending messages (SMS, RCS text/card/carousel/choice/media/location/template), listing messages, and webhook CRUD. All read credentials from environment variables and support

--help

bash

export SINCH_PROJECT_ID="your-project-id"
export SINCH_KEY_ID="your-key-id"
export SINCH_KEY_SECRET="your-key-secret"
export SINCH_APP_ID="your-app-id"
export SINCH_REGION="us"  # us|eu|br, default: us

Examples:

node scripts/sms/send_sms.cjs --to +15551234567 --message "Hello"

node scripts/rcs/send_card.cjs --to +15551234567 --title "Sale" --image-url URL

node scripts/webhooks/create_webhook.cjs --app-id APP_ID --target URL --triggers MESSAGE_INBOUND,MESSAGE_DELIVERY

node scripts/common/list_messages.cjs --channel SMS --page-size 20

scripts/

目录下包含Node.js脚本，可用于发送消息（SMS、RCS文本/卡片/轮播/选项/媒体/位置/模板）、列出消息以及Webhook的增删改查。所有脚本均从环境变量读取凭证，并支持

--help

参数查看帮助。

bash

export SINCH_PROJECT_ID="your-project-id"
export SINCH_KEY_ID="your-key-id"
export SINCH_KEY_SECRET="your-key-secret"
export SINCH_APP_ID="your-app-id"
export SINCH_REGION="us"  # us|eu|br，默认值：us

示例：

node scripts/sms/send_sms.cjs --to +15551234567 --message "Hello"

node scripts/rcs/send_card.cjs --to +15551234567 --title "Sale" --image-url URL

node scripts/webhooks/create_webhook.cjs --app-id APP_ID --target URL --triggers MESSAGE_INBOUND,MESSAGE_DELIVERY

node scripts/common/list_messages.cjs --channel SMS --page-size 20

SDK & Code Generation

SDK与代码生成

For SDK code examples, refer to the official SDK syntax references:

For REST API payloads and field definitions, see:

Webhook trigger payloads: See references/webhooks/triggers/ for payload structure and key fields for all 21 trigger types.

SDK代码示例请参考官方SDK语法参考：

REST API的请求体和字段定义请参考：

Webhook触发事件请求体： 所有21种触发事件的请求体结构和关键字段请见references/webhooks/triggers/。

Gotchas and Best Practices

注意事项与最佳实践

Use OAuth2 in production. Cache tokens (expire in ~1 hour). Never use Basic Auth in production.
Rich messages transcoded to text on unsupported channels — test across target channels.
Implement idempotent webhook handlers — Sinch retries with exponential backoff.
Load credentials from environment variables. Never hardcode.
Always set the region explicitly in the client configuration. SDK clients must configure the region — do not rely on SDK defaults. Region mismatches between the client and the app cause
```
404
```
errors. All Conversation API URLs are region-specific (
```
{region}.conversation.api.sinch.com
```
). If you get a
```
404
```
, the most likely cause is a region mismatch — verify the app's region in the Sinch dashboard and configure the SDK/URL accordingly.
SDK naming varies across languages. Do not assume that method names, property paths, or service accessors are the same between SDKs (e.g., Python and Node.js may use different singular/plural forms for the same service). Always fetch the SDK reference docs for the target language before generating code — see the links in Quick Reference.
Error codes:
```
400
```
malformed or duplicate resource (e.g., webhook with same target already exists),
```
401
```
bad credentials,
```
403
```
no access/billing limit,
```
404
```
not found/region mismatch,
```
429
```
rate limit,
```
500/501/503
```
retry with backoff.
Messages not delivered: Verify app region matches base URL region (mismatches cause
```
404
```
). Check delivery status via webhook or
```
GET /messages/{message_id}
```
. WhatsApp: must be within 24h window or using an approved template. Channel fallback:
```
SWITCHING_CHANNEL
```
status means fallback occurred — each attempted channel may incur charges.
Webhook not receiving callbacks: Verify
```
target_type
```
is
```
HTTP
```
, target URL must be publicly reachable and return
```
2xx
```
, check triggers are correct — max 5 webhooks per app.
Rate limits (429): 800 requests/second per project across most endpoints. 500,000-message ingress queue per app, drained at 20 msg/sec by default. Channel-specific limits also apply.

生产环境请使用OAuth2认证。缓存令牌（有效期约1小时）。切勿在生产环境使用Basic Auth。
富媒体消息在不支持的渠道会被转码为文本——请在目标渠道进行测试。
实现幂等的Webhook处理器——Sinch会采用指数退避策略进行重试。
从环境变量读取凭证。切勿硬编码凭证。
务必显式设置区域 在客户端配置中。SDK客户端必须配置区域——不要依赖SDK默认值。客户端与应用的区域不匹配会导致
```
404
```
错误。所有Conversation API地址均为区域专属（
```
{region}.conversation.api.sinch.com
```
）。如果遇到
```
404
```
错误，最可能的原因是区域不匹配——请在Sinch控制台中验证应用的区域，并相应配置SDK/地址。
不同语言的SDK命名存在差异。不要假设不同SDK之间的方法名、属性路径或服务访问器是相同的（例如，Python和Node.js对同一服务可能使用单复数不同的形式）。生成代码前，请务必获取目标语言的SDK参考文档——请见快速参考中的链接。
错误代码说明：
```
400
```
请求格式错误或资源重复（例如，已存在相同目标的Webhook），
```
401
```
凭证无效，
```
403
```
无访问权限/超出计费限制，
```
404
```
资源不存在/区域不匹配，
```
429
```
超出速率限制，
```
500/501/503
```
请采用退避策略重试。
消息未送达： 验证应用区域与基础地址区域是否匹配（不匹配会导致
```
404
```
）。通过Webhook或
```
GET /messages/{message_id}
```
查看送达状态。WhatsApp：必须在24小时服务窗口内，或使用已审核通过的模板。渠道降级：
```
SWITCHING_CHANNEL
```
状态表示已触发降级——每次尝试的渠道都可能产生费用。
Webhook未收到回调： 验证
```
target_type
```
是否为
```
HTTP
```
，目标URL必须可公开访问并返回
```
2xx
```
状态码，检查触发事件是否正确——每个应用最多支持5个Webhook。
速率限制（429错误）： 大部分接口的速率限制为每个项目800次请求/秒。每个应用的消息入队队列容量为500,000条，默认处理速率为20条/秒。各渠道还有专属的速率限制。

sinch-conversation-api

Original

Translation

Sinch Conversation API

Sinch Conversation API

Overview

概述

Key Concepts

核心概念

Getting Started

快速开始

Java Maven dependency

Java Maven依赖

Base URL

基础地址

Send a Text Message (curl)

发送文本消息（curl示例）

Common Patterns

常见使用模式

Common Tasks

常见任务

Executable Scripts

可执行脚本

SDK & Code Generation

SDK与代码生成

Gotchas and Best Practices

注意事项与最佳实践

Links

相关链接