REST API v1 — Documentation

Fliok Developer API

Build custom integrations with Fliok using our REST API. Send messages, manage contacts, trigger broadcasts, and receive real-time webhooks — all programmatically.

Get API Key Talk to Developer Support
99.99%
API Uptime SLA
< 200ms
Median Latency
2,400/min
Message Send Rate
20+
API Endpoints

Quick Start in 3 Steps

01

Get API Key

Create an account and generate your API key from Settings → Developer → API Keys.

02

Make Your First Call

Use our REST API with any language. Full cURL, Python, Node.js, PHP examples included.

03

Set Up Webhooks

Receive real-time events for incoming messages, delivery receipts, and broadcast completions.

Authentication

Fliok API uses Bearer Token authentication. Include your API key in the Authorization header for every request. API keys are scoped to your workspace and can be created/revoked from the dashboard.

Base URL

https://api.fliok.in/api/v1

Current Version

v1 (stable)

# Include in every request header

Authorization: Bearer fl_live_xxxxxxxxxxxxxxxxxxxxxxxx

Never expose your API key in client-side code or public repositories. Use environment variables and rotate keys if compromised.

Send Your First Message

# Send a text message

curl -X POST https://api.fliok.in/api/v1/messages/send \
  -H "Authorization: Bearer fl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "message": "Hello! Your order #12345 has been shipped."
  }'

# Send an image/PDF/video
curl -X POST https://api.fliok.in/api/v1/messages/send-media \
  -H "Authorization: Bearer fl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "type": "document",
    "mediaUrl": "https://example.com/invoice.pdf",
    "caption": "Your invoice for order #12345"
  }'

# Send a template
curl -X POST https://api.fliok.in/api/v1/messages/send-template \
  -H "Authorization: Bearer fl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "templateName": "order_confirmation",
    "language": "en",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Rahul" },
          { "type": "text", "text": "ORD-12345" }
        ]
      }
    ]
  }'

# Send image with template (media header)
curl -X POST https://api.fliok.in/api/v1/messages/send-template \
  -H "Authorization: Bearer fl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "templateName": "order_with_product_image",
    "language": "en",
    "components": [
      {
        "type": "header",
        "parameters": [
          { "type": "image", "image": { "link": "https://example.com/product.jpg" } }
        ]
      },
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Priya" },
          { "type": "text", "text": "ORD-45678" }
        ]
      }
    ]
  }'

# Successful response (200 OK)

{
  "success": true,
  "data": {
    "messageId": "gBEGkYiEB1VXAglK8ZaH2Kq4A",
    "to": "+919876543210",
    "status": "sent"
  }
}

Code Examples

Use any HTTP client in your language. Here are ready-to-use examples for the most popular languages.

Node.js
const API_KEY = 'fl_live_your_api_key';
const BASE = 'https://api.fliok.in/api/v1';

// Send text message
const res = await fetch(BASE + '/messages/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '+919876543210',
    message: 'Hello from Fliok!',
  }),
});
const data = await res.json();
console.log('Message ID:', data.data.messageId);
Python
import requests

API_KEY = "fl_live_your_api_key"
BASE = "https://api.fliok.in/api/v1"

# Send PDF/document
res = requests.post(f"{BASE}/messages/send-media",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "to": "+919876543210",
        "type": "document",
        "mediaUrl": "https://example.com/invoice.pdf",
        "caption": "Your invoice"
    }
)
print("Status:", res.json()["data"]["status"])
PHP
<?php
$apiKey = 'fl_live_your_api_key';
$base = 'https://api.fliok.in/api/v1';

// Send template message
$ch = curl_init("$base/messages/send-template");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $apiKey",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'to' => '+919876543210',
    'templateName' => 'order_confirmation',
    'language' => 'en',
  ]),
]);
$response = json_decode(curl_exec($ch));
echo "Message ID: " . $response->data->messageId;

Works with any language that supports HTTP requests — Ruby, Go, Java, .NET, Dart, and more.

API Endpoints

POST/messages/sendSend a text message to a WhatsApp number Auth
POST/messages/send-mediaSend image, video, PDF, document, or audio file Auth
POST/messages/send-templateSend a pre-approved template message with parameters Auth
POST/messages/send-buttonsSend interactive button message (up to 3 buttons) Auth
POST/messages/send-locationSend a location pin with name and address Auth
GET/contactsList contacts with search, filter, and pagination Auth
POST/contactsCreate a new contact with phone, name, email, tags Auth
GET/contacts/{id}Get contact details by ID Auth
PUT/contacts/{id}Update contact attributes and tags Auth
DELETE/contacts/{id}Delete a contact permanently Auth
GET/templatesList all WhatsApp templates and approval status Auth
GET/templates/{id}Get template details by ID Auth
GET/conversationsList conversations with contact info Auth
GET/conversations/{id}/messagesGet message history for a conversation Auth
GET/broadcastsList all broadcasts with stats Auth
GET/broadcasts/{id}Get broadcast details — delivered, failed, cost Auth
GET/webhooksList your registered webhook endpoints Auth
POST/webhooksRegister a new webhook for real-time events Auth
DELETE/webhooks/{id}Remove a webhook endpoint Auth
GET/accountGet account info, tenant details, and wallet balance Auth

