Conversations

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)	`tenantId`, `whatsappNumber` or `contactId`
`contacts`	List all contacts	`tenantId`
`find-by-phone`	Find a contact by phone number	`tenantId`, `whatsappNumber`

Action: Get Conversation Messages

Fetch messages from a specific conversation. This is the default action.

Basic Usage

curl -X GET "https://api.flowiq.live/conversations?tenantId=YOUR_TENANT_ID&whatsappNumber=27123456789" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

Paginated Results

curl -X GET "https://api.flowiq.live/conversations?tenantId=YOUR_TENANT_ID&whatsappNumber=27123456789&page=2&limit=20" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

Search Messages by Text

curl -X GET "https://api.flowiq.live/conversations?tenantId=YOUR_TENANT_ID&whatsappNumber=27123456789&query=urgent,help" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

Search by Shopify Order ID

curl -X GET "https://api.flowiq.live/conversations?tenantId=YOUR_TENANT_ID&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

curl -X GET "https://api.flowiq.live/conversations?action=contacts&tenantId=YOUR_TENANT_ID" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

Paginated Contacts

curl -X GET "https://api.flowiq.live/conversations?action=contacts&tenantId=YOUR_TENANT_ID&page=2&limit=25" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

Search Contacts by Name/Phone

curl -X GET "https://api.flowiq.live/conversations?action=contacts&tenantId=YOUR_TENANT_ID&search=john" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

Action: Find Contact by Phone

Look up a specific contact using their phone number.

curl -X GET "https://api.flowiq.live/conversations?action=find-by-phone&tenantId=YOUR_TENANT_ID&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

Authorizations

Authorization

string

header

required

Bearer token for authentication. Format: Bearer YOUR_BEARER_TOKEN

Query Parameters

tenantId

string

required

Organization tenant identifier

action

enum<string>

default:conversation-messages

API action to perform

Available options:

conversation-messages,

contacts,

find-by-phone

whatsappNumber

string

WhatsApp phone number (required for message and find-by-phone actions)

contactId

string<uuid>

Contact UUID (alternative to whatsappNumber)

limit

integer

default:10

Number of items per page (messages: default 10, contacts: default 50)

Required range: 1 <= x <= 100

page

integer

default:1

Page number for pagination

Required range: x >= 1

query

string

Search terms (comma-separated for multiple terms)

orderId

string

Shopify order ID to search for (fetches order number from Shopify)

ascending

boolean

default:false

Message order (false = newest first, true = oldest first)

string

Search contacts by name/phone (for contacts action)

Response

Successful response

Option 1
Option 2
Option 3

success

boolean

required

Whether the request was successful

Example:

true

messages

object[]

required

Array of conversation messages

Show child attributes

messages.message

string

required

The message content (may contain JSON for structured messages)

Example:

"Hello! How can I help you today?"

messages.sender_type

enum<string>

required

Type of sender

Available options:

user-whatsapp,

bot-whatsapp,

human-whatsapp,

system

Example:

"user-whatsapp"

messages.created_at

string<date-time>

required

Message timestamp

Example:

"2025-01-10T14:30:00Z"

messages.message_status

enum<string>

required

Message delivery status

Available options:

sent,

delivered,

read,

failed

Example:

"read"

messages.media_type

enum<string> | null

Type of media attachment

Available options:

image,

video,

audio,

document,

interactive,

Example:

"image"

messages.media_url

string | null

URL to media file if applicable

Example:

"https://example.com/image.jpg"

messages.assignee

string | null

Assigned team member UUID

Example:

null

messages.voice_note_transcription

string | null

Transcription of voice messages

Example:

null

messages.reactions

object[]

Message reactions

Example:

[]

count

integer

required

Number of messages returned in this response

Required range: x >= 0

Example:

10

filtered

boolean

required

Whether search filtering was applied

Example:

true

pagination

object

Show child attributes

pagination.currentPage

integer

required

Current page number

Required range: x >= 1

Example:

1

pagination.totalPages

integer

required

Total number of pages

Required range: x >= 0

Example:

5

pagination.hasNextPage

boolean

required

Whether there is a next page

Example:

true

pagination.hasPrevPage

boolean

required

Whether there is a previous page

Example:

false

pagination.totalMessages

integer

Total number of messages (for message endpoints)

Required range: x >= 0

Example:

48

pagination.totalContacts

integer

Total number of contacts (for contacts endpoint)

Required range: x >= 0

Example:

150

pagination.messagesPerPage

integer

Number of messages per page

Required range: x >= 1

Example:

10

pagination.contactsPerPage

integer

Number of contacts per page

Required range: x >= 1

Example:

50

searchTerms

string[] | null

Search terms that were applied (if any)

Example:

["#4275", "urgent"]

stored

boolean

Whether messages were stored in contact record

Example:

false

Getting Started

Endpoints

Default Behavior

Search Capabilities

Available Actions

Action: Get Conversation Messages

Basic Usage

Paginated Results

Search Messages by Text

Search by Shopify Order ID

Action: List Contacts

Get All Contacts

Paginated Contacts

Search Contacts by Name/Phone

Action: Find Contact by Phone

Reference Tables

Message Sender Types

Message Status

Media Types

Bot Status Values

Authorizations

Query Parameters

Response

Getting Started

Endpoints

​Available Actions

​Action: Get Conversation Messages

​Basic Usage

​Paginated Results

​Search Messages by Text

​Search by Shopify Order ID

​Action: List Contacts

​Get All Contacts

​Paginated Contacts

​Search Contacts by Name/Phone

​Action: Find Contact by Phone

​Reference Tables

​Message Sender Types

​Message Status

​Media Types

​Bot Status Values

Authorizations

Query Parameters

Response

Available Actions

Action: Get Conversation Messages

Basic Usage

Paginated Results

Search Messages by Text

Search by Shopify Order ID

Action: List Contacts

Get All Contacts

Paginated Contacts

Search Contacts by Name/Phone

Action: Find Contact by Phone

Reference Tables

Message Sender Types

Message Status

Media Types

Bot Status Values