API Reference

The MessengerFlow API gives you programmatic access to your accounts, campaigns, leads, conversations, and more. Every action available in the dashboard can be performed through the API.

Authentication

All requests require authentication via one of two methods:

API Key (Recommended)

Include your key in the X-API-Key header:

curl https://app.messengerflow.com/api/v1/accounts \
  -H "X-API-Key: mf_a1b2c3d4e5f67890abcdef1234567890"

Create and manage keys in Settings > Developers > API Keys. Keys are shown only once at creation and cannot be retrieved later.

Bearer Token

Pass a Keycloak JWT in the Authorization header:

curl https://app.messengerflow.com/api/v1/accounts \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Base URL

https://app.messengerflow.com/api/v1

All endpoint paths in this document are relative to this base URL.

Rate Limits

API key requests are limited to 100 requests per minute per user. Bearer token requests are not rate limited.

Every API key response includes these headers:

Exceeding the limit returns 429 Too Many Requests.

Response Format

All responses are JSON with a consistent structure.

Success:

{
  "success": true,
  "data": { }
}

Error:

{
  "success": false,
  "error": "Description of what went wrong"
}

Validation error:

{
  "success": false,
  "error": "Invalid request",
  "data": {
    "fieldErrors": {
      "email": ["Required"]
    }
  }
}

Status Codes

Accounts

Manage the Facebook accounts connected to your workspace.

List accounts

GET /accounts

Returns all accounts for the authenticated user, sorted by availability (healthy accounts first).

curl https://app.messengerflow.com/api/v1/accounts \
  -H "X-API-Key: mf_your_key"

Response:

{
  "success": true,
  "data": [
    {
      "id": "9a9de1db-cf33-4056-8188-8e570cab466c",
      "email": "[email protected]",
      "display_name": "My Account",
      "enabled": true,
      "banned": false,
      "error": false,
      "invalid_credentials": false,
      "invalid_2fa": false,
      "unsupported_auth_flow": false,
      "requires_pin": false,
      "rate_limited_until": "2026-01-15T08:00:00Z",
      "last_sent_at": "2026-02-10T11:23:00Z",
      "proxy": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
      "proxyData": {
        "id": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
        "ip": "192.168.1.100",
        "port": 3128,
        "error": false
      },
      "profile": {
        "picture": "s3://profiles/uuid/picture.jpg",
        "banner": "s3://profiles/uuid/banner.jpg",
        "bio": "Digital marketing consultant",
        "fb_name": "John Smith"
      },
      "profile_applied": {
        "picture": "s3://profiles/uuid/picture.jpg",
        "bio": "Digital marketing consultant"
      },
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

Get account

GET /accounts/:id

Returns a single account by ID.

curl https://app.messengerflow.com/api/v1/accounts/9a9de1db-cf33-4056-8188-8e570cab466c \
  -H "X-API-Key: mf_your_key"

Response:

{
  "success": true,
  "data": {
    "id": "9a9de1db-cf33-4056-8188-8e570cab466c",
    "email": "[email protected]",
    "display_name": "My Account",
    "enabled": true,
    "banned": false,
    "error": false,
    "invalid_credentials": false,
    "invalid_2fa": false,
    "unsupported_auth_flow": false,
    "requires_pin": false,
    "rate_limited_until": null,
    "last_sent_at": "2026-02-10T11:23:00Z",
    "proxy": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
    "proxyData": {
      "id": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
      "ip": "192.168.1.100",
      "port": 3128,
      "error": false
    },
    "profile": null,
    "profile_applied": null,
    "created_at": "2026-01-01T00:00:00Z"
  }
}

Returns 404 if the account does not exist or belongs to another user.

Add account

POST /accounts

Adds a new Facebook account. Requires an active subscription.

curl -X POST https://app.messengerflow.com/api/v1/accounts \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "fb_password",
    "secret": "JBSWY3DPEHPK3PXP",
    "proxy": "d4e5f6a7-b8c9-0123-4567-89abcdef0123"
  }'

Cookie object shape:

Update account

PATCH /accounts

Updates one or more fields on an existing account. Only include the fields you want to change.

curl -X PATCH https://app.messengerflow.com/api/v1/accounts \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "9a9de1db-cf33-4056-8188-8e570cab466c",
    "enabled": false
  }'

Changing status flags (banned, invalid_credentials, etc.) triggers an account.status_changed webhook event.

Delete account

DELETE /accounts

Permanently removes an account. Fails if the account is assigned to any active campaigns.

curl -X DELETE https://app.messengerflow.com/api/v1/accounts \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "id": "9a9de1db-cf33-4056-8188-8e570cab466c" }'

Get account stats

GET /accounts/:id/stats

Returns messaging statistics for a single account.

curl https://app.messengerflow.com/api/v1/accounts/9a9de1db-.../stats \
  -H "X-API-Key: mf_your_key"

Response:

{
  "success": true,
  "data": {
    "messagesSent": 1247,
    "totalMessages": 1310,
    "successRate": 95,
    "recentSent": 182,
    "recentTotal": 190
  }
}

Get account error log

GET /accounts/:id/logs

Returns the most recent error log entries for an account (up to 50).

Response:

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "title": "Invalid Credentials",
      "description": "The provided email or password was rejected by Facebook.",
      "warning": true,
      "screenshot": "https://cdn.fuyu.gg/messengerflow/screenshots/...",
      "created_at": "2026-02-09T14:30:00Z"
    }
  ]
}

