> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowapt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Conversations
> Retrieve messages from a conversation with comprehensive filtering and search capabilities.
## Default Behavior
- **Action**: Defaults to `conversation-messages` if not specified
- **Order**: Returns newest messages first (`ascending=false`)
- **Limit**: Returns 10 messages per page by default
- **Page**: Starts at page 1
## Search Capabilities
- **Text Search**: Use `query` parameter with comma-separated terms
- **Order Search**: Use `orderId` to search by Shopify order ID
- **Combined Search**: Use both `query` and `orderId` together
This single endpoint handles multiple operations via the `action` query parameter.
## Available Actions
| Action | Description | Required Parameters |
| ----------------------- | ------------------------------------------ | ------------------------------- |
| `conversation-messages` | Get messages from a conversation (default) | `whatsappNumber` or `contactId` |
| `contacts` | List all contacts | — |
| `find-by-phone` | Find a contact by phone number | `whatsappNumber` |
***
## Action: Get Conversation Messages
Fetch messages from a specific conversation. This is the default action.
### Basic Usage
```bash theme={null}
curl -X GET "https://api.flowiq.live/conversations?whatsappNumber=27123456789" \
-H "Authorization: Bearer YOUR_BEARER_TOKEN"
```
### Paginated Results
```bash theme={null}
curl -X GET "https://api.flowiq.live/conversations?whatsappNumber=27123456789&page=2&limit=20" \
-H "Authorization: Bearer YOUR_BEARER_TOKEN"
```
### Search Messages by Text
```bash theme={null}
curl -X GET "https://api.flowiq.live/conversations?whatsappNumber=27123456789&query=urgent,help" \
-H "Authorization: Bearer YOUR_BEARER_TOKEN"
```
### Search by Shopify Order ID
```bash theme={null}
curl -X GET "https://api.flowiq.live/conversations?whatsappNumber=27123456789&orderId=1234567890" \
-H "Authorization: Bearer YOUR_BEARER_TOKEN"
```
***
## Action: List Contacts
Retrieve a paginated list of all contacts for your organization.
### Get All Contacts
```bash theme={null}
curl -X GET "https://api.flowiq.live/conversations?action=contacts" \
-H "Authorization: Bearer YOUR_BEARER_TOKEN"
```
### Paginated Contacts
```bash theme={null}
curl -X GET "https://api.flowiq.live/conversations?action=contacts&page=2&limit=25" \
-H "Authorization: Bearer YOUR_BEARER_TOKEN"
```
### Search Contacts by Name/Phone
```bash theme={null}
curl -X GET "https://api.flowiq.live/conversations?action=contacts&search=john" \
-H "Authorization: Bearer YOUR_BEARER_TOKEN"
```
***
## Action: Find Contact by Phone
Look up a specific contact using their phone number.
```bash theme={null}
curl -X GET "https://api.flowiq.live/conversations?action=find-by-phone&whatsappNumber=27123456789" \
-H "Authorization: Bearer YOUR_BEARER_TOKEN"
```
Phone numbers are automatically normalized, so `+27 12 345 6789` and `27123456789` will find the same contact.
***
## Reference Tables
### Message Sender Types
| Sender Type | Description |
| ---------------- | ----------------------------------------- |
| `user-whatsapp` | Message sent by the customer via WhatsApp |
| `bot-whatsapp` | Automated bot response |
| `human-whatsapp` | Message sent by a human agent |
| `system` | System-generated message |
### Message Status
| Status | Description |
| ----------- | --------------------------------------- |
| `sent` | Message has been sent |
| `delivered` | Message has been delivered to recipient |
| `read` | Message has been read by recipient |
| `failed` | Message delivery failed |
### Media Types
| Media Type | Description |
| ------------- | ------------------------------------ |
| `image` | Image attachment (JPEG, PNG, etc.) |
| `video` | Video attachment |
| `audio` | Audio message or voice note |
| `document` | Document (PDF, DOCX, etc.) |
| `interactive` | Interactive message (buttons, lists) |
### Bot Status Values
| Status | Description |
| -------- | ------------------------------------------ |
| `active` | Bot is actively responding to this contact |
| `paused` | Bot responses are paused (human takeover) |
| `null` | No bot configured for this contact |
## OpenAPI
````yaml GET /conversations
openapi: 3.1.0
info:
title: FlowIQ Conversations API
version: 1.0.0
description: >-
Complete WhatsApp Conversations API for retrieving messages, contacts, and
conversation history.
## Authentication
All endpoints require a Bearer token in the header:
```
Authorization: Bearer YOUR_BEARER_TOKEN
```
## Example API Call
```bash
curl -X GET
"https://api.flowiq.live/conversations?whatsappNumber=27123456789&limit=10"
\
-H "Authorization: Bearer YOUR_BEARER_TOKEN"
```
**Response:**
```json
{
"success": true,
"messages": [...],
"pagination": {
"currentPage": 1,
"totalPages": 5,
"hasNextPage": true
},
"count": 10
}
```
contact:
name: FlowIQ Support
email: dev@flowapt.com
servers:
- url: https://api.flowiq.live
description: FlowIQ Production API
security:
- BearerAuth: []
tags:
- name: Endpoints
description: Conversation and contact management API endpoints
- name: Webhooks
description: Webhook registration and management
paths:
/conversations:
get:
tags:
- Endpoints
summary: Get Conversation Messages
description: >-
Retrieve messages from a conversation with comprehensive filtering and
search capabilities.
## Default Behavior
- **Action**: Defaults to `conversation-messages` if not specified
- **Order**: Returns newest messages first (`ascending=false`)
- **Limit**: Returns 10 messages per page by default
- **Page**: Starts at page 1
## Search Capabilities
- **Text Search**: Use `query` parameter with comma-separated terms
- **Order Search**: Use `orderId` to search by Shopify order ID
- **Combined Search**: Use both `query` and `orderId` together
operationId: getConversationMessages
parameters:
- name: action
in: query
required: false
schema:
type: string
enum:
- conversation-messages
- contacts
- find-by-phone
default: conversation-messages
description: API action to perform
example: conversation-messages
- name: whatsappNumber
in: query
required: false
schema:
type: string
description: >-
WhatsApp phone number (required for message and find-by-phone
actions)
example: '27123456789'
- name: contactId
in: query
required: false
schema:
type: string
format: uuid
description: Contact UUID (alternative to whatsappNumber)
example: 123e4567-e89b-12d3-a456-426614174000
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 10
description: >-
Number of items per page (messages: default 10, contacts: default
50)
example: 20
- name: page
in: query
required: false
schema:
type: integer
minimum: 1
default: 1
description: Page number for pagination
example: 1
- name: query
in: query
required: false
schema:
type: string
description: Search terms (comma-separated for multiple terms)
example: urgent,help,order
- name: orderId
in: query
required: false
schema:
type: string
description: Shopify order ID to search for (fetches order number from Shopify)
example: '1234567890'
- name: ascending
in: query
required: false
schema:
type: boolean
default: false
description: Message order (false = newest first, true = oldest first)
example: false
- name: search
in: query
required: false
schema:
type: string
description: Search contacts by name/phone (for contacts action)
example: john
responses:
'200':
description: Successful response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ConversationResponse'
- $ref: '#/components/schemas/ContactsResponse'
- $ref: '#/components/schemas/FindContactResponse'
examples:
conversation-messages:
summary: Conversation Messages
value:
success: true
messages:
- message: Hello! How can I help you today?
sender_type: bot-whatsapp
created_at: '2025-01-10T14:30:00Z'
message_status: read
media_type: null
media_url: null
assignee: null
voice_note_transcription: null
reactions: []
pagination:
currentPage: 1
totalPages: 5
totalMessages: 48
messagesPerPage: 10
hasNextPage: true
hasPrevPage: false
count: 1
searchTerms: null
filtered: false
stored: false
'400':
description: Bad Request - Invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized - Invalid or missing authentication
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missing-auth:
summary: Missing Authorization
value:
success: false
error: Authorization required
message: Please provide Authorization bearer token
'404':
description: Not Found - Organization, contact, or order not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
org-not-found:
summary: Organization Not Found
value:
success: false
error: Organization not found
message: Organization not found for API key
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
error: Internal server error
security:
- BearerAuth: []
components:
schemas:
ConversationResponse:
type: object
properties:
success:
type: boolean
description: Whether the request was successful
example: true
messages:
type: array
items:
$ref: '#/components/schemas/ConversationMessage'
description: Array of conversation messages
pagination:
$ref: '#/components/schemas/Pagination'
count:
type: integer
minimum: 0
description: Number of messages returned in this response
example: 10
searchTerms:
type: array
items:
type: string
nullable: true
description: Search terms that were applied (if any)
example:
- '#4275'
- urgent
filtered:
type: boolean
description: Whether search filtering was applied
example: true
stored:
type: boolean
description: Whether messages were stored in contact record
example: false
required:
- success
- messages
- count
- filtered
ContactsResponse:
type: object
properties:
success:
type: boolean
description: Whether the request was successful
example: true
contacts:
type: array
items:
$ref: '#/components/schemas/Contact'
description: Array of contacts
pagination:
$ref: '#/components/schemas/Pagination'
count:
type: integer
minimum: 0
description: Number of contacts returned in this response
example: 50
required:
- success
- contacts
- pagination
- count
FindContactResponse:
type: object
properties:
success:
type: boolean
description: Whether the request was successful
example: true
contact:
$ref: '#/components/schemas/Contact'
original_phone:
type: string
description: Original phone number provided
example: '27123456789'
normalized_phone:
type: string
description: Normalized phone number used for lookup
example: '27123456789'
required:
- success
- contact
- original_phone
- normalized_phone
ErrorResponse:
type: object
properties:
success:
type: boolean
description: Whether the request was successful
example: false
error:
type: string
description: Error message
example: Invalid or missing API key
message:
type: string
description: Detailed error message
example: Invalid or missing API key
details:
type: string
description: Additional error details (optional)
example: Shopify order not found
required:
- success
- error
ConversationMessage:
type: object
properties:
message:
type: string
description: The message content (may contain JSON for structured messages)
example: Hello! How can I help you today?
sender_type:
type: string
enum:
- user-whatsapp
- bot-whatsapp
- human-whatsapp
- system
description: Type of sender
example: user-whatsapp
created_at:
type: string
format: date-time
description: Message timestamp
example: '2025-01-10T14:30:00Z'
message_status:
type: string
enum:
- sent
- delivered
- read
- failed
description: Message delivery status
example: read
media_type:
type: string
nullable: true
enum:
- image
- video
- audio
- document
- interactive
- null
description: Type of media attachment
example: image
media_url:
type: string
nullable: true
description: URL to media file if applicable
example: https://example.com/image.jpg
assignee:
type: string
nullable: true
description: Assigned team member UUID
example: null
voice_note_transcription:
type: string
nullable: true
description: Transcription of voice messages
example: null
reactions:
type: array
items:
type: object
description: Message reactions
example: []
required:
- message
- sender_type
- created_at
- message_status
Pagination:
type: object
properties:
currentPage:
type: integer
minimum: 1
description: Current page number
example: 1
totalPages:
type: integer
minimum: 0
description: Total number of pages
example: 5
totalMessages:
type: integer
minimum: 0
description: Total number of messages (for message endpoints)
example: 48
totalContacts:
type: integer
minimum: 0
description: Total number of contacts (for contacts endpoint)
example: 150
messagesPerPage:
type: integer
minimum: 1
description: Number of messages per page
example: 10
contactsPerPage:
type: integer
minimum: 1
description: Number of contacts per page
example: 50
hasNextPage:
type: boolean
description: Whether there is a next page
example: true
hasPrevPage:
type: boolean
description: Whether there is a previous page
example: false
required:
- currentPage
- totalPages
- hasNextPage
- hasPrevPage
Contact:
type: object
properties:
id:
type: string
format: uuid
description: Contact unique identifier
example: 123e4567-e89b-12d3-a456-426614174000
full_name:
type: string
nullable: true
description: Contact full name
example: John Doe
whatsapp_id:
type: string
description: WhatsApp number (normalized)
example: '27123456789'
phone_number:
type: string
nullable: true
description: Original phone number format
example: +27 12 345 6789
email:
type: string
nullable: true
format: email
description: Contact email address
example: john@example.com
created_at:
type: string
format: date-time
description: Contact creation timestamp
example: '2025-01-10T14:30:00Z'
tags:
type: array
items:
type: string
nullable: true
description: Contact tags
example:
- customer
- premium
has_unread_messages:
type: boolean
description: Whether contact has unread messages
example: false
bot_status:
type: string
nullable: true
enum:
- active
- paused
- null
description: Bot interaction status
example: active
archived:
type: boolean
nullable: true
description: Whether contact is archived
example: false
required:
- id
- whatsapp_id
- created_at
- has_unread_messages
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 'Bearer token for authentication. Format: `Bearer YOUR_BEARER_TOKEN`'
bearerFormat: JWT
````