Ctrl K

Migasender API reference

22 endpoints · 101 parameters · 36 worked examples

Base URL https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/… Where do I find it?

Nothing found. Try an endpoint name, a path, or a parameter.

Your registration token

Every path starts with /p/<registration token>/. The token tells Migasender which platform the call is for. A wrong token is answered with Unknown platform.; a path without /p/…/ gets HTTP 404.

You can find it in three places:

Your dashboard address. While signed in, the token is everything after /p/ in the browser's address bar, e.g. https://dashboard.migasender.com/p/907a0888…c1f61b.
The old Siberian backoffice. Top menu Manage → Modules → Migawhatsapp (page …/migawhatsapp/backoffice_migawhatsapp), section Migration. On a row with status MIGRATED, the New endpoint column shows https://apidb.migasender.com/p/<token> (API) and https://dashboard.migasender.com/p/<token> (dashboard), each with a copy button. Apps still OFF show only a dash.
The Migasender admin panel (platform administrators): https://apidb.migasender.com/panel/ → Platforms → column Registration Token.

It is not the same as the tokens sent in security_token: the platform token (Line Management, Groups), the Send Message token and the Chat History token. The user manual explains it step by step.

Warning

PLATFORM TOKEN: request it from your platform administrator. The Line Management, QR Code, Instances / Line Log and Groups APIs need the platform token. It is not shown in the customer dashboard or in the API endpoints panel. Administrators find it under Manage → Modules → Migawhatsapp, box Platform Token for API (old backoffice), or at https://apidb.migasender.com/panel/ → Settings → Platform Token for API. (see the user manual).

Response language

Responses come back in Italian by default. Add lang=en — as a query parameter or a body field — to get English, which is the language every message on this page is printed in.

It applies to the error and message fields; data is unaffected. The Accept-Language header is deliberately ignored, so a browser's locale can never silently change what your integration receives.

bash

curl -X POST 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_send/heartbeat?lang=en' \
  -H 'Content-Type: application/json' \
  -d '{ "app_id": 1, "security_token": "YOUR_SEND_MESSAGE_TOKEN" }'

7 endpoints

Line Management

Creating, listing, renaming, re-dating and deleting the WhatsApp lines an application sends from, and setting its monthly cap.

Warning

PLATFORM TOKEN required — request it from your platform administrator. It is not shown in the customer dashboard. Where administrators find it.

The token is a platform token under an app-level name

Easy to get wrong

These endpoints authenticate with your platform token — but the field is called security_token, not platform_token. Sending the Send Message or Chat History token here fails with Security token mismatched.

A “line” is a pair of gateway rows, MASTER and SLAVE. Creating one makes both; deleting one removes both; an update writes to both.

What every Line Management endpoint needs

security_token string Required

Your platform token, despite the field name.

app_id int Required

The application the line belongs to.

Errors any Line Management endpoint can return5

Security token missing.

security_token was not included.

Security token mismatched.

The value is not this platform's token — an app-level API token will fail here.

App id missing.

app_id was not included.

Invalid app id.

No application matches that app_id on this platform.

This app is in read-only mode. Write operations are disabled.

Returned by create, update, delete and the cap setter while the application is read-only. Reads still work.

POST /p/{regToken}/api_line/getall

List every line

Warning

PLATFORM TOKEN required — request it from your platform administrator. It is not shown in the customer dashboard. Where administrators find it.

Returns all of the application's lines, keyed by line ID.

Parameters

The two common parameters are all it needs.

Request

List the lines

bash

curl -X POST 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_line/getall' \
  -H 'Content-Type: application/json' \
  -d '{ "security_token": "YOUR_PLATFORM_TOKEN", "app_id": 1 }'

Response

An object keyed by line_id, not an array.

json

{
  "error": null,
  "data": {
    "1": {
      "line_id": 1,
      "line_label": "My Line 01",
      "line_expiration_date": "UNLIMITED",
      "line_status": "CONFIGURED"
    },
    "2": { "line_id": 2, "line_label": "My Line 02", "…": "…" }
  }
}

POST /p/{regToken}/api_line/get

Get one line

Warning

PLATFORM TOKEN required — request it from your platform administrator. It is not shown in the customer dashboard. Where administrators find it.

Returns a single line, plus the application's Chat History and Send Message tokens.

In addition to the common parameters

line_id int Required

The line to read.

Errors2

Line id missing.

line_id was not included.

Invalid line id.

No line with that ID on this application.

Request

Read line 1

bash

curl -X POST 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_line/get' \
  -H 'Content-Type: application/json' \
  -d '{ "security_token": "YOUR_PLATFORM_TOKEN", "app_id": 1, "line_id": 1 }'

Response

The two API tokens come back with the line.

json

{
  "error": null,
  "data": {
    "line_id": 1,
    "line_label": "My Line 01",
    "line_expiration_date": "UNLIMITED",
    "line_status": "CONFIGURED",
    "chat_api_token": "Lp3qRz9vWx…",
    "send_message_api_token": "Wz7tYp2mKn…"
  }
}

POST /p/{regToken}/api_line/create

Create a line

Warning

PLATFORM TOKEN required — request it from your platform administrator. It is not shown in the customer dashboard. Where administrators find it.

Adds a line to the application — one MASTER and one SLAVE gateway row. Every field beyond the common two is optional.

In addition to the common parameters

line_label string Optional

A name for the line. Must be unique within the application.

line_expiration_date string (date) Optional

Y-m-d, and it has to be in the future. Leave empty for UNLIMITED. Ignored on YEARLY platforms, which always get one year from today.

max_messages_per_month int Optional

The application's monthly cap. Minimum 1.

Errors5

Maximum allowed lines reached.

The application's line entitlement is used up. An entitlement of 0 means unlimited.

Line name already exists.

Another line on this application already uses that line_label.

Invalid date format for line_expiration_date. Expected format: Y-m-d.

The date is not in Y-m-d form.

Invalid date for line_expiration_date. Date should be greater than the current date.

The date is today or in the past.

Invalid max_messages_per_month value.

Not a number, or below 1.

Request

Create an unlimited line

An empty line_expiration_date means the line never expires.

bash

curl -X POST 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_line/create' \
  -H 'Content-Type: application/json' \
  -d '{
    "security_token": "YOUR_PLATFORM_TOKEN",
    "app_id": 1,
    "line_label": "My New Line",
    "line_expiration_date": "",
    "max_messages_per_month": 10000
  }'

POST /p/{regToken}/api_line/update

Update a line

Warning

PLATFORM TOKEN required — request it from your platform administrator. It is not shown in the customer dashboard. Where administrators find it.

Changes a line's label, expiry or status. The change is written to both of its gateway rows.

In addition to the common parameters

You must send at least one of line_expiration_date or line_status, otherwise the call is rejected. line_label alone is not enough.

line_id int Required

The line to change.

line_label string Optional

A new name. Still has to be unique within the application.

line_expiration_date string (date) Optional

Y-m-d, in the future.

line_status string Optional

One of CONFIGURED, NOT_CONFIGURED, EXPIRED, DISABLED.

enable_instance_status_webhook int Optional

Turns the instance-status webhook on for the line.

instance_status_webhook_url string Conditional

Required whenever the webhook is enabled.

Errors7

No data posted for update.

Neither line_expiration_date nor line_status was sent.

Line id missing.

line_id was not included.

Invalid line id.

No line with that ID on this application.

Line status missing.

The status field was present but empty.

Invalid line status.

Not one of the four accepted values.

Line name already exists.

Another line already uses that label.

Instance Status Webhook URL is required when webhook is enabled.