Get account profile

GET /accounts/:id/profile

Returns the desired profile configuration, what has been applied, and any pending task.

Response:

{
  "success": true,
  "data": {
    "profile": {
      "picture": "s3://profiles/uuid/picture.jpg",
      "bio": "Digital marketing consultant",
      "fb_name": "John Smith"
    },
    "applied": {
      "picture": "s3://profiles/uuid/picture.jpg"
    },
    "pending_task": {
      "id": "uuid",
      "status": "pending",
      "created_at": "2026-02-10T11:00:00Z"
    }
  }
}

Update account profile

PATCH /accounts/:id/profile

Sets or updates profile fields. Fields are merged with existing profile data. If the new profile differs from what's applied, a setup task is automatically queued with a 5-minute debounce window.

curl -X PATCH https://app.messengerflow.com/api/v1/accounts/uuid/profile \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "bio": "Digital marketing consultant",
    "fb_name": "John Smith"
  }'

All fields are optional. Only include the ones you want to change.

Upload profile image

POST /accounts/:id/profile/upload?type=picture
POST /accounts/:id/profile/upload?type=banner

Uploads a profile picture or banner image. Images are compressed to JPEG and stored in S3. Use the returned URL in the profile update endpoint.

Send the image as multipart form data with a file field.

curl -X POST "https://app.messengerflow.com/api/v1/accounts/uuid/profile/upload?type=picture" \
  -H "X-API-Key: mf_your_key" \
  -F "[email protected]"

Response:

{
  "success": true,
  "data": { "url": "s3://profiles/uuid/picture.jpg" }
}

Clear account profile

DELETE /accounts/:id/profile

Removes all profile configuration and cancels any pending setup tasks. Does not revert changes already applied to Facebook.

Campaigns

Create and manage outreach campaigns.

List campaigns

GET /campaigns

Returns all campaigns (excluding deleted) with progress metrics.

curl https://app.messengerflow.com/api/v1/campaigns \
  -H "X-API-Key: mf_your_key"

Response:

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Q1 Outreach",
      "paused": false,
      "finished": false,
      "deleted": false,
      "inactive": false,
      "collection": "uuid",
      "range_min": 20,
      "range_max": 30,
      "timezone": "America/New_York",
      "active_days": [1, 2, 3, 4, 5],
      "active_hours": [
        { "start": "09:00", "end": "17:00" }
      ],
      "messages": ["Hey {{first}}, ..."],
      "accounts": ["account-uuid-1", "account-uuid-2"],
      "progress": {
        "sent": 450,
        "failed": 12,
        "partial": 8,
        "pending": 530,
        "total": 1000
      },
      "created_at": "2026-01-15T00:00:00Z"
    }
  ]
}

Get campaign

GET /campaigns/:id

Returns a single campaign by ID with progress metrics, account limits, and assigned accounts.

curl https://app.messengerflow.com/api/v1/campaigns/campaign-uuid \
  -H "X-API-Key: mf_your_key"

Response:

