跳转到主要内容

Witime RCS API — 集成指南

目的​

本文档仅介绍 Witime RCS API 的公开契约，包括身份验证、数据格式、响应、错误，以及所有面向客户端的接口集成示例。

通用信息​

基础 URL​

请将示例中的 https://rcs-api.witi.me 替换为您的环境所提供的 URL。

https://rcs-api.witi.me

数据格式​

请求和响应均使用 JSON，属性名采用 camelCase 格式。

Content-Type: application/json
Accept: application/json

身份验证​

所有请求都必须包含 X-Api-Key 请求头：

X-Api-Key: YOUR_ACCESS_KEY

缺少密钥或密钥无效时，将返回 401 Unauthorized：

{
  "error": {
	"code": "AUTHENTICATION_FAILED",
	"message": "Invalid API key."
  }
}

请求关联​

X-Correlation-Id 请求头为可选项。提供该请求头时，响应会返回相同的值；未提供时，API 会生成一个格式为 corr_<guid> 的标识符。

X-Correlation-Id: order-2026-0001

幂等性​

发送消息和发送模板的请求支持可选的 Idempotency-Key 请求头。

Idempotency-Key: send-2026-0001

使用相同的密钥和内容重试同一请求时，会返回原始响应。使用相同密钥提交不同内容时，会返回 409 Conflict：

{
  "error": {
	"code": "DUPLICATE_IDEMPOTENCY_KEY",
	"message": "A different request was already sent with the same Idempotency-Key."
  }
}

请求体校验​

GET 请求不包含请求体。对于 POST 请求，空请求体会返回 400 Bad Request 和错误代码 EMPTY_BODY。JSON 格式错误时会返回：

{
  "error": {
	"code": "INVALID_JSON",
	"message": "Request body contains invalid JSON."
  }
}

C# 示例的通用设置​

C# 示例使用 HttpClient 和 System.Net.Http.Json。以下变量在每个示例中均可使用：

using System.Net.Http.Json;
using System.Text;
using System.Text.Json;

var baseUrl = "https://rcs-api.witi.me";
var apiKey = "YOUR_ACCESS_KEY";
using var client = new HttpClient();

1. 检查服务可用性​

检查 API 是否正常响应。此请求不会检查任何其他服务。

GET /health

cURL​

curl -X GET "https://rcs-api.witi.me/health" \
	-H "X-Api-Key: YOUR_ACCESS_KEY"

C#​

using var request = new HttpRequestMessage(HttpMethod.Get, $"{baseUrl}/health");
request.Headers.Add("X-Api-Key", apiKey);

using var response = await client.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();
response.EnsureSuccessStatusCode();
Console.WriteLine(responseBody);

响应 200 OK​

{
  "status": "ok"
}

2. 发送消息​

向一个或多个收件人发送消息。

POST /v1/messages

请求字段​

字段类型必填说明
senderProfileIdstring是发送方配置文件标识符。
routeint是要使用的路由 ID。
campaignNamestring否活动名称。
channelstring是请求的渠道：rcs 或 sms。
messageobject是消息内容。提供 template 字段时，此字段非必填。
templateint否预配置的 RCS 模板。
recipientsarray是至少包含一位收件人的列表。

每位收件人包含：

字段类型必填说明
phonestring是包含国家/地区代码和区号的电话号码。

支持的内容类型​

message.type使用的字段
texttext
imageurl
videourl 和可选的 text
pdfurl 和可选的 filename
suggestiontext 和 suggestions
rich-cardtitle、description、url、orientation、alignment 和 suggestions
carouselcards，每张卡片包含 rich-card 的字段

建议操作支持 title、value、type，以及可选的显示、位置和日历字段。支持的类型：openurl、openurlwebview、call、reply、viewlocationaction、sharelocationaction 和 createcalendareventaction。

请求示例​

{
  "route": 123,
  "campaignName": "welcome-2026",
  "senderProfileId": "snd_default",
  "channel": "rcs",
  "message": {
    "type": "text",
    "text": "您好！您的注册已完成。"
  },
  "recipients": [
    {
      "phone": "5511999999999"
    }
  ]
}

cURL​

curl -X POST "https://rcs-api.witi.me/v1/messages" \
  -H "X-Api-Key: YOUR_ACCESS_KEY" \
  -H "X-Correlation-Id: order-2026-0001" \
  -H "Idempotency-Key: send-2026-0001" \
  -H "Content-Type: application/json" \
  --data '{
    "route": 123,
    "campaignName": "welcome-2026",
    "senderProfileId": "snd_default",
    "channel": "rcs",
    "message": {
      "type": "text",
      "text": "您好！您的注册已完成。"
    },
    "recipients": [
      {
        "phone": "5511999999999"
      }
    ]
  }'

