Registry /
communication / messaging-api-messenger
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MessengerClient
✓ import { MessengerClient } from 'messaging-api-messenger';
✗ const { MessengerClient } = require('messaging-api-messenger');
For modern Node.js and TypeScript projects, ESM named imports are preferred. The CommonJS `require` syntax is also supported but less idiomatic for type-aware tooling.
Message
✓ import type { Message } from 'messaging-api-messenger';
Commonly imported type for defining Messenger message objects. Use `import type` for type-only imports to avoid bundling issues.
MessengerError
✓ import { MessengerError } from 'messaging-api-messenger';
This is a custom error class that wraps Axios errors, providing structured error information. It extends `Error` and includes `request`, `response`, and `config` properties.
This quickstart demonstrates how to initialize the MessengerClient, send a basic text message, fetch a user's profile, and send a message with quick replies, incorporating environment variables for secure token handling and comprehensive error handling.
import { MessengerClient } from 'messaging-api-messenger';
// It is recommended to use environment variables for sensitive tokens
const ACCESS_TOKEN = process.env.MESSENGER_ACCESS_TOKEN ?? 'YOUR_ACCESS_TOKEN';
const APP_ID = process.env.MESSENGER_APP_ID ?? 'YOUR_APP_ID';
const APP_SECRET = process.env.MESSENGER_APP_SECRET ?? 'YOUR_APP_SECRET';
const USER_ID = process.env.MESSENGER_USER_ID ?? 'YOUR_USER_ID'; // Replace with a valid Messenger user ID
if (!ACCESS_TOKEN || !APP_ID || !APP_SECRET || !USER_ID) {
console.error('Please set MESSENGER_ACCESS_TOKEN, MESSENGER_APP_ID, MESSENGER_APP_SECRET, and MESSENGER_USER_ID environment variables.');
process.exit(1);
}
const client = new MessengerClient({
accessToken: ACCESS_TOKEN,
appId: APP_ID,
appSecret: APP_SECRET,
version: '6.0' // Explicitly specify the Graph API version
});
async function sendSampleMessages() {
try {
console.log('Sending a simple text message...');
const textResponse = await client.sendText(USER_ID, 'Hello from the Messenger API client!');
console.log('Text message sent successfully:', textResponse);
console.log('\nFetching user profile...');
const userProfile = await client.getUserProfile(USER_ID, { fields: ['first_name', 'last_name', 'profile_pic'] });
console.log('User Profile:', userProfile);
console.log('\nSending a message with quick replies...');
const quickReplyResponse = await client.sendText(USER_ID, 'Choose your favorite color:', {
quickReplies: [
{ contentType: 'text', title: 'Red', payload: 'RED_PAYLOAD' },
{ contentType: 'text', title: 'Blue', payload: 'BLUE_PAYLOAD' }
]
});
console.log('Quick reply message sent successfully:', quickReplyResponse);
} catch (error: any) {
console.error('\nAn error occurred during API interaction:');
if (error.response) {
console.error('Response data:', error.response.data); // Detailed error from Facebook API
console.error('Response status:', error.response.status);
} else if (error.request) {
console.error('No response received:', error.request);
} else {
console.error('Error message:', error.message);
}
console.error('Error stack:', error.stack);
}
}
sendSampleMessages();
Debug
Known issues
breakingVersion 1.0.0 introduced a significant breaking change: the entire project was rewritten in TypeScript, and all API methods now exclusively accept `camelCase` keys in their payloads instead of the previous `snake_case` keys. This change impacts all request bodies for API calls.fixReview your application's API payloads and update all keys from `snake_case` to `camelCase` to align with the new API signature. Refer to the official API document for updated parameter names.
affects: >=1.0.0
gotchaThe `MessengerClient` automatically includes `appsecret_proof` in all Graph API requests if an `appSecret` is provided during initialization. While this enhances security, developers expecting to manage this manually might be surprised. It can lead to authentication failures if `appSecret` is missing or invalid.fixEnsure a valid `appSecret` is always provided in the client configuration for secure requests. If `appsecret_proof` is not desired or causes issues (e.g., in a development environment without a proper app secret), explicitly set `skipAppSecretProof: true` in the `MessengerClient` options.
affects: >=0.1.0 (implicitly, as appsecret_proof is a general Messenger Platform feature)
gotchaError handling is implemented using `axios-error`, which wraps the underlying `axios` error instances. This means direct `axios` error properties (`error.response`, `error.request`, `error.config`) are still accessible, but the primary error object when caught might be an instance of `MessengerError` with custom formatting.fixWhen catching API call errors, be aware that the error object will be an instance of `MessengerError`. You can still access `error.response`, `error.request`, and `error.config` for detailed HTTP information, but `console.log(error)` will output a pre-formatted message. Destructure these properties explicitly if you need raw Axios error data.
affects: >=0.1.0
Errors
Common errors & fixes
Facebook Graph API Error: (#100) Invalid parameter: template_type is not allowed
Attempting to send an API request with `snake_case` keys (e.g., `template_type`) after upgrading to `v1.0.0` or later, which expects `camelCase` (e.g., `templateType`).
fixUpdate all payload keys in your API requests from `snake_case` to `camelCase`. For instance, change `template_type` to `templateType`, `quick_replies` to `quickReplies`, etc.
TypeError: MessengerClient is not a constructor
Cannot read properties of undefined (reading 'MessengerClient')
This typically occurs when attempting to use CommonJS `require` syntax in an ESM module context, or vice-versa, or attempting a default import where a named import is expected.
fixIf using modern Node.js or TypeScript, ensure you are using ESM named imports: `import { MessengerClient } from 'messaging-api-messenger';`. If strictly in a CommonJS environment, use `const { MessengerClient } = require('messaging-api-messenger');`. Error: Request failed with status code 400 (Bad Request) - Graph API returns 'Unsupported post request' or 'The 'appsecret_proof' field is required'
API request failing due to either an invalid or missing `appSecret` when `appsecret_proof` is enabled, or an improperly formatted request body that the Graph API rejects.
fixVerify that your `appSecret` is correct and provided during client initialization. If `appsecret_proof` is causing issues and you're in a non-production environment, consider setting `skipAppSecretProof: true` in the client options. Also, double-check your request payload for correctness and adherence to `camelCase` key requirements.
Audit
Dependencies
axiosrequiredHTTP client for making API requests, used for all underlying network communication.
axios-errorrequiredCustom error wrapper used to provide formatted error messages and access to underlying Axios error properties.