Quickstart

This guide assumes you have a FlowIQ account with WhatsApp connected at app.flowiq.live.

1. Get your API key

Open API Keys

Go to Settings → Profile → API Keys. If the section isn’t there, ask FlowIQ support to enable API access for your organization.

Create a key

Create a key and copy it. It starts with fiq_.

Building with Claude Code? Connect the FlowIQ MCP server by signing in and it can make the key for you and save it to your .env. See Build on the API with an assistant.

Store it in an environment variable so it never ends up in your code:

export FLOWIQ_API_KEY="fiq_YOUR_API_KEY"

2. Create a contact

Messages can only be sent to contacts that exist in FlowIQ. Skip this step if the person has already messaged you.

curl -X POST "https://api.flowiq.live/contact" \
  -H "Authorization: Bearer $FLOWIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Jane Smith", "phone_number": "+27834321234" }'

const response = await fetch("https://api.flowiq.live/contact", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FLOWIQ_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Jane Smith", phone_number: "+27834321234" }),
});

console.log(await response.json());

import os, requests

headers = {"Authorization": f"Bearer {os.environ['FLOWIQ_API_KEY']}"}

response = requests.post(
    "https://api.flowiq.live/contact",
    headers=headers,
    json={"name": "Jane Smith", "phone_number": "+27834321234"},
)
print(response.json())

A 409 means the contact already exists, which is fine for this guide.

3. Send a message

curl -X POST "https://api.flowiq.live/send-whatsapp" \
  -H "Authorization: Bearer $FLOWIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+27834321234", "message_type": "text", "text": "Hi Jane, your order is on its way!" }'

const response = await fetch("https://api.flowiq.live/send-whatsapp", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FLOWIQ_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "+27834321234",
    message_type: "text",
    text: "Hi Jane, your order is on its way!",
  }),
});

const result = await response.json();
console.log(result.data.message_id);

response = requests.post(
    "https://api.flowiq.live/send-whatsapp",
    headers=headers,
    json={
        "phone_number": "+27834321234",
        "message_type": "text",
        "text": "Hi Jane, your order is on its way!",
    },
)
print(response.json()["data"]["message_id"])

WhatsApp only allows free-form messages within 24 hours of the contact’s last message to you. If Jane hasn’t written to you recently, send an approved template with Send Template instead.

4. Read the conversation

curl "https://api.flowiq.live/conversations?whatsappNumber=27834321234&limit=10" \
  -H "Authorization: Bearer $FLOWIQ_API_KEY"

const response = await fetch(
  "https://api.flowiq.live/conversations?whatsappNumber=27834321234&limit=10",
  { headers: { Authorization: `Bearer ${process.env.FLOWIQ_API_KEY}` } }
);

const data = await response.json();
console.log(data.messages);
console.log("More pages:", data.pagination.hasNextPage);

response = requests.get(
    "https://api.flowiq.live/conversations",
    headers=headers,
    params={"whatsappNumber": "27834321234", "limit": 10},
)
data = response.json()
print(data["messages"])
print("More pages:", data["pagination"]["hasNextPage"])

Messages come back newest first (pass ascending=true for oldest first), 10 per page by default and up to 100 with limit:

{
  "success": true,
  "messages": [
    {
      "message": "Hi Jane, your order is on its way!",
      "sender_type": "human-whatsapp",
      "created_at": "2026-10-02T10:30:00.000Z",
      "message_status": "delivered",
      "media_type": null,
      "media_url": null,
      "assignee": null,
      "voice_note_transcription": null,
      "reactions": []
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 15,
    "totalMessages": 150,
    "messagesPerPage": 10,
    "hasNextPage": true,
    "hasPrevPage": false
  },
  "count": 10,
  "searchTerms": null,
  "filtered": false,
  "stored": false
}

sender_type tells you who wrote each message: user-whatsapp (the contact), bot-whatsapp (your AI agent or an automation), human-whatsapp (your team, or the API). See Conversations for search, filtering and every field.

5. Look up a contact

curl "https://api.flowiq.live/conversations?action=find-by-phone&whatsappNumber=27834321234" \
  -H "Authorization: Bearer $FLOWIQ_API_KEY"

response = requests.get(
    "https://api.flowiq.live/conversations",
    headers=headers,
    params={"action": "find-by-phone", "whatsappNumber": "27834321234"},
)
print(response.json()["contact"])

To page through every contact, use action=contacts with page and limit (up to 200).

Next steps

Receive messages with webhooks

Get replies and delivery receipts on your server as they happen

Send a template

Start conversations with approved WhatsApp templates

Other message types

Images, documents, buttons, lists and more

Reporting API

Pull account, broadcast and order numbers into your own tools

Troubleshooting

401 Unauthorized

Check the header is exactly Authorization: Bearer fiq_...
Make sure the key hasn’t been revoked or expired in Settings → Profile → API Keys

404 Contact not found when sending

Create the contact first (step 2). Numbers are matched with the country code and without +, spaces or dashes.

No messages returned

Include the country code in whatsappNumber
Check that the contact has messages in your FlowIQ inbox

Get Started

WhatsApp

Calling

Instagram

Messenger

Subscriptions

Webhooks

Reporting & AI

1. Get your API key

2. Create a contact

3. Send a message

4. Read the conversation

5. Look up a contact

Next steps

Receive messages with webhooks

Send a template

Other message types

Reporting API

Troubleshooting

​1. Get your API key

​2. Create a contact

​3. Send a message

​4. Read the conversation

​5. Look up a contact

​Next steps

Receive messages with webhooks

Send a template

Other message types

Reporting API

​Troubleshooting

1. Get your API key

2. Create a contact

3. Send a message

4. Read the conversation

5. Look up a contact

Next steps

Troubleshooting