{
  "id": "uuid",
  "name": "Q1 Outreach",
  "paused": false,
  "finished": false,
  "deleted": false,
  "inactive": false,
  "collection": "uuid",
  "range_min": 20,
  "range_max": 30,
  "timezone": "America/New_York",
  "active_days": [1, 2, 3, 4, 5],
  "active_hours": [
    { "start": "09:00", "end": "17:00" }
  ],
  "messages": ["Hey {{first}}, ..."],
  "accounts": ["account-uuid-1", "account-uuid-2"],
  "progress": {
    "sent": 450,
    "failed": 12,
    "partial": 8,
    "pending": 530,
    "total": 1000
  },
  "limits": {
    "account-uuid-1": { "daily_limit": 25, "send_interval": 120 }
  },
  "created_at": "2026-01-15T00:00:00Z"
}

Returns 404 if the campaign does not exist, belongs to another user, or has been deleted.

Create campaign

POST /campaigns

Creates a new campaign. Requires an active subscription and available capacity (checked against your plan's campaign and account-per-campaign limits).

curl -X POST https://app.messengerflow.com/api/v1/campaigns \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Outreach",
    "collection": "collection-uuid",
    "accounts": ["account-uuid-1", "account-uuid-2"],
    "messages": ["Hey {{first}}, quick question about your business..."],
    "range_min": 20,
    "range_max": 30,
    "timezone": "America/New_York",
    "active_days": [1, 2, 3, 4, 5],
    "active_hours": [{ "start": "09:00", "end": "17:00" }]
  }'

Follow-up object:

Response:

{
  "success": true,
  "data": { "id": "new-campaign-uuid" }
}

Update campaign

PATCH /campaigns

Updates campaign settings. All fields are optional except id. Changing messages or follow-ups automatically syncs pending lead queues.

curl -X PATCH https://app.messengerflow.com/api/v1/campaigns \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "campaign-uuid",
    "paused": true
  }'

Accepts the same fields as campaign creation, plus id (required).

Delete campaign

POST /campaigns/destroy

Soft-deletes a campaign. The campaign is paused and marked as deleted. Lead data is preserved.

curl -X POST https://app.messengerflow.com/api/v1/campaigns/destroy \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "id": "campaign-uuid" }'

Add account to campaign

POST /campaigns/accounts

Assigns an additional account to a running campaign. Unsent leads are automatically redistributed across all accounts.

curl -X POST https://app.messengerflow.com/api/v1/campaigns/accounts \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign-uuid",
    "account_id": "account-uuid"
  }'

Remove account from campaign

DELETE /campaigns/accounts

Removes an account from a campaign. Unsent leads from the removed account are reassigned to remaining accounts. At least one account must remain.

curl -X DELETE https://app.messengerflow.com/api/v1/campaigns/accounts \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign-uuid",
    "account_id": "account-uuid"
  }'

Get campaign leads

GET /campaigns/:id/leads

Returns a paginated list of leads assigned to the campaign.

Response:

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "uuid",
        "status": "sent",
        "priority": 0,
        "attempts": 1,
        "error_code": null,
        "sent_at": "2026-02-10T11:00:00Z",
        "created_at": "2026-01-15T00:00:00Z",
        "lead_name": "John Smith",
        "fb_id": "123456789",
        "account_email": "[email protected]",
        "account_id": "uuid",
        "messages": [
          {
            "id": "uuid",
            "message_index": 0,
            "status": "sent",
            "sent_at": "2026-02-10T11:00:00Z",
            "error_code": null,
            "body": "Hey John, ..."
          }
        ]
      }
    ],
    "pagination": {
      "total": 1000,
      "limit": 50,
      "offset": 0,
      "hasMore": true
    }
  }
}

Get campaign activity

GET /campaigns/:id/activity

Returns recent message activity for a campaign (last 48 hours).

Response:

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "uuid",
        "status": "sent",
        "sent_at": "2026-02-10T11:00:00Z",
        "updated_at": "2026-02-10T11:00:00Z",
        "error_code": null,
        "message_index": 0,
        "body_preview": "Hey John, ...",
        "lead_name": "John Smith",
        "fb_id": "123456789",
        "account_email": "[email protected]"
      }
    ],
    "timestamp": "2026-02-10T11:05:00Z"
  }
}

Use the timestamp value as the since parameter on subsequent requests to receive only new events.

Leads

Manage lead collections and imports.

List collections

GET /leads

Returns all lead collections with their lead counts.