enable_instance_status_webhook is on with no URL.

Request

bash

curl -X POST 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_line/update' \
  -H 'Content-Type: application/json' \
  -d '{
    "security_token": "YOUR_PLATFORM_TOKEN",
    "app_id": 1,
    "line_id": 1,
    "line_label": "Renamed Line",
    "line_status": "CONFIGURED"
  }'

bash

curl -X POST 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_line/update' \
  -H 'Content-Type: application/json' \
  -d '{
    "security_token": "YOUR_PLATFORM_TOKEN",
    "app_id": 1,
    "line_id": 1,
    "line_expiration_date": "2027-01-31"
  }'

POST /p/{regToken}/api_line/setmaxmessagespermonth

Set the monthly message cap

Warning

PLATFORM TOKEN required — request it from your platform administrator. It is not shown in the customer dashboard. Where administrators find it.

Sets how many messages the application may send per month. This is the same cap that produces “You have reached the maximum limit of messages for this month.” on a send.

In addition to the common parameters

max_messages_per_month int Required

The new cap. Minimum 1.

Errors2

Value for max_messages_per_month is missing.

The field was not sent.

Invalid max_messages_per_month value.

Not a number, or below 1.

Request

Raise the cap

bash

curl -X POST 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_line/setmaxmessagespermonth' \
  -H 'Content-Type: application/json' \
  -d '{ "security_token": "YOUR_PLATFORM_TOKEN", "app_id": 1, "max_messages_per_month": 10000 }'

Response

The value comes back formatted.

json

{ "error": null, "data": { "app_id": 1, "max_messages_per_month": "10,000" } }

POST /p/{regToken}/api_line/delete

Delete a line

Warning

PLATFORM TOKEN required — request it from your platform administrator. It is not shown in the customer dashboard. Where administrators find it.

Removes the line, meaning both its MASTER and SLAVE gateway rows.

In addition to the common parameters

line_id int Required

The line to delete.

Errors2

Line id missing.

line_id was not included.

Invalid line id.

No line with that ID on this application.

There is no undo

Deleting removes both gateway rows for the line. Anything that was sending on that line stops, and the connection has to be set up again from a QR scan.

Request

Delete line 2

bash

curl -X POST 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_line/delete' \
  -H 'Content-Type: application/json' \
  -d '{ "security_token": "YOUR_PLATFORM_TOKEN", "app_id": 1, "line_id": 2 }'

Response

json

{
  "error": null,
  "data": {
    "line_id": 2,
    "operation": "DELETED",
    "chat_api_token": "Lp3qRz9vWx…",
    "send_message_api_token": "Wz7tYp2mKn…"
  }
}

POST /p/{regToken}/api_line/heartbeat

Heartbeat

Warning

PLATFORM TOKEN required — request it from your platform administrator. It is not shown in the customer dashboard. Where administrators find it.

Liveness check that also hands back the application's API tokens. On the first call the Chat History and Send Message tokens are provisioned for the app.

Parameters

The two common parameters are all it needs.

Request

Check the API and collect the tokens

bash

curl -X POST 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_line/heartbeat' \
  -H 'Content-Type: application/json' \
  -d '{ "security_token": "YOUR_PLATFORM_TOKEN", "app_id": 1 }'

Response

json

{
  "error": null,
  "data": {
    "status": "success",
    "version": "…",
    "title": "Migawhatsapp Line Management API Running.",
    "chat_api_token": "Lp3qRz9vWx…",
    "send_message_api_token": "Wz7tYp2mKn…"
  }
}

5 endpoints

Send Message

Sending WhatsApp messages: text, media, voice, groups, round-robin lines and Meta Cloud API templates.

How a send is routed

Every send attempts WA API MASTER first and falls back to WA API SLAVE only if the master attempt fails.

Each gateway gets exactly one attempt per request. There is no inner retry loop and no pre-filtering by stored status.
A failed attempt immediately marks that gateway PROBABLY_DISCONNECTED, updates last_status_checked, and recomputes the line's health before the next gateway is tried.
Telemetry is written for every attempt — gateway type, status, timing, and a classified success/failure detail.
The first attempt that succeeds returns success straight away. If both fail, you get a health-aware error envelope.

When both gateways fail

The response carries success: false plus an error_code that reflects the line's aggregate health:

error_code	When	Message
`gateways_probably_disconnected`	Line health is PROBABLY_OFFLINE, or a mix of non-connected statuses	“GATEWAYS ARE PROBABLY DISCONNECTED, WE ARE CHECKING THE REAL STATUS, TRY AGAIN IN ABOUT 10 MINUTES.”
`gateways_disconnected`	Line health is OFFLINE, or every gateway is DISCONNECTED	“GATEWAYS ARE DISCONNECTED. PLEASE RECONNECT BY SCANNING THE QR CODE, THEN TRY AGAIN.”

line_id and app_id come back with it. The envelope is returned after each failed attempt has marked its gateway and triggered the health recomputation.

Which line the message goes out on

line_id	roundbin_id	Behaviour
provided	—	Sends via that specific line.
—	provided	The system picks the least-recently-used connected line in the roundbin.
provided	provided	roundbin_id wins — line_id is ignored.
—	—	Falls back to the application's connected line. With none connected: `no active/connected gateway for this app — connect a line first`

Note

send_via=cloud_api skips line and roundbin routing entirely — no WhatsApp line is involved. Only app_id, security_token and phone are checked before the Meta call.

Fallback to Meta Cloud API

A message can leave through Meta Cloud API instead of the WhatsApp line, as an approved template. Your message text is then not delivered: the template replaces it. This happens in two cases.

Case	When	Which template
Daily threshold	The line has already sent its daily threshold of messages today.	The one in the call (`fallback_template_`), otherwise the line's own. The line's own is used when Fallback Enabled* is on.
Line cannot send	The line does not exist, is not connected, is marked DISCONNECTED, or refuses the send (for example a banned or logged-out number). Also a roundbin whose lines are all down.	Only the one in the call. Without it you get the usual error.

The threshold is counted per line, not per contact, and the counter resets at 00:00 UTC. It counts only the messages that go through the threshold check: the fallback must be active for that message (Fallback Enabled on the line, or a fallback_template_* in the call), and in standard mode a contact who wrote in the last 7 days is skipped and not counted. With threshold 1, the first counted message of the day goes through the line and the next one through Meta. The master and slave sides of a line keep separate counters.
When the template send itself fails, the line's Failure Webhook URL receives {"event":"waba_send_failed", "app_id", "line_id", "phone", "template_name", "error", "fallback_reason", "reference", "timestamp"}. fallback_reason is null for a direct send_via=cloud_api send, and reference is the value you passed in the call.
A number with no WhatsApp account gets nothing: no line send and no template, because Meta Cloud API cannot reach it either. The call returns the error The phone number does not exist on WhatsApp., and the Failure Webhook URL of the line receives the same event with fallback_reason: "number_not_on_whatsapp" and template_name: null. The send shows on the Logs page as failed, does not count toward the monthly limit, and api_send/status with its reference answers state: not_sent, status: failed. If the check itself cannot be done, the message is sent as usual. A number whose account still exists, but whose phone is off or lost, is not caught.
Threshold mode standard (the default) leaves out contacts who have written to the application in the last 7 days, today excluded: they always get the normal message and do not count. strict counts every message.
If the line does not answer in time, nothing is resent through Meta. The message may already have gone out, and a second send would deliver it twice. Send a reference and ask api_send/status with it before retrying: it tells you whether the message went out.
The response says which path was taken. via is migasender for the line and cloud_api_fallback for a fallback, which also carries fallback_reason (threshold, line_not_found, line_disconnected, send_refused, all_lines_down) and Meta's message_id.
Delivery statuses of a fallback reach the line's delivery webhook, like any other send, with channel: "waba".

