Skip to main content
Get up and running with FlowIQ Conversations API. This guide will help you make your first API call and retrieve conversation data from WhatsApp.

​
Prerequisites

Before you begin, ensure you have:
  • FlowIQ account at app.flowiq.live
  • Bearer token (API Key)
  • Your Tenant ID
  • Active WhatsApp number connected to FlowIQ
If you don’t have a FlowIQ account yet, sign up at app.flowiq.live and connect your WhatsApp number first.

​
Getting Your Credentials

​
1. Obtain Your Bearer Token

1

Login to Dashboard

Navigate to app.flowiq.live and log in
2

Access API Settings

Go to Settings → API Keys or Developer Settings
3

Generate Token

Generate a new bearer token or copy your existing one
4

Secure Your Token

Store it securely - never expose it in client-side code

​
2. Find Your Tenant ID

Your Tenant ID is available in your FlowIQ dashboard under Settings or Account Information.

​
Your First API Call

​
Retrieve Conversation Messages

Let’s fetch the last 10 messages from a WhatsApp conversation: 
curl -X GET "https://api.flowiq.live/conversations?tenantId=YOUR_TENANT_ID&whatsappNumber=27123456789&limit=10" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

​
Expected Response

{
  "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": []
    },
    {
      "message": "I need help with my order",
      "sender_type": "user-whatsapp",
      "created_at": "2025-01-10T14:29:45Z",
      "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": 10,
  "filtered": false
}

​
Common Operations

​
1. List All Contacts

Retrieve all contacts with pagination: 
curl -X GET "https://api.flowiq.live/conversations?action=contacts&tenantId=YOUR_TENANT_ID&limit=20&page=1" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

​
2. Search Contacts

Search for specific contacts by name or phone: 
curl -X GET "https://api.flowiq.live/conversations?action=contacts&tenantId=YOUR_TENANT_ID&search=John" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

​
3. Find Contact by Phone Number

Lookup a specific contact using their phone number: 
curl -X GET "https://api.flowiq.live/conversations?action=find-by-phone&tenantId=YOUR_TENANT_ID&phoneNumber=27123456789" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

​
Working with Pagination

FlowIQ API returns paginated results for large datasets: 
// Example: Fetch all messages across multiple pages
async function fetchAllMessages(tenantId, whatsappNumber, bearerToken) {
  let allMessages = [];
  let currentPage = 1;
  let hasNextPage = true;

  while (hasNextPage) {
    const response = await fetch(
      `https://api.flowiq.live/conversations?tenantId=${tenantId}&whatsappNumber=${whatsappNumber}&page=${currentPage}&limit=50`,
      {
        headers: {
          Authorization: `Bearer ${bearerToken}`,
        },
      }
    );

    const data = await response.json();
    allMessages = allMessages.concat(data.messages);

    hasNextPage = data.pagination.hasNextPage;
    currentPage++;
  }

  return allMessages;
}

​
Understanding Message Types

FlowIQ API returns different types of messages and senders:

​
Sender Types

TypeDescription
user-whatsappMessage from the end user
bot-whatsappAutomated bot response
human-whatsappMessage from a human agent
systemSystem notification

​
Media Types

TypeDescription
imageImage file
videoVideo file
audioAudio file or voice note
documentDocument file (PDF, DOCX, etc.)
interactiveInteractive message (buttons, lists)
nullText-only message

​
Message Status

StatusDescription
sentMessage sent successfully
deliveredMessage delivered to recipient
readMessage read by recipient
failedMessage failed to send

​
Error Handling

Implement proper error handling in your applications: 
async function safeApiCall() {
  try {
    const response = await fetch(
      "https://api.flowiq.live/conversations?tenantId=YOUR_TENANT_ID&whatsappNumber=27123456789",
      {
        headers: {
          Authorization: "Bearer YOUR_BEARER_TOKEN",
        },
      }
    );

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();

    if (!data.success) {
      console.error("API returned error:", data.error, data.message);
      return null;
    }

    return data;
  } catch (error) {
    console.error("Request failed:", error);
    return null;
  }
}

​
Best Practices

  • Implement exponential backoff for retries
  • Cache responses when appropriate
  • Use pagination effectively to avoid large requests
  • Monitor 429 status codes
  • Never expose your bearer token in client-side code - Use environment variables for credentials - Implement token rotation regularly - Use HTTPS for all API calls
  • Request only the data you need using limit parameter - Use appropriate page sizes (recommended: 20-50 items) - Implement caching for frequently accessed data - Use search filters to reduce response size
  • Always check the success field in responses
  • Implement retry logic with exponential backoff
  • Log errors for debugging
  • Handle network timeouts gracefully

​
Next Steps

Conversations API

Complete endpoint documentation with all parameters

Contact API

Learn about contact management features

API Reference

Full API reference and authentication details

Dashboard

Access your FlowIQ dashboard

​
Troubleshooting

Cause: Invalid or missing bearer tokenSolution:
  • Verify your bearer token is correct
  • Check the Authorization header format: Bearer YOUR_TOKEN
  • Ensure the token hasn’t expired
  • Generate a new token from the dashboard if needed
Cause: Invalid endpoint or missing required parameters Solution: - Verify the API endpoint URL is correct - Ensure all required query parameters are included - Check that the WhatsApp number format is correct (international format without +)
Cause: No messages found for the specified conversation Solution: - Verify the WhatsApp number is correct - Check that the number has active conversations - Ensure the tenant ID matches your account - Try adjusting pagination parameters
Cause: Too many requests in a short time periodSolution:
  • Implement exponential backoff in your code
  • Reduce request frequency
  • Use pagination instead of requesting all data at once
  • Contact support if you need higher rate limits

​
Need Help?

Support

Email our development team

Flowapt Website

Learn more about our products