curl https://app.messengerflow.com/api/v1/leads \
  -H "X-API-Key: mf_your_key"

Response:

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Tech Founders NYC",
      "is_import": false,
      "is_group": true,
      "progress": 100,
      "lead_count": 4520,
      "created_at": "2026-01-10T00:00:00Z"
    }
  ]
}

Import leads

POST /leads/import

Creates a new collection from a list of Facebook user IDs. Maximum 100,000 leads per import. Duplicates within the batch are automatically removed.

curl -X POST https://app.messengerflow.com/api/v1/leads/import \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Conference Attendees",
    "data": [
      { "id": "100001234567890", "name": "John Smith" },
      { "id": "100009876543210", "name": "Jane Doe" }
    ]
  }'

Import counts against your plan's import limit.

Create collection from Facebook group

POST /leads/groups

Queues a scraping job to extract members from a Facebook group. Requires Momentum plan or above.

curl -X POST https://app.messengerflow.com/api/v1/leads/groups \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "React Developers",
    "group_id": "123456789",
    "account_id": "account-uuid",
    "max": 5000
  }'

The collection is created immediately with progress: 0. Scraping runs in the background; poll the collection to check progress.

Create collection from Facebook pages

POST /leads/pages

Queues a scraping job to find Facebook pages matching your criteria.

curl -X POST https://app.messengerflow.com/api/v1/leads/pages \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "NYC Restaurants",
    "query": "restaurant",
    "locations": ["New York, NY"],
    "keywords": ["fine dining"],
    "excludedKeywords": ["fast food"]
  }'

Merge collections

POST /leads/merge

Combines 2-10 completed collections into a new one. Collections must be the same type (all groups or all pages). Duplicates are removed automatically.

curl -X POST https://app.messengerflow.com/api/v1/leads/merge \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Combined NYC Leads",
    "collection_ids": ["uuid-1", "uuid-2", "uuid-3"]
  }'

Get collection leads

GET /leads/:id/leads

Returns up to 500 leads from a collection.

Response:

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "fb_id": "100001234567890",
      "name": "John Smith",
      "avatar": "https://...",
      "is_page": false,
      "created_at": "2026-01-10T00:00:00Z"
    }
  ]
}

Export collection as CSV

GET /leads/:id/export

Streams the entire collection as a CSV file. The response is streamed in batches so it works for large collections without loading everything into memory.

curl https://app.messengerflow.com/api/v1/leads/uuid/export \
  -H "X-API-Key: mf_your_key" \
  -o leads.csv

Response: CSV file with id and name columns.

id,name
100001234567890,John Smith
100009876543210,Jane Doe

Update collection

PATCH /leads/:id

Renames a collection.

curl -X PATCH https://app.messengerflow.com/api/v1/leads/uuid/... \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "New Name" }'

Delete collection

DELETE /leads/:id

Permanently deletes a collection and its leads.

Rescrape collection

POST /leads/:id/rescrape

Queues a completed collection for re-scraping. Not available for imports.

Retry failed collection

POST /leads/:id/retry

Retries a collection that failed during scraping.

Conversations

Access the unified inbox for managing conversations across all accounts.

List conversations

GET /inbox/conversations

Returns conversations sorted by most recent message.

Response:

{
  "success": true,
  "data": [
    {
      "id": 12345,
      "recipient": "John Smith",
      "recipient_id": "100001234567890",
      "account": "account-uuid",
      "read": true,
      "responded": false,
      "booked_at": null,
      "pinned": false,
      "tags": ["interested"],
      "waiting": false,
      "preview": "Hey John, quick question...",
      "last_message_date": "2026-02-10T11:00:00Z",
      "updated_at": "2026-02-10T11:00:00Z"
    }
  ]
}

Search conversations

GET /inbox/conversations/search?q=term

Searches conversations by recipient name or tags.

Get conversation messages

GET /inbox/conversations/:id/messages

Returns messages within a conversation, newest first.

Response:

{
  "success": true,
  "data": {
    "id": 12345,
    "messages": [
      {
        "id": "msg-uuid",
        "body": "Hey John, quick question about your business...",
        "date": "2026-02-10T11:00:00Z",
        "self": true,
        "status": "delivered",
        "failed": false,
        "pending": false,
        "replying_to": null
      }
    ],
    "pending_messages": []
  }
}

