META Messenger API Documentation | JSON API, Webhooks & Error Codes

🚀 Overview

One JSON endpoint is used for all supported Messenger outbound types.

MESSAGE

Free-form text reply with optional URL preview.

FILE

Send one publicly accessible image or document URL.

TEMPLATE

Available only for accounts with an enabled Messenger template.

✅

A request is accepted only when the response has statusCode = 0 and a non-empty messageId. Do not rely on HTTP 200 alone.

🔗 API Endpoint

Send an HTTP POST request with a JSON body and UTF-8 encoding. Three endpoint URLs are provided — we recommend URL 1 for production, with URLs 2 and 3 as fallback if the primary is unavailable.

POSThttps://www.isms.com.my/isms_send_messenger.php

URL 1https://www.isms.com.my/isms_send_messenger.phpRecommended

URL 2https://smtpapi.vocotext.com/isms_send_messenger.php

URL 3https://smtpapi2.vocotext.com/isms_send_messenger.php

Setting	Value
Content-Type	application/json
Method	POST only
Encoding	UTF-8 JSON
Recipients	1 to 20 comma-separated PSIDs

🔐 Authentication

Every request includes both account login credentials and Messenger application credentials.

un / pwdYour account username and password.

AppId / AppSecretMessenger API credentials assigned to your registered Page.

FromThe Facebook Page ID registered under the same account.

agreedtermSend YES when API terms have not already been accepted.

🔒

Keep passwords and application secrets on your server. Never place them in browser JavaScript, mobile applications or public source repositories.

🧩 Request Parameters

Parameter names are case-sensitive.

Parameter	Type	Requirement	Description
AppId	String	REQUIRED	Messenger application ID supplied for the account.
AppSecret	String	REQUIRED	Messenger application secret.
un	String	REQUIRED	Account username. Main and authorised subuser credentials are supported.
pwd	String	REQUIRED	Account password.
agreedterm	String	CONDITIONAL	Use `YES` when API terms are not already accepted.
Type	Enum	REQUIRED	`message`, `file`, or `template`.
From	String	REQUIRED	Your registered Facebook Page ID.
To	String	REQUIRED	Customer PSID. For multiple recipients, separate up to 20 PSIDs with commas.
Message	String	CONDITIONAL	Text body. Required when `Type` is `message`.
fileUrl	String	CONDITIONAL	Public HTTPS URL of the file. Required when `Type` is `file`.
fileName	String	CONDITIONAL	Final file name shown to the customer, with the correct extension.
TemplateCode	String	CONDITIONAL	Enabled template code. Required when `Type` is `template`.

💬 Send Text

Set Type to message and provide the text body.

JSONText request

{
  "AppId":      "YOUR_APP_ID",
  "AppSecret":  "YOUR_APP_SECRET",
  "un":         "your_username",
  "pwd":        "your_password",
  "agreedterm": "YES",
  "Type":       "message",
  "From":       "379920865198163",
  "To":         "28493227163613907",
  "Message":    "Hello! Thanks for messaging our Page — how can we help?"
}

PHP example

PHPcURL send

<?php
$payload = json_encode([
    'AppId'      => 'YOUR_APP_ID',
    'AppSecret'  => 'YOUR_APP_SECRET',
    'un'         => 'your_username',
    'pwd'        => 'your_password',
    'agreedterm' => 'YES',
    'Type'       => 'message',
    'From'       => '379920865198163',
    'To'         => '28493227163613907',
    'Message'    => 'Hello from our Page!'
], JSON_UNESCAPED_UNICODE);

$ch = curl_init('https://www.isms.com.my/isms_send_messenger.php');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30
]);
$response = curl_exec($ch);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);

$result = json_decode($response, true);
if (($result['statusCode'] ?? null) === 0 && !empty($result['messageId'])) {
    echo 'Accepted: '.$result['messageId'];
} else {
    echo 'Not accepted: '.$response;
}
?>

📎 Send File

Set Type to file and provide a public HTTPS URL plus the final file name.

JSONFile request

{
  "AppId":       "YOUR_APP_ID",
  "AppSecret":   "YOUR_APP_SECRET",
  "un":          "your_username",
  "pwd":         "your_password",
  "agreedterm":  "YES",
  "Type":        "file",
  "From":        "379920865198163",
  "To":          "28493227163613907",
  "fileUrl":     "https://example.com/files/invoice.pdf",
  "fileName":    "invoice.pdf",
  "MessageType": "FILE"
}

⚠️

The remote file must be accessible without login, cookies or an expiring browser session. Keep the extension in fileName consistent with the actual file.

🧱 Template Mode