C#​

var payload = new
{
    route = 123,
    campaignName = "welcome-2026",
    senderProfileId = "snd_default",
    channel = "rcs",
    message = new
    {
        type = "text",
        text = "您好！您的注册已完成。"
    },
    recipients = new[]
    {
        new
        {
            phone = "5511999999999"
        }
    }
};

using var request = new HttpRequestMessage(HttpMethod.Post, $"{baseUrl}/v1/messages")
{
    Content = JsonContent.Create(payload)
};
request.Headers.Add("X-Api-Key", apiKey);
request.Headers.Add("X-Correlation-Id", "order-2026-0001");
request.Headers.Add("Idempotency-Key", "send-2026-0001");

using var response = await client.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();
response.EnsureSuccessStatusCode();
Console.WriteLine(responseBody);

响应 200 OK​

{
  "batchId": "batch_01",
  "status": "accepted",
  "messages": [
    {
      "messageId": "msg_01",
      "recipient": "5511999999999",
      "status": "accepted"
    }
  ],
  "rejected": []
}

可能的校验错误：INVALID_ACCOUNT、INVALID_APIKEY、INVALID_BASEURL、INVALID_RECIPIENTS 和 INVALID_MESSAGE。

3. 查询消息​

使用发送消息时返回的标识符查询消息。

GET /v1/messages/{messageId}

cURL​

curl -X GET "https://rcs-api.witi.me/v1/messages/msg_01" \
  -H "X-Api-Key: YOUR_ACCESS_KEY"

C#​

var messageId = "msg_01";
using var request = new HttpRequestMessage(HttpMethod.Get, $"{baseUrl}/v1/messages/{Uri.EscapeDataString(messageId)}");
request.Headers.Add("X-Api-Key", apiKey);

using var response = await client.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();
response.EnsureSuccessStatusCode();
Console.WriteLine(responseBody);

响应 200 OK​

{
  "messageId": "msg_01",
  "status": 10,
  "recipient": "5511999999999",
  "deliverDate": "2026-09-24T10:21:47"
}

如果标识符不存在，则返回 404 Not Found。

4. 查询模板列表​

返回该账户可用的模板。

GET /v1/templates

cURL​

curl -X GET "https://rcs-api.witi.me/v1/templates" \
  -H "X-Api-Key: YOUR_ACCESS_KEY"

C#​

using var request = new HttpRequestMessage(HttpMethod.Get, $"{baseUrl}/v1/templates");
request.Headers.Add("X-Api-Key", apiKey);

using var response = await client.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();
response.EnsureSuccessStatusCode();
Console.WriteLine(responseBody);

响应 200 OK​

[
  {
    "templateId": "tpl_01",
    "name": "欢迎"
  }
]

5. 查询模板​

使用模板标识符查询模板。

GET /v1/templates/{templateId}

cURL​

curl -X GET "https://rcs-api.witi.me/v1/templates/tpl_01" \
  -H "X-Api-Key: YOUR_ACCESS_KEY"

C#​

var templateId = "tpl_01";
using var request = new HttpRequestMessage(HttpMethod.Get, $"{baseUrl}/v1/templates/{Uri.EscapeDataString(templateId)}");
request.Headers.Add("X-Api-Key", apiKey);

using var response = await client.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();
response.EnsureSuccessStatusCode();
Console.WriteLine(responseBody);

响应 200 OK​

{
  "templateId": "tpl_01",
  "name": "欢迎"
}

如果标识符不存在，则返回 404 Not Found。

HTTP 状态码​

状态码含义
200请求已处理。
400请求体为空、JSON 无效或必填数据无效。
401访问密钥缺失或无效。
404未找到消息或模板。
409幂等键被用于不同的请求内容。
500处理过程中发生意外错误。

集成建议​

  • 请勿将访问密钥写入源代码。
  • 每个逻辑发送操作都应生成唯一的 Idempotency-Key。
  • 记录响应中返回的 X-Correlation-Id。
  • 保存返回的 batchId 和 messageId。
  • 反序列化预期结果之前，先处理非 2xx 响应。
  • 为 HTTP 请求设置超时并支持取消。
  • 不要依赖 JSON 属性的顺序。
  • 电话号码请使用国际格式，且仅包含数字。