Send message

POST /inbox/conversations/send

Queues a message for delivery in an existing conversation.

curl -X POST https://app.messengerflow.com/api/v1/inbox/conversations/send \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": 12345,
    "body": "Thanks for getting back to me!"
  }'

Messages are queued and delivered asynchronously. The response confirms queuing, not delivery.

Voice messages and image attachments are only available through the web interface. The API supports text messages only.

Update conversation

PATCH /inbox/conversations/:id

Updates conversation metadata such as read status, tags, or booking state.

curl -X PATCH https://app.messengerflow.com/api/v1/inbox/conversations/12345 \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "booked_at",
    "value": "2026-02-15T10:00:00Z"
  }'

Get unread count

GET /inbox/conversations/unread-count

Returns the number of unread conversations.

Response:

{ "success": true, "data": { "count": 7 } }

Delete conversations

DELETE /inbox/conversations

Removes conversations from the inbox.

curl -X DELETE https://app.messengerflow.com/api/v1/inbox/conversations \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "conversations": ["12345", "12346"] }'

Retry failed message

POST /inbox/conversations/message-retry

Re-queues a failed message for delivery.

curl -X POST https://app.messengerflow.com/api/v1/inbox/conversations/message-retry \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "message_id": "msg-uuid" }'

Delete pending message

DELETE /inbox/conversations/message

Cancels a pending or failed message before it's delivered.

Dashboard

Retrieve analytics and performance data.

Get stats

GET /dashboard/stats

Returns messaging statistics across multiple time periods.

Response:

{
  "success": true,
  "data": {
    "today": { "sent": 45, "seen": 38, "replied": 12, "booked": 3, "failed": 2 },
    "yesterday": { "sent": 52, "seen": 44, "replied": 15, "booked": 4 },
    "week": { "sent": 312, "seen": 267, "replied": 89, "booked": 22 },
    "month": { "sent": 1247, "seen": 1089, "replied": 356, "booked": 88 },
    "conversations": { "total": 892, "unread": 7, "waiting": 14, "booked": 88 }
  }
}

Get performance

GET /dashboard/performance

Returns top-performing accounts and campaigns over the last 30 days.

Response:

{
  "success": true,
  "data": {
    "topAccounts": [
      {
        "id": "uuid",
        "name": "[email protected]",
        "sent": 312,
        "replied": 89,
        "replyRate": 28.5
      }
    ],
    "topCampaigns": [
      {
        "id": "uuid",
        "name": "Q1 Outreach",
        "totalLeads": 1000,
        "sent": 450,
        "replied": 128,
        "booked": 32,
        "replyRate": 28.4,
        "bookRate": 7.1
      }
    ],
    "recentActivity": [
      {
        "type": "message_sent",
        "timestamp": "2026-02-10T11:00:00Z",
        "campaignName": "Q1 Outreach",
        "leadName": "John Smith",
        "description": "Message delivered"
      }
    ]
  }
}

Get activity chart

GET /dashboard/activity?period=week

Returns time-series data for charting.

Response:

{
  "success": true,
  "data": [
    {
      "label": "Mon",
      "date": "2026-02-10",
      "sent": 45,
      "seen": 38,
      "replied": 12,
      "booked": 3
    }
  ]
}

Proxies

Manage proxy connections used by your accounts.

List proxies

GET /proxies

Returns all proxies, sorted by creation date.

Response:

{
  "success": true,
  "data": [
    {
      "id": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
      "name": "US East",
      "ip": "192.168.1.100",
      "port": 3128,
      "username": "proxy_user",
      "error": false,
      "last_error": null,
      "last_checked": "2026-02-10T11:00:00Z",
      "last_recorded_speed": 245,
      "timezone": "America/New_York",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

Add proxy

POST /proxies

curl -X POST https://app.messengerflow.com/api/v1/proxies \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "192.168.1.100",
    "port": 3128,
    "username": "proxy_user",
    "password": "proxy_pass"
  }'

Update proxy

PATCH /proxies/:id

Delete proxy

DELETE /proxies/:id

Bulk add proxies

POST /proxies/bulk

Adds multiple proxies in a single request.

curl -X POST https://app.messengerflow.com/api/v1/proxies/bulk \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "proxies": [
      { "ip": "192.168.1.100", "port": 3128, "username": "user1", "password": "pass1" },
      { "ip": "192.168.1.101", "port": 3128, "username": "user2", "password": "pass2" }
    ]
  }'

