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) |
| 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 |
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) 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 |
| Update Message | APPLEMB_UPDATE_MESSAGE | Business Updates 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 驗證訊息 允許品牌透過向客戶傳送一次性密碼（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 |