Conversations API
Manage inbox conversations: list and filter them, assign owners and AI assistants, move pipeline stages, send and read messages, upload attachments, maintain predefined replies, and run automations with conversation context.
This section mirrors what you can do from the Conversations area in the app (list, filters, chat header actions, composer, bulk actions, predefined messages, and “run automation” from a thread).
Base paths
| Concern | Service path | Typical methods |
|---|---|---|
| Conversation record | /conversations | GET (find/get), PATCH, DELETE |
| Bulk updates | /conversations-bulk-actions | POST (create body describes the action) |
| Messages (read) | /conversation-messages-{channel} | GET (find/get), DELETE |
| Outgoing send / transform | /conversation-messages-transform-outgoing-{channel} | POST (create) |
| Playground / SMS outbound | /conversation-messages-playground, /conversation-messages-sms | POST (create) |
| File metadata after S3 upload | /conversation-files | POST (create) |
| Signed upload URL | /s3-url-signing | POST (create) |
| Predefined replies | /conversation-predefined-messages | GET (find/get), POST, PATCH, DELETE |
| Run automation with context | /automations-executions | POST (create) |
Replace {channel} with: whatsapp, instagram, messenger, or webchat.
Channel-specific message services
Each conversation has a channel value. Use the matching message service for listing and deleting messages:
channel on conversation | List / get / delete messages |
|---|---|
whatsapp | /conversation-messages-whatsapp |
instagram | /conversation-messages-instagram |
messenger | /conversation-messages-messenger |
webchat | /conversation-messages-webchat |
sms | /conversation-messages-sms |
playground | /conversation-messages-playground |
For sending customer-facing content:
channel | Send / transform outgoing |
|---|---|
whatsapp | POST /conversation-messages-transform-outgoing-whatsapp |
instagram | POST /conversation-messages-transform-outgoing-instagram |
messenger | POST /conversation-messages-transform-outgoing-messenger |
webchat | POST /conversation-messages-transform-outgoing-webchat |
sms | POST /conversation-messages-sms |
playground | POST /conversation-messages-playground |
Pagination
Use Feathers-style query parameters. For any find call, use $limit at most 50 (for example $limit: 50 and $skip for pages).
Related documentation
- List conversations
- Patch conversation (status, assignees, pipeline, AI context, unread, block)
- Bulk conversation actions
- Send outgoing message
- Message composer AI (draft / improve outgoing text)
- WhatsApp templates in conversations
- AI Assistants (configure assistants assigned to threads)
- Pipelines API and Pipeline stages API — conversation boards use
type: 'conversation'; see Patch conversation for updating a thread’spipeline_id/pipeline_stage_id
Report an issue with this documentation
Please log in to report issues with our documentation.