Use only when a Messenger template code has been enabled for the account.

JSONTemplate request

{
  "AppId":          "YOUR_APP_ID",
  "AppSecret":      "YOUR_APP_SECRET",
  "un":             "your_username",
  "pwd":            "your_password",
  "agreedterm":     "YES",
  "Type":           "template",
  "From":           "379920865198163",
  "To":             "28493227163613907",
  "TemplateCode":   "YOUR_TEMPLATE_CODE",
  "Language":       "en",
  "TemplateParams": [{ "name": "Customer" }]
}

ℹ️

If template mode is not enabled for your account, use normal text or file mode during the permitted customer reply window.

✅ Response Format

The endpoint returns the submission identifiers, accepted charge and currency.

JSONAccepted response

{
  "requestId":          "841c4247-6cb1-4d85-bf4c-b0084503ac86",
  "statusCode":         0,
  "messageId":          "2026071235388571360206848",
  "messageInstanceId":  "2026071235388571360206848",
  "charge":             "0.020",
  "currency":           "MYR"
}

Field	Description
requestId	Request trace identifier for support and troubleshooting.
statusCode	`0` means accepted. Any other value is not accepted.
messageId	Primary ID used to correlate delivery callbacks.
messageInstanceId	Additional submission identifier for diagnostics.
charge / currency	Credits charged for the accepted request. Failed requests return zero charge.

✅

Store messageId with your local record. Delivery callbacks use this value, which can differ from messageInstanceId.

❌ Error Codes

Validation errors may be returned as plain text, while Messenger-specific errors use JSON with resultCode and errorMessage.

HTTP and general errors

HTTP 400

Invalid JSON request body.

HTTP 405

Only POST requests are allowed.

-1001

Authentication failed.

-1002

Account suspended or expired.

-1003

Source IP address is not allowed.

-1008

A required parameter is missing.

-1010

More than 20 destination PSIDs were supplied.

-1013

API terms and agreement are not accepted.

Messenger errors

70600

Facebook Page is not registered or is inactive.

70601

Invalid Messenger application credentials.

70602

Insufficient Messenger credits.

70603

Invalid destination PSID.

70604

Unsupported message type.

70605

Messenger rate is not configured.

JSONMessenger error example

{
  "resultCode": 70603,
  "errorMessage": "Invalid Destination PSID"
}

📥 Inbound Message Webhook

Incoming customer messages are delivered to your configured webhook as a JSON array.

JSONText message

[{
  "From": "28493227163613907",
  "Message": "Hi",
  "MessageId": "2026071236821556319162368",
  "Timestamp": 1783992845172,
  "To": "379920865198163",
  "Type": "TEXT"
}]

FromCustomer PSID.

ToYour receiving Facebook Page ID.

MessageIdUnique inbound message identifier.

TimestampEvent time in epoch milliseconds.

TypeTEXT, IMAGE, VIDEO, AUDIO, FILE or another supported type.

MessageText content, or a JSON string containing media details.

Media Message field

JSON stringDecode Message again

"Message": "{\"filename\":\"photo.jpg\",\"animated\":false,\"url\":\"https://example.com/photo.jpg\"}"

⚠️

Use MessageId for idempotency. Webhook retries can deliver the same message more than once.

📬 Delivery Status Webhook

Outbound delivery updates use the same messageId returned by the send response.

JSONDelivered callback

[{
  "ConversationId": "123686334931625574494509",
  "From": "379920865198163",
  "MessageId": "2026071236863344861163520",
  "MsgFrameType": "message",
  "Status": "Delivered",
  "Timestamp": 1784002812674,
  "To": "28493227163613907",
  "Type": "TEXT"
}]

SentSubmission was sent for delivery.

DeliveredThe message reached the recipient.

FailedThe message could not be delivered. ErrorDescription may be included.

ℹ️

Meta Messenger does not provide a recipient read status. Integrations must not wait for or expect a Read callback.

🔁

Delivery callbacks are at-least-once and may repeat the same status. Deduplicate using Page ID, MessageId and Status, and never deduct credits again from a webhook.

🛡 Integration Best Practices

Validate acceptance

Require statusCode 0 and a messageId before marking a send accepted.

Make webhooks idempotent

Persist message IDs and ignore repeated inbound or delivery events.

Respond quickly

Return HTTP 200 promptly and process webhook business logic asynchronously when possible.

Protect credentials

Store secrets server-side and rotate them if exposed.

Do not alter PSIDs

Keep identifiers as strings; never apply telephone-number formatting.

Log correlation IDs

Store requestId, messageId, Page ID and recipient PSID for support.

META Messenger API