Version: 1.0
Conversations API
概述
欢迎使用PaaSoo对话API，这是您跨多渠道无缝客户互动的门户！
通过这个强大的API，您可以通过WhatsApp、Telegram、Apple Messages for Business、Viber Business Messages等流行平台与您的客户建立联系。
通过简化各个渠道的沟通，Conversations API 使您能够提供卓越的客户体验。
Postman
要以交互方式探索我们的 API 端点并轻松发起请求，您可以访问我们的 Postman 公共集合。
身份验证
要使用 Conversations API 的功能，您需要使用 API 令牌对您的请求进行身份验证。
按照以下步骤开始：
- 通过我们直观的客户端生成唯一的 API 令牌。
- 在你发出的每个 API 请求的 Authorization 标头中包含生成的令牌。
以下是如何构建标题：
| Header | Description | Example |
|---|---|---|
| Authorization | Your API token | Bearer <API_TOKEN> |
响应与错误
Paasoo 会话 API 使用标准的 HTTP 状态码 来表示请求的结果。 以下是供您参考的常见状态码的非详尽列表。
| Status code | Description |
|---|---|
| 200 | successful request |
| 400 | bad request |
| 401 | Unauthorized access |
| 404 | Resource not found |
| 5xx | something went wrong on our end |
当请求出错时，API 将以以下格式的 JSON 正文进行响应：
{
"id": <id>,
"receivedTime": <receivedTime>,
"code": <errorCode>,
"message": "<errorMessage>"
}
响应错误代码详见下文。
| Http Status Code | Code | Message | Resolution |
|---|---|---|---|
| 400 | 4000 | Validation error | Check request body structure and ensure all required fields are present |
| 401 | 4001 | API Token is not valid | Verify your API token and regenerate if needed |
| 400 | 4002 | The user has unsubscribed | Remove contact from campaign or wait for user to re-subscribe |
| 400 | 4003 | Your balance is not sufficient for this transaction | Add credits to your account balance |
| 400 | 4004 | Missing parameters | Add missing required fields (type, to, content, channel) |
| 400 | 4005 | Parameters are invalid | Check parameter formats, lengths, and channel compatibility (see Supported Features section). For Apple Messages for Business this is also returned in reject mode when a payload violates an iOS 27 compliance rule (UUID identifiers, HTTPS URLs, PNG images, ISO Apple Pay codes, keyboardType, UI string/range limits); in warn mode the same violations are listed in the response warnings field instead. |
| 400 | 4006 | Not allowed to send free-form messages | Use approved templates (required for WhatsApp initial contact) or check channel restrictions |
| 400 | 4007 | Channel is not activated | Activate the channel in your account settings |
| 400 | 4010 | Tag not found | Verify the tag ID exists in your account |
| 400 | 4011 | Tag already exists | Use a different tag name or update the existing tag |
| 400 | 4020 | Contact not found | Verify the contact ID exists in your account |
| 400 | 4021 | failover timeoutSeconds param illegal | Ensure timeoutSeconds value is within valid range |
| 400 | 4022 | failover channel max size | Reduce the number of failover channels in the chain |
| 400 | 4023 | failover channel duplicate | Remove duplicate channels from failover configuration |
| 400 | 4024 | Template not found | Verify the template ID and check approval status in your account |
| 400 | 4025 | Template validate error: | Check template parameters and format against template definition |
| 400 | 4026 | WhatsApp Cloud API template error | The Meta (WhatsApp) Cloud API rejected the request. The message field contains the user-facing reason from Meta (e.g. duplicate template name, invalid component). |
| 400 | 4051 | Sender is unavailable | Verify WhatsApp sender is properly configured and available |
| 529 | 4052 | Too Many Requests | The channel has been throttled, please try again later |
| 400 | 4053 | Unsupported Operation | Viber templates do not support modifications |
| 400 | 4054 | Unsupported Operation | Template management for this channel is not currently supported |
| 400 | 4055 | Unsupported Operation | Viber template mismatch |
| 400 | 4060 | Invalid channel user ID | Provide a valid WhatsApp Business-Scoped User ID (BSUID) in CC.alphanumeric format, e.g. US.DDC91135R |
| 404 | 4065 | Media not found | Verify the media ID exists and was uploaded by your account |
| 400 | 4066 | File too large | Ensure the file does not exceed the 200 MB limit |
| 400 | 4067 | Unsupported file type | Use a supported MIME type (see Media and WhatsApp Media endpoint descriptions) |
| 400 | 4068 | Media download failed | Verify the URL is publicly accessible and returns a valid response |
| 500 | 4069 | Upstream provider unavailable | Retry the request; if the issue persists contact support |
| 400 | 4070 | File is empty | The uploaded file has no content (0 bytes); upload a non-empty file |
| 400 | 4071 | IP address is not allowed | Your account has an IP whitelist configured; add the request IP to the whitelist or call from an allowed IP |
| 400 | 4080 | The number of template ids exceeds the maximum of 10 | Limit the template analytics request to 10 or fewer template IDs |
| 400 | 4081 | Invalid date format; YYYY-MM-DD is required when useWabaTimezone is true | Send start/end as YYYY-MM-DD when useWabaTimezone is true |
| 400 | 4082 | End date must not be earlier than start date | Ensure end is on or after start in the query window |
| 400 | 4084 | WhatsApp template analytics error | The Meta template analytics API rejected the request; see the message field for the reason from Meta |
| 400 | 4085 | Start and end must not be in the future | Use a start/end date or epoch that is today or earlier |
| 400 | 4090 | Contact field does not exist for this app | Pass only AppField codes that are defined under your app in invitation-link contactFields |
| 400 | 4091 | Contact field value too long | Keep each contactFields value to 200 characters or fewer |
| 400 | 4092 | Invitation URL too long | Reduce the number/size of parameters so the generated URL is 2000 characters or fewer |
| 400 | 4093 | Contact field value invalid | Remove injection patterns (e.g. <script>, javascript:) from contactFields values |
Error Handling Best Practices:
- Always check the
codefield in the response to identify the specific error - Log error messages for debugging and monitoring
- Handle validation errors (4000-4007, 4010-4011, 4020-4025, 4051, 4060, 4065-4068, 4080-4082, 4085, 4090-4093) by correcting the request parameters before retrying
- Monitor account balance to avoid 4003 errors
- Refer to the Supported Features section for channel-specific constraints to prevent 4005 errors
- Verify failover configuration parameters to avoid 4021-4023 errors
支持的功能
The following table list the features supported for each available channel.
| Feature | Content Type | Comments |
|---|---|---|
| Text | TEXT | Max 4,096 characters |
| Attachment (Image, Video, Document) | MEDIA | Max 100MB Image, Max 100MB Video, Max 100MB Document |
| Location | LOCATION | Geographic location sharing |
| QuickReply | QUICK_REPLY | Max 5 choices |
| RichLink | RICH_LINK | Rich cards with image, title, description, and link |
| ListPicker | LIST_PICKER | Multi-item selection lists |
| TimePicker | TIME_PICKER | Date and time selection interface |
| ApplePay | APPLEMB_PAY | Apple Pay integration for payments |
| Authentication | APPLEMB_AUTH | OAuth authentication flows |
| Form | APPLEMB_FORM | Interactive form elements |
| Invitations Message | APPLEMB_UPDATE_MESSAGE | Invitations message to mobile number |
| TypingIndicator | TYPING_START / TYPING_END | Show (TYPING_START) or dismiss (TYPING_END) the typing indicator. No content body is required. |
| Subscribe/Unsubscribe | - | Subscription management |
| iMessageApps | - | iMessage app integrations |
Viber
| Feature | Content Type | Comments |
|---|---|---|
| Text | TEXT | Max 1,000 UTF-8 characters |
| Image | MEDIA | Max 200MB - Expected formats: .jpg, .png |
| Video | MEDIA | Max 200MB |
| Document | MEDIA | Max 200MB (.doc, .docx, .rtf, .dot, .dotx, .odt, .odf, .txt, .info, .pdf, .xps, .pdax, .eps, .xls, .xlsx, .ods, .fods, .csv, .xlsm, .xltx) |
| Action Button | BUTTON | Max 6 buttons - 允许企业在每条消息中只包含一个可点击的按钮，可触发 URL。 详细字段说明请参见 content.button/ViberButton 模型。 |
| List Message (QuickReply) | QUICK_REPLY | 列表消息 让商家可以向用户展示一个问题，并提供 2–10 个可供选择的答案，用户可以从中选择一个选项进行回复。在 24 小时活跃会话窗口内发送的列表消息按 Viber 会话费率计费（类型码 802），会话窗口外则按事务费率计费（类型码 801）。UI 风格可通过 viber.listMessageUiType 控制（1 = 经典单选按钮，默认；2 = 横向按钮，需 Viber 客户端 27.8.2+）。详细字段说明请参见 content.quickReply/ViberListMessage 模型。 |
| Carousel Message | CAROUSEL | Horizontal scrollable cards (multiple cards) - 轮播消息 允许商家发送一条包含文本和多个可自定义版块（items）的消息。 每个版块都可展示不同的产品或服务，并配有专属的媒体内容和行动号召按钮（call-to-action）。 |
| Template | TEMPLATE | Russia/Ukraine templates, Transactional/Promotional templates, Viber templates |
| OTP Verification Message | - | OTP Verification messages 允许品牌通过向客户发送一次性密码（OTP）来验证其身份。请联系支持团队获取支持的语言列表和模板 ID。 |
| Feature | Content Type | Comments |
|---|---|---|
| Text | TEXT | Max 1,024 UTF-8 characters |
| Image | MEDIA | Max 5MB (.jpg, .png) |
| Video | MEDIA | Max 16MB (.3gp, .mp4) |
| Audio | MEDIA | Max 16MB (.aac, .amr, .m4a, .mp3, .ogg) |
| Document | MEDIA | Max 100MB (.txt, .xls, .xlsx, .doc, .docx, .ppt, .pptx, .pdf) |
| Location | LOCATION | Geographic location sharing |
| Interactive Reply buttons | QUICK_REPLY | Quick reply buttons for user responses |
| Interactive CTA URL button | BUTTON | Max 3 buttons with call-to-action URLs |
| Template | TEMPLATE | Pre-approved message templates (Marketing, Utility, Authentication, Service) - Required for initial contact |
| Interactive List | - | Interactive list picker |
| Sticker | - | Sticker support |
| Reaction | - | Message reactions |
| Feature | Content Type | Comments |
|---|---|---|
| Text | TEXT | Max 3,072 characters |
| Media (Images, Videos, Documents, Audio) | MEDIA | Max 100MB (.ogx, .pdf, .aac, .mp3, .mpeg, .mp4, .3gp, .jpg, .gif, .png, .h263, .m4v, .m4p, .webm) |
| Location | LOCATION | Geographic location sharing |
| Suggested replies | QUICK_REPLY | Quick reply suggestions for user responses |
| Suggested actions (Buttons) | BUTTON | Max 4 buttons - Dial Number, Text, Location, Web URL |
| Rich card | CARD | Rich card with single image, title, description, and buttons |
| Rich card carousel | CAROUSEL | Horizontal scrollable cards (multiple cards) |
| Subscribe/Unsubscribe | - | Subscription management |
| Feature | Content Type | Comments |
|---|---|---|
| Text | TEXT | Max 4,096 characters |
| Photo | MEDIA | Max 10MB |
| Video | MEDIA | Max 50MB |
| Audio | MEDIA | Max 50MB (.mp3, .m4a) |
| Document | MEDIA | Max 50MB |
| QuickReply/KeyboardRow | QUICK_REPLY | Quick reply buttons for user responses |
| Buttons | BUTTON | Action buttons with URLs or postback data |
| Feature | Content Type | Comments |
|---|---|---|
| Text | TEXT | Max 5,000 characters |
| Image | MEDIA | Max 10MB (.jpg, .jpeg, .png) |
| Video | MEDIA | Max 200MB (.mp4) |
| Audio | MEDIA | Max 200MB (.m4a) |
| Document | MEDIA | Max 200MB |
| QuickReply | QUICK_REPLY | Max 13 quick reply buttons for user responses |
| Subscribe/Unsubscribe | - | Follow/Unfollow events from the LINE Official Account |
Notes:
- Each channel table above includes a Content Type column showing the API content type value to use in message requests
- Features marked with "-" in the Content Type column are channel-specific capabilities that don't map directly to the content type API parameter
Authentication
- HTTP: Bearer Auth
Bearer HTTP authentication. Headers-- Authorization: Bearer <TOKEN>
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | auth-scheme |