FlowIQ Quickstart - FlowIQ API Documentation

Get started with FlowIQ API. This guide assumes you already have a FlowIQ account set up at app.flowiq.live.

Prerequisites

You need:

FlowIQ account with connected WhatsApp
Bearer token (API Key)

1. Get Your Credentials

Navigate to your FlowIQ dashboard settings to retrieve:

Go to app.flowiq.live and sign in

Navigate to API Settings

Click on Settings → API Keys or Developer Settings

Generate Bearer Token

Create a new bearer token or copy your existing one

Security Best Practices:

Never expose your bearer token in client-side code
Store credentials in environment variables
Use HTTPS for all API calls

2. Retrieve Conversation Messages

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

const response = await fetch(
  'https://api.flowiq.live/conversations?whatsappNumber=27123456789&limit=10',
  {
    headers: {
      'Authorization': 'Bearer YOUR_BEARER_TOKEN'
    }
  }
);

const data = await response.json();
console.log('Messages:', data.messages);
console.log('Total messages:', data.pagination.totalMessages);
console.log('Has next page:', data.pagination.hasNextPage);

import requests

response = requests.get(
    'https://api.flowiq.live/conversations',
    headers={'Authorization': 'Bearer YOUR_BEARER_TOKEN'},
    params={
        'whatsappNumber': '27123456789',
        'limit': 10
    }
)

data = response.json()
print('Messages:', data['messages'])
print('Total messages:', data['pagination']['totalMessages'])
print('Has next page:', data['pagination']['hasNextPage'])

3. List All Contacts

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

const response = await fetch(
  'https://api.flowiq.live/conversations?action=contacts&limit=20',
  {
    headers: {
      'Authorization': 'Bearer YOUR_BEARER_TOKEN'
    }
  }
);

const data = await response.json();
console.log('Contacts:', data.contacts);
console.log('Total contacts:', data.pagination.totalContacts);

response = requests.get(
    'https://api.flowiq.live/conversations',
    headers={'Authorization': 'Bearer YOUR_BEARER_TOKEN'},
    params={
        'action': 'contacts',
        'limit': 20
    }
)

data = response.json()
print('Contacts:', data['contacts'])
print('Total contacts:', data['pagination']['totalContacts'])

4. Search Specific Contact

curl -X GET "https://api.flowiq.live/conversations?action=find-by-phone&phoneNumber=27123456789" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

const response = await fetch(
  'https://api.flowiq.live/conversations?action=find-by-phone&phoneNumber=27123456789',
  {
    headers: {
      'Authorization': 'Bearer YOUR_BEARER_TOKEN'
    }
  }
);

const data = await response.json();
console.log('Contact:', data.contact);

response = requests.get(
    'https://api.flowiq.live/conversations',
    headers={'Authorization': 'Bearer YOUR_BEARER_TOKEN'},
    params={
        'action': 'find-by-phone',
        'phoneNumber': '27123456789'
    }
)

data = response.json()
print('Contact:', data['contact'])

Understanding the Response

Conversation Messages Response

{
  "success": true,
  "messages": [
    {
      "id": "message_id",
      "content": "Hello, how can I help you?",
      "sender": "user-whatsapp",
      "status": "read",
      "mediaType": null,
      "mediaUrl": null,
      "timestamp": "2024-01-15T10:30:00Z",
      "reactions": [],
      "assignee": null,
      "voiceTranscription": null
    }
  ],
  "pagination": {
    "totalMessages": 150,
    "currentPage": 1,
    "totalPages": 15,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Message Sender Types

Type	Description
`user-whatsapp`	Message from the end user
`bot-whatsapp`	Automated bot response
`human-whatsapp`	Message from a human agent
`system`	System notification or message

Message Status

Status	Description
`sent`	Message sent successfully
`delivered`	Message delivered to recipient
`read`	Message read by recipient
`failed`	Message failed to send

Next Steps

API Reference

Complete endpoint documentation

Conversations Endpoint

Full endpoint documentation with all parameters

Contact Management

Learn about contact management capabilities

Advanced Usage

Complete guide with code examples and best practices

Troubleshooting

Authentication Issues

Verify bearer token is valid and not expired
Check that token is properly formatted in Authorization header
Ensure your API key is valid

Empty Response

Verify the WhatsApp number format (include country code)
Check that conversations exist for the specified number
Ensure your WhatsApp is connected in the dashboard

Pagination Not Working

Use page parameter starting from 1
Combine with limit to control results per page
Check hasNextPage to determine if more pages exist

​Prerequisites

​1. Get Your Credentials

​2. Retrieve Conversation Messages

​3. List All Contacts

​4. Search Specific Contact

​Understanding the Response

​Conversation Messages Response

​Message Sender Types

​Message Status

​Next Steps

API Reference

Conversations Endpoint

Contact Management

Advanced Usage

​Troubleshooting

Prerequisites

1. Get Your Credentials

2. Retrieve Conversation Messages

3. List All Contacts

4. Search Specific Contact

Understanding the Response

Conversation Messages Response

Message Sender Types

Message Status

Next Steps

Troubleshooting