What every Send Message endpoint needs

app_id int Required

Your application ID, shown at the top left of the module dashboard.

security_token string Required

The Send Message API token, generated under Settings → API Settings with the label Send Message API Token. The API must also be enabled there.

Errors any Send Message endpoint can return2

Security token mismatched.

One answer covers four cases: security_token missing, security_token wrong, app_id missing, or app_id not found. Check both against Settings → API Settings.

Send Message API is disabled.

The Send Message API is switched off for this application. Enable it in the API settings.

POST /p/{regToken}/api_send/message

Send a message

Sends a WhatsApp message — text, media, a voice note, a group message, or a Meta template. Parameters are POST body fields, JSON or form-data.

Authentication

app_id int Required

Your application ID, shown at the top left of the module dashboard.

security_token string Required

The Send Message API token, generated under Settings → API Settings with the label Send Message API Token. The Send Message API must also be enabled there.

Recipient and content

phone string Conditional

10–14 digits with a leading + and country code. Optional if you send email for a registered user who has a valid phone on their profile; otherwise required. Not used at all for group sends. If the number already exists in the database you also get sib_user_id back.

email string Conditional

A valid address that exists in the database, with a phone number attached to that account. Optional if you send phone instead. When both are sent, the API checks the pair exists before it sends anything.

message string Conditional

The text to send. Optional when file_url is present, since a file can be sent on its own.

name string Optional

First name — only if you also want the user registered.

surname string Optional

Last name — only if you also want the user registered.

file_url url Optional

Any publicly reachable file URL that WhatsApp supports. Max 25 MB. Audio files only work while the MASTER gateway is up.

is_link_preview_enabled int Optional

1 shows the link preview (default), 0 hides it.

Text to speech

tts_enabled int Optional

1 converts the message text to audio and sends it as a voice note instead of text; 0 is the default. MASTER gateway only, and TTS must be enabled for the application.

tts_voice string Optional

OpenAI: alloy (default), echo, fable, onyx, nova, shimmer. ElevenLabs: the voice_id shown under the player of the chosen voice. The provider is picked in Settings → OpenAI Configuration → TTS Service.

tts_speed float Optional

OpenAI: 0.25–4.0, default 1.0. ElevenLabs: 0.1–1.2. Below 1.0 slows the speech down, above speeds it up.

Routing

line_id int Optional

The line to send from. Must be valid; defaults to 1 when not posted. Found under Gateway Settings → WhatsApp Line Management, in the Line ID column.

roundbin_id int Optional

A roundbin group. The system picks the next available connected line from it (least-recently-used rotation) and overrides line_id. If every line in the group is disconnected and the roundbin has a fallback template configured, that template is sent via Meta Cloud API instead.

Group send

is_sent_to_group int Optional

1 tells the API this is a group message. 0 or not posted means a normal send.

group_id string Conditional

Required when is_sent_to_group=1, and phone then stops being required. Format: 1203630000000000@g.us. Get the IDs from the List groups endpoint below.

Direct Meta Cloud API send

send_via string Optional

Set to cloud_api to bypass the WhatsApp line entirely and send a Meta template. Default migasender.

template_name string Conditional

Required when send_via=cloud_api. The exact template name as it appears in Meta Business Manager, and it must be APPROVED.

template_language string Optional

BCP-47 code matching the approved template's language. Default en_US.

template_variables array | string Optional

Ordered values for the template body's {{1}}, {{2}} … Accepts a native array or a JSON-encoded string. The count must match the template exactly.

template_buttons array | string Optional

Payloads for URL-type buttons — each element is the dynamic URL suffix or coupon code.

Per-call fallback template

Used only when the message goes to the fallback: at the daily line threshold, or when the line cannot send. For this one request they replace the fallback template configured on the line. See Fallback to Meta Cloud API above.

fallback_template_name string Optional

Name of an APPROVED template on the application's WABA. Sending it turns the fallback on for this message, even when it is off on the line. The name wins if fallback_template_id is also sent.

reference string Optional

Your own id for this send, up to 255 characters. It comes back as reference on the failure webhook, and if the send times out you can ask api_send/status with it whether the message actually went out. This works for line sends and for Cloud API sends, including fallbacks.

not_sent_after int Optional

Seconds without confirmation, after a send that timed out, before api_send/status answers not_sent for its reference. From 60 to 86400; default 180 (3 minutes).

fallback_template_id int Optional

The template's local ID (template_id). Useful when several templates share a name across languages. Ignored if fallback_template_name is also sent.

fallback_template_language string Optional

Normally resolved automatically from the stored template record. Send this only to override it.

fallback_template_variables array | string Optional

Values for the fallback template. The count is validated against the template before anything is sent.

fallback_template_buttons array | string Optional

Button payloads for URL buttons in the fallback template.

Errors40

Gateway settings do not exist.

No active gateway for that app_id + line_id.

GATEWAYS ARE PROBABLY DISCONNECTED… TRY AGAIN IN ABOUT 10 MINUTES.

Health-aware envelope, error_code: gateways_probably_disconnected.

GATEWAYS ARE DISCONNECTED. PLEASE RECONNECT BY SCANNING THE QR CODE…

Health-aware envelope, error_code: gateways_disconnected.

No eligible gateway available for retry.

No working gateway was found during sending.

message or media is required

Neither message nor file_url was provided.

phone is required

Neither phone nor email was provided.

Phone number is missing or invalid. Include country code, e.g. +39123456789.

Malformed phone — it must start with + and carry the country code.

The phone number does not exist on WhatsApp.

The number has no WhatsApp account. Nothing was sent, and the Failure Webhook URL of the line received fallback_reason: "number_not_on_whatsapp".

The email address is invalid.

Malformed email.

No such account exists with this email and phone pair.

You sent both, and that pair is not in the database — when both are sent the API checks the user first. Sending name and surname as well creates the account instead, and returns sib_user_id.

The phone number associated with this account is not correct. …The current one is: API_SENT_PHONE_NUMBER

Email-only send; the account exists but its stored phone is invalid.

No phone number is associated with this account.

Email-only send; the account exists but has no phone attached.

No such account exists with this email.

Email-only send; no account with that address.

We are sorry but this account is already linked to one of our customers.

Email-only send with name/surname; the address already belongs to another customer.

The file does not exist.

file_url was given but nothing is served at that URL.

The file size is too large. The maximum file size allowed is 25 MB.

The file exceeds the 25 MB cap.

The file type is not supported.

The file is outside the supported types — see the note below this table.

The tts_voice value is not valid.

The voice is not one of the accepted options.

The tts_speed value must be between 0.25 and 4.0.

Out of range for OpenAI.

The tts_speed value must be between 0.1 and 1.2 for ElevenLabs.

Out of range for ElevenLabs.

Text to Speech is not enabled for this application.

tts_enabled=1 but TTS is disabled or not configured for the app.

Service is temporarily unavailable, please try later.

tts_enabled=1 and no gateway is CONNECTED at all.

no active/connected gateway for this app — connect a line first

The line_id does not resolve to a usable gateway. This is also what you get when no line is connected at all.

Roundbin not found.

No roundbin with that roundbin_id on this application.

You cannot send a message because your line status is EXPIRED|DISABLED|NOT_CONFIGURED.

The chosen line is not in CONFIGURED status.

All lines in this roundbin are disconnected and no fallback template is set.

