> ## 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.

# FlowIQ Quickstart

> Retrieve your first conversation using FlowIQ API in 5 minutes.

Get started with FlowIQ API. This guide assumes you already have a FlowIQ account set up at [app.flowiq.live](https://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:

<Steps>
  <Step title="Login to Dashboard">
    Go to [app.flowiq.live](https://app.flowiq.live) and sign in
  </Step>

  <Step title="Navigate to API Settings">
    Click on Settings → API Keys or Developer Settings
  </Step>

  <Step title="Generate Bearer Token">
    Create a new bearer token or copy your existing one
  </Step>
</Steps>

<Warning>
  **Security Best Practices:**

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

## 2. Retrieve Conversation Messages

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.flowiq.live/conversations?whatsappNumber=27123456789&limit=10" \
    -H "Authorization: Bearer YOUR_BEARER_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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'])
  ```
</CodeGroup>

## 3. List All Contacts

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.flowiq.live/conversations?action=contacts&limit=20" \
    -H "Authorization: Bearer YOUR_BEARER_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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'])
  ```
</CodeGroup>

## 4. Search Specific Contact

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.flowiq.live/conversations?action=find-by-phone&phoneNumber=27123456789" \
    -H "Authorization: Bearer YOUR_BEARER_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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'])
  ```
</CodeGroup>

## Understanding the Response

### Conversation Messages Response

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/flowiq-api-reference/introduction">
    Complete endpoint documentation
  </Card>

  <Card title="Conversations Endpoint" icon="message" href="/flowiq-api-reference/endpoint/conversations">
    Full endpoint documentation with all parameters
  </Card>

  <Card title="Contact Management" icon="address-book" href="/flowiq-api-reference/endpoint/contact">
    Learn about contact management capabilities
  </Card>

  <Card title="Advanced Usage" icon="rocket" href="/flowiq-getting-started">
    Complete guide with code examples and best practices
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>