Version: 1.0
Conversations API
概要
PaaSoo Conversations APIへようこそ。複数のチャネルにわたってシームレスな顧客エンゲージメントを実現するゲートウェイです！
この強力なAPIを使用すると、WhatsApp、Telegram、Apple Messages for Business、Viber Business Messagesなどの人気のあるプラットフォームを通じて顧客とつながることができます。
様々なチャネルでのコミュニケーションを簡素化することで、Conversations APIはお客様に優れた顧客体験を提供する力を与えます。
Postman
要以交互方式探索我们的 API 端点并轻松发起请求，您可以访问我们的 Postman 公共集合。
認証
Conversations APIの機能にアクセスするには、APIトークンを使用してリクエストを認証する必要があります。
始めるには次の手順に従ってください：
- 直感的なclient portalを通じて、ユニークなAPIトークンを生成してください。
- 生成されたトークンを、あなたが行うすべてのAPIリクエストのAuthorizationヘッダーに含めてください。
ヘッダーの構成方法は次のとおりです：
| Header | Description | Example |
|---|---|---|
| Authorization | Your API token | Bearer <API_TOKEN> |
レスポンスとエラー
Paasoo Conversations 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 - 企業はメッセージごとに1つだけのクリック可能なボタンを含めることができ、URLを起動できます。 詳細については content.viber/ViberButton スキーマを参照してください。 |
| List Message (QuickReply) | QUICK_REPLY | リストメッセージ は、 ユーザーに質問と 2〜10 個の回答候補を提示し、その中から 1 つを選択できる機能です。アクティブな 24 時間セッション内で送信されたリストメッセージは Viber セッションレート（タイプコード 802）で課金され、セッション外ではトランザクション（タイプコード 801）として課金されます。UI スタイルは viber.listMessageUiType で制御できます（1 = 従来のラジオボタン、デフォルト。2 = 横並びボタン、Viber クライアント 27.8.2+ 必須）。詳細については content.quickReply/ViberListMessage スキーマを参照してください。 |
| Carousel Message | CAROUSEL | Horizontal scrollable cards (multiple cards) - カルーセルメッセージ タイプでは、テキストと複数のカスタマイズ可能なセクション（アイテム）を含む 1 件のメッセージを送信できます。各セクションには、異なる商品やサービスを表示し、 専用のメディアおよびコールトゥアクション（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 |