Every line in the roundbin is down and it has no fallback template. Reconnect a line or configure one.

You have reached the maximum limit of messages for this month.

The monthly cap — 10,000 by default — counts every successful outgoing message. This is a platform limit, not the daily threshold.

The is_link_preview_enabled value is not valid.

A value other than 0 or 1.

The phone number does not exist on WhatsApp.

The recipient has no WhatsApp account.

Group id missing.

is_sent_to_group=1 but group_id is missing or empty.

Group not found.

group_id is not a valid group. Only raised on WA API MASTER — the slave gateway does not support groups or this validation.

template_name is required for cloud_api send.

without a template name.

Template requires {N} variables, {M} provided.

The template_variables count does not match the template definition.

Fallback template not found or not approved.

fallback_template_id does not match an APPROVED template of this application. Re-sync templates from Meta.

Fallback template '{name}' requires {N} variables, {M} provided.

Variable count mismatch on the per-call fallback template.

{line error} Fallback template send failed: {reason}

The line could not send, and the fallback template was refused too. Nothing was delivered. The first part says why the line failed, the second why Meta refused.

{line error} Fallback template not delivered: {reason}

The line could not send. Meta accepted the fallback template, then reported it as not delivered.

(#190) Access token has expired

The Meta WABA access token expired. Reconnect from the WABA Config page.

(#132000) Variable parameter count mismatch

Meta rejected the template call — the variable count does not match the definition on Meta's side.

(#131005) …

A Meta Cloud API limit or permission error. Check the WABA account status in Meta Business Manager.

Supported file types

Images image/jpeg, image/jpg, image/png · Video video/mp4, video/ogg, application/octet-stream · Audio audio/mpeg, audio/ogg · Documents application/pdf, application/msword, Word/Excel/PowerPoint OpenXML types, application/vnd.ms-excel, application/vnd.ms-powerpoint, text/plain, text/html, text/css, application/ics.

Fallback is not the same as a direct Cloud API send

send_via=cloud_api always goes through Meta, whatever the daily counter says. The fallback_template_* parameters only act on a send through the line (migasender): the template goes out when the daily line threshold is hit, or when the line cannot send. A per-call fallback replaces the line's configured fallback for that one request only.

Template language must match exactly

Language codes have to match the approved template on Meta — it, en_US, en, pt_BR. A mismatch makes Meta return a template-not-found error.

A threshold fallback that Meta also rejects

You get HTTP 200 with the error set and the real Meta message propagated, e.g. { "error": "(#190) Access token has expired", "data": null }. The daily line threshold was hit and the Meta send failed, so nothing was delivered.

Request

The minimum for a text send is security_token + app_id + phone + message.

json

{
  "app_id": "12",
  "security_token": "YOUR_SEND_MESSAGE_TOKEN",
  "line_id": "1",
  "phone": "+391234567890",
  "message": "Hello! Your order has been confirmed.",
  "is_link_preview_enabled": 1
}

No message needed when a file is attached.

php

<?php
$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_send/message',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST  => 'POST',
  CURLOPT_POSTFIELDS => [
    'security_token' => 'YOUR_SEND_MESSAGE_TOKEN',
    'app_id'         => '4',
    'phone'          => '+391234567890',
    'file_url'       => 'https://example.com/samples/audio/mp3/sample3.mp3',
  ],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;

MASTER gateway only, and TTS must be enabled for the application.

json

{
  "app_id": "12",
  "security_token": "YOUR_SEND_MESSAGE_TOKEN",
  "phone": "+391234567890",
  "message": "Your appointment is confirmed for Monday at 10.",
  "tts_enabled": 1,
  "tts_voice": "nova",
  "tts_speed": 0.9
}

With is_sent_to_group=1, group_id becomes required and phone is not used.

json

{
  "app_id": "12",
  "security_token": "YOUR_SEND_MESSAGE_TOKEN",
  "line_id": "1",
  "is_sent_to_group": 1,
  "group_id": "1203630000000000@g.us",
  "message": "Welcome to the group!"
}

The system auto-selects the least-recently-used connected line.

json

{
  "app_id": "12",
  "security_token": "YOUR_SEND_MESSAGE_TOKEN",
  "roundbin_id": 3,
  "phone": "+391234567890",
  "message": "Hello! Your order has been confirmed."
}

The WhatsApp line is bypassed entirely — no line_id or roundbin_id needed.

json

{
  "app_id": "12",
  "security_token": "YOUR_SEND_MESSAGE_TOKEN",
  "phone": "+391234567890",
  "send_via": "cloud_api",
  "template_name": "order_confirmation",
  "template_language": "en_US",
  "template_variables": ["Mario Rossi", "#ORD-9981"]
}

Below the threshold, with the line working, this sends normally over the WhatsApp line. Once the threshold is hit, or if the line cannot send, daily_limit_reached goes out via Meta instead. The language is resolved from the stored template record.

json

{
  "app_id": "12",
  "security_token": "YOUR_SEND_MESSAGE_TOKEN",
  "line_id": "1",
  "phone": "+391234567890",
  "message": "Ciao! Come posso aiutarti?",
  "fallback_template_name": "daily_limit_reached",
  "fallback_template_variables": ["Mario"]
}

Resolved by local record ID — useful when templates share a name across languages. fallback_template_name still wins if both are sent.

json

{
  "app_id": "12",
  "security_token": "YOUR_SEND_MESSAGE_TOKEN",
  "line_id": "1",
  "phone": "+391234567890",
  "message": "Ciao! Come posso aiutarti?",
  "fallback_template_id": 7,
  "fallback_template_variables": ["Mario"]
}

Roundbin routing, with a message-specific fallback if the selected line's threshold is hit.

json

{
  "app_id": "12",
  "security_token": "YOUR_SEND_MESSAGE_TOKEN",
  "roundbin_id": 3,
  "phone": "+391234567890",
  "message": "Your appointment is confirmed.",
  "fallback_template_name": "appointment_reminder",
  "fallback_template_variables": ["Anna", "Monday 14 July", "10:00 AM"]
}

Response

Sent. sib_user_id can be 0 when only a phone was sent and no account matched.

json

{
  "error": null,
  "data": {
    "status": "success",
    "via": "migasender",
    "message": "Message sent successfully.",
    "sib_user_id": 51,
    "message_id": "3EB0D9E8F5E3ED652D72FF"
  }
}

Sent, and a new user account was created along the way. sib_user_password comes back in clear text so you can pass it to the user.

json

{
  "error": null,
  "data": {
    "status": "success",
    "via": "migasender",
    "message": "Message sent successfully with the new user account creation.",
    "sib_user_id": 22,
    "sib_user_password": "5oc3qwLwn",
    "message_id": "3EB0D9E8F5E3ED652D72FF"
  }
}

The via field tells you which path the message actually took.

json

// WhatsApp line
{ "error": null, "data": { "status": "success", "via": "migasender",
  "message": "Message sent successfully.", "message_id": "3EB0D9E8F5E3ED652D72FF" } }

// Direct Meta Cloud API
{ "error": null, "data": { "status": "success", "via": "cloud_api",
  "message": "Template sent successfully.", "message_id": "wamid.HBgMMzkzMzk..." } }

// Daily line threshold was hit — the fallback template went out via Meta
// instead, and your original "message" text was NOT delivered.
{ "error": null, "data": { "status": "success", "via": "cloud_api_fallback",
  "fallback_reason": "threshold",
  "message": "Daily threshold reached — fallback template sent via Meta Cloud API.",
  "message_id": "wamid.HBgMMzkzMzk..." } }

// The line could not send (fallback_reason: line_not_found, line_disconnected,
// send_refused or all_lines_down) and the call carried a fallback template.
{ "error": null, "data": { "status": "success", "via": "cloud_api_fallback",
  "fallback_reason": "line_disconnected",
  "message": "Line unavailable — fallback template sent via Meta Cloud API.",
  "message_id": "wamid.HBgMMzkzMzk..." } }

POST /p/{regToken}/api_send/checkphone

Check a phone number

Answers whether a number exists on WhatsApp. Three parameters only. The same check runs inside the message endpoint.

app_id int Required

Your application ID.

security_token string Required

The Send Message API token.

phone string Required

10–14 digits with a leading + and country code.

Errors2

The service is currently unavailable due to an issue with the WA API Master. Please try again later.

The MASTER server is down — this endpoint has no slave fallback.

The phone number is not correct. Please add a phone between 10-14 digits with + international country code at the beginning.

Malformed phone.

Request

Check a number

php

<?php
$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_send/checkphone',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST  => 'POST',
  CURLOPT_POSTFIELDS => [
    'security_token' => 'YOUR_SEND_MESSAGE_TOKEN',
    'app_id'         => '4',
    'phone'          => '+391234567890',
  ],
]);
echo curl_exec($curl);
curl_close($curl);

Response

The check is always served by the MASTER gateway.

json

{ "error": null, "data": { "number_exists": true } }

{ "error": null, "data": { "number_exists": false } }

POST /p/{regToken}/api_send/status

Check the status of a sent message

Answers what happened to a message after the send: by the message_id the send returned, or by your own reference when the send timed out and returned no id.

app_id int Required

Your application ID.

security_token string Required

The Send Message API token.

message_id string Conditional

The message_id returned by the send (a line id or a Cloud API wamid). Send this or reference.

reference string Conditional

The reference you passed to the send: a line send, a direct send_via=cloud_api send, or one the fallback moved to Cloud API. Use it when the send timed out and returned no message_id: the answer says whether the message actually went out.

Errors3

message_id is required.

Neither message_id nor reference was sent.

message_id not found.

No message with that id on this application.

reference not found.

No send carried that reference: the send never reached a line (refused or invalid), or the reference is wrong. A send refused because the number has no WhatsApp does have a record: it answers not_sent.

Request

Ask before retrying a timed-out send

bash

curl -X POST 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_send/status?lang=en' \
  -H 'Content-Type: application/json' \
  -d '{ "security_token": "YOUR_SEND_MESSAGE_TOKEN", "app_id": 4, "reference": "order-4711" }'

Response

By message_id: the delivery status (sent, delivered, read, failed, or pending when unconfirmed after 30 minutes) and, for a failure, Meta's reason.

json

{ "error": null, "data": { "message_id": "3EB0C008DCF2843EE4F6F8", "status": "delivered", "reason": null, "phone": "+391234567890", "channel": "migasender", "sent_at": "2026-09-30T09:19:38.000Z", "updated_at": "2026-09-30T09:19:39.529Z" } }

By reference: state tells you whether you can retry. sent: the message went out, do not retry (message_id, channel (migasender for the line, waba for Cloud API) and the delivery status are filled in). not_sent: the send timed out and was never confirmed within its window (not_sent_after, default 3 minutes), or its delivery failed, so it is safe to retry. unknown: it timed out moments ago, ask again shortly. When several sends share a reference, the newest one is described.

json

{ "error": null, "data": { "reference": "order-4711", "state": "sent", "message_id": "3EB0C008DCF2843EE4F6F8", "status": "delivered", "reason": null, "phone": "+391234567890", "channel": "migasender", "sent_at": "2026-09-30T09:19:38.000Z", "updated_at": "2026-09-30T09:19:39.529Z" } }

{ "error": null, "data": { "reference": "order-4712", "state": "not_sent", "message_id": null, "status": "pending", "reason": null, "phone": "+391234567890", "channel": "migasender", "sent_at": "2026-09-30T10:56:30.976Z", "updated_at": "2026-09-30T10:56:30.976Z" } }

POST /p/{regToken}/api_send/groups

List the groups on a line

Returns every WhatsApp group the line belongs to, with the group_id values you need for a group send.

app_id int Required

Your application ID.

security_token string Required

The Send Message API token.

line_id int Optional

Defaults to 1 when not posted.

Request

List groups

php

<?php
$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_send/groups',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST  => 'POST',
  CURLOPT_POSTFIELDS => [
    'security_token' => 'YOUR_SEND_MESSAGE_TOKEN',
    'app_id'         => '4',
    'line_id'        => '1',
  ],
]);
echo curl_exec($curl);
curl_close($curl);