Webhook Events

Subscribe to real-time events by registering a webhook URL. Fliok sends a POST request to your URL whenever an event occurs. All webhook payloads are signed with HMAC-SHA256 using your webhook secret for verification.

message.received

Fired when a contact sends a message to your number

Payload: contact_id, message_id, type, content, timestamp

message.delivered

Fired when a message is successfully delivered to the device

Payload: message_id, contact_id, status, timestamp

message.read

Fired when the recipient reads your message (blue ticks)

Payload: message_id, contact_id, timestamp

message.failed

Fired when a message fails to deliver (with error reason)

Payload: message_id, contact_id, error_code, error_message

broadcast.completed

Fired when all messages in a broadcast have been processed

Payload: broadcast_id, sent, delivered, read, failed, timestamp

contact.opted_out

Fired when a contact replies with STOP or blocks your number

Payload: contact_id, timestamp

payment.completed

Fired when a WhatsApp payment is successfully completed

Payload: payment_id, contact_id, amount, currency, timestamp

template.approved

Fired when Meta approves a submitted message template

Payload: template_id, name, category, language, timestamp

Verifying Webhook Signatures (Node.js)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

// In your Express route:
app.post('/webhooks/fliok', (req, res) => {
  const sig = req.headers['x-fliok-signature'];
  if (!verifyWebhook(req.body, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { event, data } = req.body;
  // Handle event...
  res.json({ received: true });
});

Message Types & Templates

Session Messages (Free-form)

When a customer messages you first, a 24-hour window opens. During this window you can send:

  • Text messages (/messages/send)
  • Images, PDFs, videos, documents (/messages/send-media)
  • Interactive buttons (/messages/send-buttons)
  • Location pins (/messages/send-location)

No template approval needed. Send anything within 24h of customer's last message.

Template Messages (Pre-approved)

To message a customer outside the 24h window (notifications, broadcasts, alerts), you must use Meta-approved templates:

  • Create template in Dashboard → Templates Hub
  • Template is submitted to Meta via Gupshup for approval
  • Once approved, use /messages/send-template
  • Browse ready-made templates in our Template Library

3 categories: Marketing, Utility, Authentication. Each has different pricing and approval rules.

Marketing templates must include opt-out text (e.g., "Reply STOP to unsubscribe"). Templates with spammy language, excessive caps, or URLs in body text will be rejected by Meta.

Rate Limits

Free

100 req/min
API Requests
100 msgs/day
Message Send Rate

Basic

500 req/min
API Requests
2,400 msgs/min
Message Send Rate

Pro / Enterprise

2,000 req/min
API Requests
Custom rate
Message Send Rate

Handling Rate Limit Errors

When you receive a 429 Too Many Requests response, check the Retry-After header for the number of seconds to wait before retrying. We recommend implementing exponential backoff for production systems.

Error Codes

400Bad RequestMissing or invalid parameters in the request body
401UnauthorizedInvalid or missing API key in the Authorization header
403ForbiddenYour plan does not have access to this endpoint
404Not FoundThe requested resource (contact, broadcast, template) does not exist
429Rate LimitedYou have exceeded the rate limit for this endpoint
500Server ErrorAn internal error occurred — retry with exponential backoff

Why Developers Love the Fliok API

RESTful & Predictable

Standard HTTP verbs, JSON request/response bodies, and ISO-8601 timestamps throughout.

Secure by Default

TLS 1.3 required, HMAC webhook signatures, IP allowlisting, and scoped API keys.

High Throughput

Up to 2,400 messages per minute on Pro plans. Ideal for time-sensitive broadcast campaigns.

Real-Time Webhooks

8 event types with signed payloads. Build fully event-driven WhatsApp applications.

SDK First

Official SDKs for Node.js, Python, PHP, Ruby, Go, and Java. Generated from OpenAPI spec.

OpenAPI + Postman

Full OpenAPI 3.0 spec available. Import directly into Postman, Insomnia, or Swagger UI.

Ready to Build?

Create your free account to get an API key. No credit card required. Our developer support team is available 24/7.

Get Free API Key Talk to Developer Support
Chat with us