Verify proxy

POST /proxies/verify

Tests whether a proxy can connect to Facebook. Returns the connection delay in milliseconds.

Response:

{ "error": false, "delay": 245 }

API Keys

Manage programmatic access credentials.

List keys

GET /api-keys

Returns all active (non-revoked) API keys. The full key value is never returned after creation.

Response:

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Production",
      "key_prefix": "mf_a1b2...",
      "scopes": ["all"],
      "last_used_at": "2026-02-10T11:00:00Z",
      "created_at": "2026-01-15T00:00:00Z"
    }
  ]
}

Create key

POST /api-keys

Creates a new API key. The full key is returned only once in the response. Maximum 5 active keys per user.

curl -X POST https://app.messengerflow.com/api/v1/api-keys \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production" }'

Response:

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Production",
    "key_prefix": "mf_a1b2...",
    "key": "mf_a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef12345678",
    "created_at": "2026-02-10T00:00:00Z"
  }
}

Store the key value securely. It cannot be retrieved again.

Revoke key

DELETE /api-keys/:id

Permanently revokes an API key. Any requests using this key will immediately return 401.

Webhook Endpoints

Register and manage webhook endpoints for real-time event notifications. For a complete guide on webhook events, payloads, and signature verification, see the Webhooks documentation.

List endpoints

GET /webhooks/endpoints

Response:

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "url": "https://your-app.com/webhooks",
      "events": ["message.sent", "conversation.reply"],
      "enabled": true,
      "failure_count": 0,
      "disabled_at": null,
      "created_at": "2026-02-01T00:00:00Z",
      "updated_at": "2026-02-01T00:00:00Z"
    }
  ]
}

Create endpoint

POST /webhooks/endpoints

Registers a new webhook endpoint. The signing secret is returned only once in the response.

curl -X POST https://app.messengerflow.com/api/v1/webhooks/endpoints \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks",
    "events": ["message.sent", "message.failed", "conversation.reply"]
  }'

Available events: message.sent, message.failed, conversation.created, conversation.reply, conversation.booked, campaign.completed, account.status_changed

Response includes secret — save it for signature verification.

Get endpoint details

GET /webhooks/endpoints/:id

Returns endpoint configuration and its last 50 delivery attempts.

Response:

{
  "success": true,
  "data": {
    "id": "uuid",
    "url": "https://your-app.com/webhooks",
    "events": ["message.sent"],
    "enabled": true,
    "failure_count": 0,
    "created_at": "2026-02-01T00:00:00Z",
    "deliveries": [
      {
        "id": "uuid",
        "event": "message.sent",
        "status": "delivered",
        "response_code": 200,
        "attempts": 1,
        "created_at": "2026-02-10T11:00:00Z"
      }
    ]
  }
}

Update endpoint

PATCH /webhooks/endpoints/:id

Updates endpoint URL, subscribed events, or enabled state. Re-enabling an endpoint resets its failure count.

Delete endpoint

DELETE /webhooks/endpoints/:id

Permanently deletes an endpoint and all its delivery history.

Send test event

POST /webhooks/endpoints/:id/test

Sends a ping event to the endpoint with a valid HMAC signature. Use this to verify your endpoint is reachable and correctly validates signatures.

Response:

{
  "success": true,
  "data": {
    "success": true,
    "status_code": 200
  }
}

Message Presets

Save and reuse message templates.

List presets

GET /presets

Returns all saved message presets, sorted by most recently updated.

Create preset

POST /presets

curl -X POST https://app.messengerflow.com/api/v1/presets \
  -H "X-API-Key: mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Hey {{first}}, I saw your page and wanted to reach out..." }'

Delete preset

DELETE /presets/:id

Best Practices

1. Store keys securely — never commit API keys to version control or expose them in client-side code
2. Respect rate limits — implement exponential backoff when you receive a 429 response
3. Handle errors gracefully — check the success field and handle error responses in your integration
4. Use webhooks for real-time data — prefer webhooks over polling to reduce API calls and get instant notifications
5. Paginate large datasets — use limit and offset parameters to avoid loading too much data at once
6. Validate inputs client-side — match the field constraints documented above to avoid unnecessary API calls