Response

subject is the group's name.

json

{
  "error": null,
  "data": {
    "groups": [
      { "id": "1203630000000001@g.us", "subject": "The Student Network" },
      { "id": "1203630000000002@g.us", "subject": "Humdum community" }
    ]
  }
}

POST /p/{regToken}/api_send/heartbeat

Heartbeat

Confirms the Send Message API is reachable and your token and app ID are accepted. Accepts the same parameters as the message endpoint, but sends nothing.

Parameters

The two common parameters are all it needs.

Response shape

The official document does not print a sample body for the heartbeat endpoints, so none is reproduced here. Treat a response with error: null as reachable, and read the error table above for the failure cases.

Request

Heartbeat

bash

curl -X POST 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_send/heartbeat' \
  -H 'Content-Type: application/json' \
  -d '{ "app_id": "4", "security_token": "YOUR_SEND_MESSAGE_TOKEN" }'

2 endpoints

Chat History

Reading stored conversations, with filters for phone, email, date, line, origin, destination and direction.

What comes back

Media messages appear in the same message key as text. When a message has both, the text is prepended to the media URL.

Every record carries an in_out field — IN for incoming, OUT for outgoing — and you can filter on it.

Important

filter_start_time is matched against your server's clock, so the application or server timezone has to be set correctly for it to mean what you expect.

What every Chat History endpoint needs

app_id int Required

Your application ID.

security_token string Required

The Chat History API token, generated under Settings → API Settings with the label Chat History API Token. The API must also be enabled there.

Errors either Chat History endpoint can return2

Security token mismatched.

One answer covers four cases: security_token missing, security_token wrong, app_id missing, or app_id not found. Check both against Settings → API Settings.

Chat History API is disabled.

The Chat History API is switched off for this application. Enable it in the API settings.

GET /p/{regToken}/api_chathistory/history

Read chat history

Returns stored messages for the application, newest filters applied. All filters are optional and combine.

Note

Older documentation shows this endpoint as a POST. It is a GET, and the filters are query-string parameters.

Authentication

app_id int Required

Your application ID.

security_token string Required

The Chat History API token, generated under Settings → API Settings with the label Chat History API Token. The Chat History API must also be enabled there.

Filters

filter_history_id int Optional

The chat/log ID to start from — passing 10 returns the history from 10 onward.

filter_start_date string (date) Optional

yyyy-mm-dd. Matched against the record's created_at; returns history from that date onward.

filter_start_time string (time) Optional

HH:mm:ss. Only valid together with filter_start_date. Uses the server's timezone.

filter_phone_number string (phone) Optional

10–14 digits with a leading + and country code.

filter_email string (email) Optional

Filters by a customer's email, if the customer exists and has one assigned.

filter_origin string Optional

One of WA API MASTER, WA API SLAVE, MIGACHAT, API, WEBHOOK. Messages sent from a line through api_send/message are returned only when you filter on API.

filter_destination string Optional

One of WA API MASTER, WA API SLAVE, MIGACHAT, WEBHOOK, WA_USER.

filter_line_id int Optional

Accepted but not applied. The request succeeds and the value is ignored, so the result set is not restricted to that line. Filter by line on your side for now.

filter_in_out string Optional

Accepted but not applied. IN / OUT are ignored; every record carries its own in_out field, so filter on that after reading.

Errors1

This app has not yet configured the gateway settings so you cannot get the history.

The app has no gateway configured.

Filters are not validated — a bad value is ignored, not rejected

A malformed date, an origin outside the list, a direction that is neither IN nor OUT: none of these is refused. The filter is simply not applied, and you get the unfiltered result set with error: null. Validate filter values before you send them, and check the row count against what you expected rather than assuming an empty error means the filter was understood.

Request

bash

curl 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_chathistory/history?security_token=YOUR_CHAT_HISTORY_TOKEN&app_id=1'

The time is only accepted alongside a date.

bash

curl 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_chathistory/history?security_token=YOUR_CHAT_HISTORY_TOKEN&app_id=1&filter_start_date=2026-08-22&filter_start_time=11:00:00'

Every record carries in_out, so pick the direction you want after reading — filter_in_out is not applied.

bash

curl 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_chathistory/history?security_token=YOUR_CHAT_HISTORY_TOKEN&app_id=1&filter_phone_number=%2B391234567890&lang=en'

php

<?php
$qs = http_build_query([
  'security_token'    => 'YOUR_CHAT_HISTORY_TOKEN',
  'app_id'            => '4',
  'filter_history_id' => '10',
  'lang'              => 'en',
  'filter_origin'     => 'WA API MASTER',
]);

$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_chathistory/history?' . $qs,
  CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($curl);
curl_close($curl);

Response

Nothing matched.

json

{
  "error": null,
  "data": { "status": "success", "message": "No chat history found." }
}

A sent_to other than null means the message went from the owner to that number.

json

{
  "error": null,
  "data": [
    {
      "log_id": "56",
      "line_id": "2",
      "firstname": "John | N/A",
      "lastname": "Doe | N/A",
      "email": "john@mail.com | N/A",
      "phone": "+391234567890 | N/A",
      "sent_to": null | "+391234567890",
      "origin": "WA API MASTER | API | …",
      "destination": "WA API MASTER | WEBHOOK | …",
      "message": "Some Message | N/A",
      "log_time_stamp": "February 11, 2025 07:47:10",
      "log_status": "success | error | NO_COUNTRY…",
      "in_out": "IN | OUT"
    }
  ]
}

GET /p/{regToken}/api_chathistory/heartbeat

Heartbeat

Confirms the Chat History API is reachable and your token is accepted.

Note

Older documentation gives this path as api_chat/heartbeat. The current path is api_chathistory/heartbeat, and it accepts both GET and POST.

Parameters

The two common parameters are all it needs.

Response shape

The official document does not print a sample body for the heartbeat endpoints, so none is reproduced here. Treat a response with error: null as reachable.

Request

Heartbeat

bash

curl 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_chathistory/heartbeat?security_token=YOUR_CHAT_HISTORY_TOKEN&app_id=1'

5 endpoints · v2.0.0

QR Code

Connecting a WhatsApp number to a line: fetching the QR code, following the scan, and checking what a line is doing afterwards.

Warning

PLATFORM TOKEN required — request it from your platform administrator. It is not shown in the customer dashboard. Where administrators find it.

What changed in v2.0.0

/get now reuses the same pending instance_id by default, so repeated calls no longer pile up duplicate sessions.
Send action=RESET or reset=1 to deliberately force a fresh instance and a fresh QR.
QR requests are rate limited at line, app and platform level, configurable in the backoffice.
A line's QR counters reset automatically once a scan succeeds.
Rate-limit errors tell you exactly when the cooldown ends.

Default rate limits

Level	Min interval	Window	Max requests	Cooldown
Line	30s	600s	5	1800s
App	—	600s	20	1800s
Global	—	600s	100	1800s

All nine values are editable in the backoffice under QR Code API Rate Limits.

Parameters every QR endpoint needs

platform_token string Required

Platform-wide token from the backoffice, section Platform Token for API. May also be sent as the X-Platform-Token header.

app_id int Required

Your application ID, shown at the top left of the module dashboard.

line_id int Required

The line you want to act on.

whatsapp_gateway_type string Required

Which gateway of the line: WA API MASTER or WA API SLAVE.

action / reset string / int Optional

Send action=RESET or reset=1 to force a fresh instance and QR. Without it, /get reuses the existing pending instance_id instead of opening a duplicate session.

Errors any QR endpoint can return15

Platform token missing.

No platform_token and no X-Platform-Token header.

Platform settings not found.

The platform has no settings at all.

Platform token not found.

Settings exist, but no platform token is stored on them.

Platform token mismatched.

The token sent is not the platform's token.

App id missing.

app_id was not sent.

Invalid app id.

No application matches that app_id.

Line id missing.

line_id was not sent.

WhatsApp gateway type is missing.

Every request must say which gateway: WA API MASTER or WA API SLAVE.

WhatsApp gateway type is invalid.

The value sent is neither of the two accepted ones.

Line settings do not exist.

The combination of parameters sent does not belong to a line.

Line status is EXPIRED | DISABLED.

A line in either state cannot be manipulated.

Line QR rate limit reached (max X requests per Y seconds). Please wait until YYYY-MM-DD HH:MM:SS before trying again.

Per-line limit. The message carries the exact time the cooldown ends.

App QR rate limit reached (max X requests per Y seconds). Please wait until YYYY-MM-DD HH:MM:SS before trying again.

Per-application limit.

Platform QR rate limit reached (max X requests per Y seconds). Please wait until YYYY-MM-DD HH:MM:SS before trying again.

Platform-wide limit.

Please wait 25s before requesting a new QR code for this line. Next allowed at YYYY-MM-DD HH:MM:SS.

The minimum interval between two QR requests on the same line.

POST /p/{regToken}/api_qr/get

Get a QR code

Warning

PLATFORM TOKEN required — request it from your platform administrator. It is not shown in the customer dashboard. Where administrators find it.

Returns a base64 PNG to display for scanning, plus the instance_id you will need to follow the scan.

In addition to the common parameters

phone string Required

10–14 digits with a leading + and country code. Must be unique per line, and must be the same number that will scan the QR.

Errors4

Phone is missing.

phone was not posted, or is empty.

The phone number is not correct. Please add a phone between 10-14 digits with + international country code at the beginning.

Malformed phone.

This phone number is already used.

Another line already uses that number.

This gateway for the line is already working. You cannot get the QR code for it.

The gateway is already connected — there is nothing to scan.

The QR expires in 30 seconds

Render the base64 string straight into an <img> tag. If it is not scanned within 30 seconds it expires and may stop working. Keep the instance_id — every following call needs it.

Then start polling

As soon as the QR is on screen, call check-scan-status every 2000 ms with the instance_id (and team_id on a slave gateway) until it reports success.

Request

php

<?php
$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_qr/get',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST  => 'POST',
  CURLOPT_POSTFIELDS => [
    'platform_token'        => 'YOUR_PLATFORM_TOKEN',
    'app_id'                => '4',
    'line_id'               => '2',
    'whatsapp_gateway_type' => 'WA API SLAVE',
    'phone'                 => '+391234567890',
  ],
]);
echo curl_exec($curl);
curl_close($curl);

Without reset, the pending instance is reused.

bash

curl -X POST 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_qr/get' \
  -H 'Content-Type: application/json' \
  -d '{
    "platform_token": "YOUR_PLATFORM_TOKEN",
    "app_id": 4,
    "line_id": 2,
    "whatsapp_gateway_type": "WA API MASTER",
    "phone": "+391234567890",
    "reset": 1
  }'

Response

WA API MASTER — no team_id in the response.

json

{
  "error": null,
  "data": {
    "success": true,
    "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg…",
    "instance_id": "67FT9ES73503T"
  }
}

WA API SLAVE — the extra team_id must be passed to the status endpoints.

json

{
  "error": null,
  "data": {
    "success": true,
    "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg…",
    "instance_id": "67FT9ES73503T",
    "team_id": 99
  }
}

POST /p/{regToken}/api_qr/check-scan-status

Check the scan status

Warning

PLATFORM TOKEN required — request it from your platform administrator. It is not shown in the customer dashboard. Where administrators find it.

Poll this after showing the QR to find out whether it has been scanned yet.

In addition to the common parameters

instance_id string Required

The instance ID returned by /get.

team_id int Conditional

Required only on WA API SLAVE, where /get returned it. Not used on MASTER.

Errors2

Instance ID is missing.

instance_id was not posted.

Team id is missing.

A slave-gateway call without team_id.

Polling cadence

Call every 2000 ms while the QR is displayed. Stop as soon as status is success and message is Success.

Request

Poll for the scan

bash

curl -X POST 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_qr/check-scan-status' \
  -H 'Content-Type: application/json' \
  -d '{
    "platform_token": "YOUR_PLATFORM_TOKEN",
    "app_id": 4,
    "line_id": 2,
    "whatsapp_gateway_type": "WA API SLAVE",
    "instance_id": "67FT9ES73503T",
    "team_id": 99
  }'

Response

Not scanned yet — keep polling.

json

{ "error": null, "data": { "success": true, "status": "error", "message": "Unsuccess" } }

Scanned. Stop polling; the line's QR counters reset automatically.

json

{ "error": null, "data": { "success": true, "status": "success", "message": "Success" } }

POST /p/{regToken}/api_qr/get-current-status

Get the current status

Warning

PLATFORM TOKEN required — request it from your platform administrator. It is not shown in the customer dashboard. Where administrators find it.

Tells you whether a stored instance is working right now. Save the instance_id locally after /get and use it here whenever you need the live state.

In addition to the common parameters

instance_id string Required

The instance ID returned by /get, kept in your own database.

Errors2

Instance ID is missing.

instance_id was not posted.

Instance ID mismatched.

That instance does not belong to the matched gateway settings.

Request

Check an instance

bash

curl -X POST 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_qr/get-current-status' \
  -H 'Content-Type: application/json' \
  -d '{
    "platform_token": "YOUR_PLATFORM_TOKEN",
    "app_id": 4,
    "line_id": 1,
    "whatsapp_gateway_type": "WA API SLAVE",
    "instance_id": "67FT9ES73503T"
  }'

Response

status is WORKING or NOT_WORKING.

json

{
  "error": null,
  "data": {
    "instance_id": "67FT9ES73503T",
    "status": "WORKING",
    "whatsapp_gateway_type": "WA API SLAVE"
  }
}

POST /p/{regToken}/api_qr/rescan

Rescan

Warning

PLATFORM TOKEN required — request it from your platform administrator. It is not shown in the customer dashboard. Where administrators find it.

Returns a fresh QR for an instance that has stopped working, so the number can be reconnected.

In addition to the common parameters

instance_id string Required

The instance ID to reconnect. Only meaningful when that instance is NOT_WORKING.

Errors5

Instance ID is missing.

instance_id was not posted.

Instance ID mismatched.

That instance does not belong to the matched gateway settings.

Line status is NOT_CONFIGURED.

The line was never configured, so there is no status to recover.

This instance is not configured.

The line is CONFIGURED but not for this instance — a line can hold at least two.

This instance is already working.

There is nothing to rescan.

Rescan is rate limited too

The same line, app and global limits apply. Then poll check-scan-status every 2000 ms, exactly as after /get.

Request

Reconnect a dead instance

bash

curl -X POST 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_qr/rescan' \
  -H 'Content-Type: application/json' \
  -d '{
    "platform_token": "YOUR_PLATFORM_TOKEN",
    "app_id": 4,
    "line_id": 2,
    "whatsapp_gateway_type": "WA API SLAVE",
    "instance_id": "67FT9ES73503T"
  }'

Response

Same shape as /get — base64 QR, instance_id, and team_id on a slave gateway.

json

{
  "error": null,
  "data": {
    "success": true,
    "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg…",
    "instance_id": "67FT9ES73503T"
  }
}

POST /p/{regToken}/api_qr/get-instance-info

Get instance info

Warning

PLATFORM TOKEN required — request it from your platform administrator. It is not shown in the customer dashboard. Where administrators find it.

Returns the gateway access token, the bound phone, and both the line and instance status. Works with the common parameters alone — change whatsapp_gateway_type to look at the other gateway.

Parameters

No extra parameters — the four common ones are enough.

Errors1

Instance not found.

No such instance or line in the system.

Request

Inspect the master gateway of a line

php

<?php
$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_qr/get-instance-info',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST  => 'POST',
  CURLOPT_POSTFIELDS => [
    'platform_token'        => 'YOUR_PLATFORM_TOKEN',
    'app_id'                => '4',
    'line_id'               => '1',
    'whatsapp_gateway_type' => 'WA API MASTER',
  ],
]);
echo curl_exec($curl);
curl_close($curl);

Response

line_status is CONFIGURED or NOT_CONFIGURED; instance_status is WORKING or NOT_WORKING. The two vary independently.

json

{
  "error": null,
  "data": {
    "access_token": "YOUR_ACCESS_TOKEN_FOR_GATEWAY",
    "instance_id": "67FT9ES73503T",
    "phone": "+391234567890",
    "line_status": "CONFIGURED",
    "instance_status": "WORKING"
  }
}

2 endpoints · v1.0.0

Groups

Creating WhatsApp groups from an external system, and reading what was said in them.

Warning

PLATFORM TOKEN required — request it from your platform administrator. It is not shown in the customer dashboard. Where administrators find it.

Before the first call

This family is authenticated by a single platform token, sent either as the X-Platform-Token header or as a platform_token body field. Group creation runs through a dedicated AI agent line that has to be configured first.

In the backoffice, under AI Agent Settings, fill in all six fields:

AI Agent Name
AI Agent Instance ID
AI Agent Access Token
AI Agent Phone — E.164, e.g. +391234567890
AI Agent Gateway API URL
AI Agent Gateway API Key

The same screen holds the Platform Token for API to copy, the Group Creation Logs for created and failed groups, and the Group Chat History viewer with filters, media links and an ADMIN badge on the agent's own messages.

Every endpoint answers with the same envelope: { "error": null | string, "data": object | null }.

Parameter every Groups endpoint needs

platform_token string Required

Platform-wide token from the backoffice. May be sent as the X-Platform-Token header instead of a body field.

POST /p/{regToken}/api_group/create

Create a group

Warning

PLATFORM TOKEN required — request it from your platform administrator. It is not shown in the customer dashboard. Where administrators find it.

Creates a WhatsApp group with the AI agent as its creator and admin. Body is raw JSON.

In addition to the platform token

members array Required

At least 2 phone numbers in E.164 format with a leading +. The AI agent is added on top, so the smallest possible group is 3 people.

group_name string Optional

The group title. If omitted, the gateway generates a default name.

description string Optional

The group description.

metadata object Optional

Anything you want to keep with the group — match_id, source, and so on.

Errors6

Platform token missing.

No token in the header or the body.

Platform token mismatched.

The token sent is not the platform's.

At least 2 member phone numbers are required.

Fewer than two valid numbers — and they must exist on WhatsApp.

Invalid member phone number. Use +countrycode format.

One of the numbers is not in E.164 format.

Invalid date for line_expiration_date. Date should be greater than the current date.

line_expiration_date is in the past.

AI agent instance ID is missing in settings.

AI Agent Settings are incomplete in the backoffice.

Where the gateway credentials come from

The Gateway API URL and API Key used for the creation are read from AI Agent Settings — you never send them on the call.

Request

Create a group

php

<?php
$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_group/create',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST  => 'POST',
  CURLOPT_POSTFIELDS => '{
    "group_name": "Match - Alice & Bob",
    "description": "Welcome",
    "members": ["+391234567890", "+391234567891"],
    "metadata": {"match_id": "MIGAMATCH-123"}
  }',
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'X-Platform-Token: YOUR_PLATFORM_TOKEN',
  ],
]);
echo curl_exec($curl);
curl_close($curl);

Response

The response echoes the agent that created the group.

json

{
  "error": null,
  "data": {
    "success": true,
    "group_id": "1203630000000000@g.us",
    "group_name": "Match - Alice & Bob",
    "description": "Welcome to Migamatch",
    "members": ["+391234567890", "+391234567891"],
    "ai_agent": {
      "name": "My Agent",
      "instance_id": "696E3D600055",
      "phone": "+391234567899"
    },
    "created_at": "2026-02-07 10:32:58"
  }
}

POST /p/{regToken}/api_group/history

Get group chat history

Warning

PLATFORM TOKEN required — request it from your platform administrator. It is not shown in the customer dashboard. Where administrators find it.

Returns paginated group messages, with the filters you applied echoed back alongside the results.

Note

Older documentation shows this endpoint as a GET with query parameters. It is a POST, and the filters go in the JSON body.

Filters — all optional, but send at least one

group_id string Optional

Filter by group ID. Recommended over the name.

group_name string Optional

Filter by group name, which is mapped back to a group ID.

member_phone string Optional

Filter by sender, in +123… format.

from_date string (date) Optional

YYYY-MM-DD.

to_date string (date) Optional

YYYY-MM-DD.

search string Optional

Free-text search inside the messages.

page int Optional

Default 1.

limit int Optional

Default 50, maximum 200.

Request

One group, one week, paginated

bash

curl -X POST 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_group/history' \
  -H 'Content-Type: application/json' \
  -H 'X-Platform-Token: YOUR_PLATFORM_TOKEN' \
  -d '{
    "group_name": "Match - Alice & Bob",
    "from_date": "2026-02-01",
    "to_date":   "2026-02-07",
    "page": 1,
    "limit": 3
  }'

Response

Each record is one group message — text or media — with sender details, type and timestamps.

json

{
  "error": null,
  "data": {
    "success": true,
    "filters": {
      "group_name": null,
      "group_id": ["1203630000000000@g.us"],
      "member_phone": null,
      "from_date": "2026-02-01",
      "to_date": "2026-02-07",
      "search": null
    },
    "pagination": { "page": 1, "limit": 3, "total": 10 },
    "data": [
      {
        "migawhatsapp_group_chat_history_id": "1",
        "group_id": "1203630000000000@g.us",
        "group_name": "Sample Group",
        "message_id": "false_1203630000000000@g.us_MESSAGE_ID@lid",
        "sender_phone": "+391234567890",
        "sender_name": "User A",
        "message_text": "Hello world",
        "message_type": "chat",
        "media_proxy_url": null,
        "media_url": null,
        "sent_at": "2026-02-07 10:32:58",
        "raw_payload": "…",
        "created_at": "2026-02-07 10:32:58",
        "updated_at": "2026-02-07 10:32:58"
      }
    ]
  }
}

1 endpoint

Migachat Auto Setup

Provisioning the AI assistant on a line in one call — instance, credentials, prompt and every token you need afterwards.

What one POST does

Built for external systems — billing panels, CRMs — to stand up MigaChat inside a specific application and on a specific WhatsApp line without anyone opening the backoffice. A single request:

adds and activates the MigaChat feature in the app,
stores the OpenAI credentials (API key, organization ID, model),
injects the system prompt for the chatbot,
links the WhatsApp line to the MigaChat instance,
and returns the Bridge, Chat History and Send Message tokens.

POST /p/{regToken}/api_migachat-setup/setup

Provision MigaChat on a line

Creates and configures a MigaChat instance and binds it to a WhatsApp line.

Note

This endpoint is also reachable without the /p/<token>/ prefix, at /api_migachat-setup/setup. Both paths are live; on the prefixed one the registration token may come from the path instead of the body.

Required

app_id int Required

Your application ID.

security_token string Required

Your platform's security token.

line_id int Required

The WhatsApp line to link MigaChat to.

openai_api_key string Required

Your OpenAI secret key. It is validated against OpenAI before anything is saved.

organization_id string Required

Your OpenAI organization ID.

gpt_model string Required

The model to use, e.g. gpt-4o-mini.

prompt string Required

The system prompt — the chatbot's standing instructions.

Optional

chat_type string Optional

chatgpt (default) or assistant.

enable_stt int Optional

1 turns Speech-to-Text on. Default 0.

enable_tts int Optional

1 turns Text-to-Speech on. Default 0.

overwrite int Optional

1 replaces an existing MigaChat instance on this line. Default 0, which fails instead.

Errors5

MigaChat not installed

The MigaChat module is not installed on this server.

Invalid Line ID

That line_id does not belong to that app_id.

Already configured

The line already has a MigaChat instance. Send overwrite=1 to replace it.

Invalid OpenAI Key

The key could not be validated with OpenAI.

missing required fields: app_id, line_id, openai_api_key, …

The response names every mandatory field that was absent or empty.

Request

php

<?php
$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_migachat-setup/setup',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST  => 'POST',
  CURLOPT_POSTFIELDS => [
    'security_token'  => 'YOUR_API_TOKEN',
    'app_id'          => '123',
    'line_id'         => '456',
    'openai_api_key'  => 'sk-proj-YOUR_OPENAI_KEY',
    'organization_id' => 'org-YOUR_ORG_ID',
    'gpt_model'       => 'gpt-4o-mini',
    'prompt'          => 'You are a helpful customer support assistant...',
    'overwrite'       => '1',
  ],
]);
echo curl_exec($curl);
curl_close($curl);

json

{
  "security_token": "YOUR_API_TOKEN",
  "app_id": 123,
  "line_id": 456,
  "openai_api_key": "sk-proj-YOUR_OPENAI_KEY",
  "organization_id": "org-YOUR_ORG_ID",
  "gpt_model": "gpt-4o-mini",
  "prompt": "You are a helpful customer support assistant...",
  "enable_stt": 1,
  "enable_tts": 1
}

Response

Every token you need for the bridge, chat history and messaging comes back at once. chat_api_token and send_message_api_token are alternative field names for the same two values.

json

{
  "success": true,
  "app_id": 123,
  "line_id": 456,
  "migachat_instance_id": 789,
  "bridge_auth_token": "Xk9mNz4hPq…",
  "chat_history_token": "Lp3qRz9vWx…",
  "chat_api_token": "Lp3qRz9vWx…",
  "send_message_token": "Wz7tYp2mKn…",
  "send_message_api_token": "Wz7tYp2mKn…"
}